ESTOS · JanFellner · Jul 6, 2026 · Jul 1, 2026 · Jul 1, 2026 · Jul 1, 2026
diff --git a/.cursor/rules/documentation-routing.mdc b/.cursor/rules/documentation-routing.mdc
@@ -0,0 +1,17 @@
+---
+description: Use esnacc documentation routing metadata before broad code search
+alwaysApply: true
+---
+
+# Documentation routing
+
+Before investigating this repository, read [AGENTS.md](AGENTS.md) at the repository root.
+
+When a markdown file has YAML front matter with `read_when`, `entry_for`, or `related_docs`:
+
+1. Search routed docs first: `rg -l "^read_when:" --glob "*.md"`
+2. Open docs whose `read_when` or `entry_for` matches the task.
+3. Follow `related_docs` links before exploring unrelated directories.
+4. Use `scope` to stay inside the correct subsystem (`compiler/`, `cpp-lib/`, `samples/`, etc.).
+
+For compiler or codegen work, confirm the target language under `compiler/back-ends/` and check `samples/` for exercised behavior. TypeScript and C++ are the primary maintained targets.
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,104 @@
+# Agent guide for estos esnacc
+
+This repository is the **estos enhanced SNACC ASN.1 compiler** (`esnacc`). It parses ASN.1 modules and generates target-language stubs, runtime helpers, and protocol documentation.
+
+Read this file first. Then follow the documentation routing metadata in markdown files across the repo.
+
+## Documentation routing
+
+Several markdown files begin with YAML front matter:
+
+```yaml
+---
+title: ...
+scope: ...
+owner_repo: esnacc
+entry_for: [...]
+purpose: ...
+read_when: [...]
+related_docs: [...]
+---
+```
+
+Use that metadata to choose docs before searching code at random:
+
+1. Match the user task to `read_when` or `entry_for`.
+2. Read `purpose` to confirm relevance.
+3. Follow `related_docs` for the next file.
+4. Respect `scope` — stay inside the described subsystem unless the task clearly spans repos.
+
+Discover routed docs:
+
+```bash
+rg -l "^read_when:" --glob "*.md"
+```
+
+## Repository map
+
+| Path | What it is | When to work here |
+|------|------------|-------------------|
+| `compiler/` | ASN.1 parser, core compiler, CLI | Compiler behavior, CLI flags, parsing, shared codegen |
+| `compiler/back-ends/` | Per-language code generators (`ts-gen`, `c++-gen`, `c-gen`, `cs-gen`, …) | Generated output for a specific target language |
+| `cpp-lib/` | C++ runtime library (`esnacc_cpp_lib`) | BER/JSON codecs, ROSE runtime, C++ consumer APIs |
+| `c-lib/` | C runtime support | C target runtime and helpers |
+| `ROSE/` | ROSE-related shared material | ROSE protocol/client-server concerns |
+| `samples/` | End-to-end usage examples | Verifying generation, integration patterns, sample apps |
+| `samples/ts-microservice/` | Main TypeScript sample (server, client, browser, OpenAPI) | TypeScript ROSE/REST/WebSocket workflows |
+
+Build outputs default under `output/` (compiler binary, libraries).
+
+## Primary maintained targets
+
+TypeScript and C++ have the fullest feature set:
+
+- structure definitions
+- JSON and BER encoders/decoders
+- ROSE client/server stubs
+
+Other backends (C, C#, Java, Kotlin, Swift, Delphi, JavaScript, IDL, JSDoc, OpenAPI) vary in completeness. Check the matching directory under `compiler/back-ends/` and treat samples as the source of truth for what is actually exercised.
+
+## Routed documentation index
+
+| Doc | Use when |
+|-----|----------|
+| [ReadMe.md](ReadMe.md) | Build instructions, repo overview, supported targets |
+| [FAQ.md](FAQ.md) | Compiler background, licensing, capability questions |
+| [samples/readme.md](samples/readme.md) | Running or updating samples |
+| [samples/ts-microservice/readme.md](samples/ts-microservice/readme.md) | TypeScript microservice layout and verification flow |
+| [samples/ts-microservice/node-server/README.md](samples/ts-microservice/node-server/README.md) | Node server handlers, config, generated stub usage |
+| [cpp-lib/tests/runtime_correctness_notes.md](cpp-lib/tests/runtime_correctness_notes.md) | Intended C++ runtime semantics and correctness tests |
+
+## Typical task routing
+
+| Task | Start here | Then inspect |
+|------|------------|--------------|
+| Change TypeScript generation | `ReadMe.md`, `compiler/back-ends/ts-gen/` | `samples/ts-microservice/` |
+| Change C++ generation or runtime | `ReadMe.md`, `cpp-lib/tests/runtime_correctness_notes.md` | `compiler/back-ends/c++-gen/`, `cpp-lib/` |
+| Add/fix a sample | `samples/readme.md` | The specific sample subdirectory |
+| Build or CI for the compiler | `ReadMe.md` | `compiler/CMakeLists.txt`, root `CMakeLists.txt` |
+| OpenAPI / JSDoc output | `FAQ.md` | `compiler/back-ends/openapi-gen/`, `compiler/back-ends/jsondoc-gen/` |
+
+## Build quick reference
+
+From repo root:
+
+```shell
+mkdir build
+cd build
+cmake ..
+cmake --build .
+```
+
+Requirements and IDE-specific steps are in [ReadMe.md](ReadMe.md). CMake minimum version: 3.20.
+
+## Working conventions
+
+- Preserve existing line endings and formatting in edited files.
+- Prefer the smallest correct change; match surrounding code style.
+- Generated output shape is defined by ASN.1 inputs plus the relevant `compiler/back-ends/*-gen` implementation — read both before changing behavior.
+- When documentation and code disagree, verify against `samples/` and tests before updating docs.
+
+## Related repositories
+
+- [esnacc-openapi-sdk](https://github.com/ESTOS/esnacc-openapi-sdk) — Swagger UI integration for generated OpenAPI output
+- Consumer projects may vendor generated stubs or runtime libraries built from this repo; confirm the target repo before assuming shared release layout
diff --git a/FAQ.md b/FAQ.md
@@ -1,3 +1,21 @@
+---
+title: estos-esnacc FAQ
+scope: estos-esnacc
+owner_repo: esnacc
+entry_for:
+  - ASN.1 compiler background
+  - supported target languages
+  - licensing questions
+purpose: Answer common questions about the enhanced ASN.1 compiler, supported targets, and licensing.
+read_when:
+  - Investigating compiler capabilities or project background
+  - Updating generated target language or licensing documentation
+related_docs:
+  - AGENTS.md
+  - ReadMe.md
+  - samples/readme.md
+---
+
 Frequently Asked Questions
 ==========================
 
@@ -30,16 +48,29 @@ A: estos eSNACC is the estos enhanced Sample Neufeld ASN.1 C Compiler.  It is a
 	* Structure definitions
 	* JSON and BER encoder/decoders
 	* ROSE client/server implementation (complete stubs)
+  * C
+	* Structure definitions
+	* BER encoder/decoders
+  * C#
+	* Structure definitions
   * Delphi
 	* Structure definitions
   * JAVA
 	* Structure definitions
+  * Kotlin
+	* Structure definitions
   * JavaScript JSON
 	* Structure definitions
+  * JavaScript ES6
+	* Structure definitions
   * SWIFT
 	* Structure definitions
+  * IDL
+	* Interface definitions
   * JSDOC
 	* JSON formatted Documentation generated based on the documentation inside the asn1 files
+  * OpenApi
+	* OpenApi JSON documentation generated based on documentation inside the ASN.1 files
 
 ### Q: What versions of ASN.1 does the estos eSNACC interoperate with?
 
@@ -50,8 +81,8 @@ A: The estos eSNACC can support most of X.608/X.609 for Basic Encoding Rules.  S
 
 ### Q: Which programming languages does the estos eSNACC target?
 
-A: Currently, the estos eSNACC mainly targets C++ and typescript but other languages are also supported.
-   Check the compiler back-ends directory for the currently adresses languages.
+A: Currently, the estos eSNACC mainly targets C++ and Typescript but other languages are also supported.
+   Check the compiler back-ends directory for the currently addressed languages.
    However the different languages may not support the full featureset like the c++ and typescript implementation.
 
 

diff --git a/ReadMe.md b/ReadMe.md
@@ -1,9 +1,32 @@
+---
+title: estos Enhanced Sample Neufeld ASN C Compiler
+scope: estos-esnacc
+owner_repo: esnacc
+entry_for:
+  - ASN.1 compiler development
+  - target-language code generation
+  - protocol documentation generation
+purpose: Explain how to build and use the enhanced ASN.1 compiler and its generated targets.
+read_when:
+  - Changing compiler behavior or generated output
+  - Updating build instructions
+  - Investigating TypeScript, C++, C, C#, Java, Kotlin, Swift, JSDoc, IDL, or OpenAPI generation
+related_docs:
+  - AGENTS.md
+  - FAQ.md
+  - samples/readme.md
+  - cpp-lib/tests/runtime_correctness_notes.md
+---
+
 # estos Enhanced Sample Neufeld ASN C Compiler
 This is the estos enhanced sample neufeld asn c compiler. 
 It is an functional enriched fork of the original enhanced sample neufeld asn c compiler offering:
 * Documented source code, based on the documentation from the asn1 source files
 * Creating documentation based on the documentation from the asn1 source files
 * Additional supported target languages
+  * C
+    * Structure definitions
+    * BER encoder/decoders
   * Typescript (main maintained language)
     * Structure definitions
     * JSON and BER encoder/decoders
@@ -13,14 +36,22 @@ It is an functional enriched fork of the original enhanced sample neufeld asn c
     * Structure definitions
     * JSON and BER encoder/decoders
     * ROSE client/server implementation (complete stubs)
+  * C#
+    * Structure definitions
   * Delphi
     * Structure definitions
   * JAVA
     * Structure definitions
+  * Kotlin
+    * Structure definitions
   * JavaScript JSON
     * Structure definitions
+  * JavaScript ES6
+    * Structure definitions
   * SWIFT
     * Structure definitions
+  * IDL
+    * Interface definitions
   * JSDOC
     * JSON formatted Documentation generated based on the documentation inside the asn1 files
   * OpenApi
@@ -34,14 +65,17 @@ Those two languages offer JSON and BER encoding for the transport layer, a compl
 Other languages just offer to get created structures which need to get serialized / deserialized in JSON with other functions of the language.
 
 # Getting started
+Agents and contributors: start with [AGENTS.md](AGENTS.md) for repository routing and task-specific documentation entry points.
+
 You need to compile the compiler or use a precompiled version of it.
 The samples folder offers examples on the usage for the different supported languages. These folders show some sample asn1 files, the command line and the expected output of the compiler.
+See [samples/readme.md](samples/readme.md) for the current TypeScript microservice sample layout and required Node/pnpm setup.
 
 # Building the compiler
 ## Prerequesites to compile the compiler
 * Have cmake installed 
   * https://cmake.org
-  * at least V3.21
+  * at least V3.20
   * available in the path
 
 ## Command line

diff --git a/cpp-lib/tests/runtime_correctness_notes.md b/cpp-lib/tests/runtime_correctness_notes.md
@@ -1,3 +1,20 @@
+---
+title: C++ Runtime Correctness Notes
+scope: cpp-lib/tests
+owner_repo: esnacc
+entry_for:
+  - C++ runtime behavior
+  - runtime correctness tests
+  - ROSE telemetry and shutdown semantics
+purpose: Record intended C++ runtime semantics before tests or implementation are tightened.
+read_when:
+  - Changing cpp-lib runtime behavior, telemetry, shutdown, or decode-error handling
+  - Adding or reviewing runtime correctness tests
+related_docs:
+  - ../../AGENTS.md
+  - ../../ReadMe.md
+---
+
 # Runtime Correctness Notes
 
 This note records the intended semantics for selected `cpp-lib` runtime behaviors

diff --git a/samples/readme.md b/samples/readme.md
@@ -1,3 +1,21 @@
+---
+title: esnacc Samples Overview
+scope: samples
+owner_repo: esnacc
+entry_for:
+  - sample applications
+  - TypeScript microservice sample
+  - generated runtime code examples
+purpose: Route readers to the sample projects that demonstrate generated esnacc code.
+read_when:
+  - Running or updating esnacc samples
+  - Changing TypeScript sample package layout or integration-test flow
+related_docs:
+  - ../AGENTS.md
+  - ../ReadMe.md
+  - ts-microservice/readme.md
+---
+
 # Samples
 This folder contains samples that show how to use the snacc compiler and the generated runtime code.
 

diff --git a/samples/ts-microservice/node-server/README.md b/samples/ts-microservice/node-server/README.md
@@ -1,3 +1,20 @@
+---
+title: TypeScript Node Server Sample
+scope: samples/ts-microservice/node-server
+owner_repo: esnacc
+entry_for:
+  - TypeScript ROSE server sample
+  - Express REST and WebSocket handlers
+  - generated server stub usage
+purpose: Document the Node server package used by the TypeScript microservice sample.
+read_when:
+  - Updating node-server handlers, configuration, generated stubs, or integration-test behavior
+related_docs:
+  - ../../../AGENTS.md
+  - ../readme.md
+  - ../../readme.md
+---
+
 # estos NodeJS server sample (`node-server`)
 
 [TOC]

diff --git a/samples/ts-microservice/readme.md b/samples/ts-microservice/readme.md
@@ -1,3 +1,21 @@
+---
+title: TypeScript Microservice Sample
+scope: samples/ts-microservice
+owner_repo: esnacc
+entry_for:
+  - TypeScript generated stubs
+  - Node server and client integration tests
+  - browser demo and OpenAPI sample
+purpose: Explain the TypeScript microservice sample layout, preparation steps, and verification flow.
+read_when:
+  - Updating TypeScript code generation samples
+  - Running node-server, node-client, browser-client, or OpenAPI examples
+related_docs:
+  - ../../AGENTS.md
+  - ../readme.md
+  - node-server/README.md
+---
+
 # Typescript based microservice sample
 This sample shows how generated TypeScript ASN.1 stubs are used end-to-end: a Node server, a browser demo, and automated integration tests.