feat: AI documentation

.cursor/rules/architecture-docs.mdc

@@ -9,10 +9,10 @@ Before non-trivial code changes, read the repository architecture context:
 
 - `AGENTS.md`
 - `ARCHITECTURE.md`
-- `docs/architecture/architecture.json`
-- `docs/architecture/architecture.html` when a visual overview helps
+- `docs/architecture/architecture.html` when a visual graph or traversal overview helps
 - Relevant files under `docs/architecture/`
+- `source-research/research-index.md` and relevant source-research artifacts for architecture, dependency, public API, hook, transport, runtime-flow, build-variant, or broad code-generation work
 
-When a change affects module boundaries, public APIs, hook signatures, dependencies, data/control flow, transport behavior, runtime assumptions, or build/test strategy, update the closest relevant architecture docs in the same change. Keep the Markdown, JSON, and HTML architecture maps synchronized when applicable.
+When a change affects module boundaries, public APIs, hook signatures, dependencies, data/control flow, transport behavior, runtime assumptions, or build/test strategy, update the closest relevant architecture docs in the same change. Keep the Markdown docs and `docs/architecture/architecture.html` synchronized when applicable. Update `source-research/` when the same change affects source-derived behavior, dependencies, public APIs, hooks, runtime flow, build variants, or architecture claims.
 
 If no architecture doc update is needed, say so explicitly in the final response or PR notes.

.github/copilot-instructions.md

@@ -4,10 +4,10 @@ Before making non-trivial code changes in this repository, read:
 
 - `AGENTS.md`
 - `ARCHITECTURE.md`
-- `docs/architecture/architecture.json`
-- `docs/architecture/architecture.html` when a visual overview helps
+- `docs/architecture/architecture.html` when a visual graph or traversal overview helps
 - Relevant files under `docs/architecture/`
+- `source-research/research-index.md` and relevant source-research artifacts for architecture, dependency, public API, hook, transport, runtime-flow, build-variant, or broad code-generation work
 
-Keep architecture documentation current with code changes. Update the closest relevant architecture file when a change affects boundaries, public APIs, hook signatures, dependencies, data/control flow, transport behavior, runtime assumptions, or build/test strategy. Keep the Markdown, JSON, and HTML architecture maps synchronized when applicable.
+Keep architecture documentation current with code changes. Update the closest relevant architecture file when a change affects boundaries, public APIs, hook signatures, dependencies, data/control flow, transport behavior, runtime assumptions, or build/test strategy. Keep the Markdown docs and `docs/architecture/architecture.html` synchronized when applicable. Update `source-research/` when the same change affects source-derived behavior, dependencies, public APIs, hooks, runtime flow, build variants, or architecture claims.
 
 If a change is implementation-only and does not require architecture doc updates, mention that explicitly in PR notes.

.github/workflows/ci.yml

@@ -75,10 +75,16 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Check embedded architecture graph data
+      - name: Check architecture docs do not reference removed JSON map
         run: |
-          node docs/architecture/embed-architecture-json.mjs
-          git diff --exit-code docs/architecture/architecture.html
+          architecture_json_pattern='architecture[.]''json'
+          embed_script_pattern='embed-architecture''-json'
+          for pattern in "$architecture_json_pattern" "$embed_script_pattern"; do
+            ! grep -R "$pattern" \
+              AGENTS.md ARCHITECTURE.md CLAUDE.md GEMINI.md \
+              .github/copilot-instructions.md .cursor/rules/architecture-docs.mdc \
+              docs
+          done
 
   build_docs:
     runs-on: ubuntu-latest

AGENTS.md

@@ -5,17 +5,53 @@ This repository uses living architecture documentation. Treat architecture docs
 Before non-trivial code changes:
 
 1. Read `ARCHITECTURE.md`.
-2. Read `docs/architecture/architecture.json` for the structured map.
-3. Read `docs/architecture/architecture.html` when a visual overview helps.
-4. Read any other relevant files under `docs/architecture/`.
+2. Read `docs/architecture/architecture.html` when a visual graph or traversal overview helps.
+3. Read any other relevant files under `docs/architecture/`.
+4. Read `source-research/research-index.md` and the relevant source-research artifacts described below when the change involves architecture, inter-module dependencies, public APIs, hooks, transports, build variants, runtime flow, or broad code generation.
 5. Check `README.md` and tests relevant to the behavior being changed.
 
+After every non-trivial code change, explicitly evaluate both maintenance surfaces:
+
+1. Architecture docs: update `ARCHITECTURE.md` and `docs/architecture/` when the change affects system shape, flow, boundaries, dependencies, public APIs, runtime model, or testing strategy.
+2. Source research: update `source-research/` when the change affects source-derived behavior, dependencies, public APIs, hooks, runtime flow, build variants, or architecture claims.
+
+If either surface is not affected, say so explicitly in the final response or PR notes.
+
+## Source Research Artifacts
+
+This repository includes durable source-derived research under `source-research/`. Use these artifacts as required orientation and impact-analysis context for architecture questions, dependency analysis, public API changes, hook/transport changes, runtime-flow changes, build/test strategy changes, and broad code-generation or refactoring work.
+
+Start with:
+
+1. `source-research/research-index.md`
+2. `source-research/overview.md`
+3. `source-research/inventory/symbol-index.json`
+4. `source-research/inventory/dependency-graph.json`
+5. `source-research/inventory/claims-ledger.json`
+6. Relevant node artifacts under `source-research/artifacts/`
+
+Use `source-research` to identify relevant symbols, callers, callees, aliases/macros, module boundaries, public surfaces, finalized claims, and known build/configuration variants. Then read the implementation source before making or asserting behavior changes.
+
+Source files remain authoritative. If source and `source-research` disagree, trust source and update or mark the affected research artifacts stale. If source-research prose and machine-readable JSON disagree, prefer the current JSON and repair stale prose. Use only finalized/source-backed claims as established facts; treat preliminary, stale, or inferred claims as leads to verify in source.
+
+When code changes affect behavior, dependencies, public APIs, hooks, runtime flow, build variants, or architecture claims, update the relevant `source-research` artifacts in the same change. Prefer the `source-first-repo-research` SKILL tools when available:
+
+- Run lifecycle and evidence refreshes after artifact updates:
+  - `research_lifecycle.py analyze source-research --write`
+  - `research_lifecycle.py evidence source-research --write`
+  - `validate_research.py source-research`
+- For finalized create-complete validation, run `validate_research.py source-research --final-response`.
+- For C/C++ graph-impacting changes, rerun `cmake_ast_validate.py` against the relevant compile database, review unresolved edge candidates, and merge source-confirmed repairs with `graph_edge_upsert.py`.
+- Do not edit dependency graph facts only in prose. Update canonical JSON artifacts and validate them.
+- If the SKILL tools are unavailable, make the source-research update manually from source evidence and state the validation limitation in the final response or PR notes.
+
 When you change architecture-relevant behavior:
 
 - Update the closest relevant `ARCHITECTURE.md` or `docs/architecture/*.md` file.
-- Keep `docs/architecture/architecture.json` and `docs/architecture/architecture.html` synchronized with the Markdown architecture docs.
+- Keep `docs/architecture/architecture.html` synchronized with the Markdown architecture docs and the current source-research evidence.
 - Add or update an ADR under `docs/architecture/decisions/` when the change records a durable design decision or tradeoff.
+- Update `source-research/` when the same change affects source-derived behavior, dependencies, public APIs, hooks, runtime flow, build variants, or architecture claims.
 - Keep docs factual and current. Remove stale statements instead of adding contradictory notes.
-- If no architecture doc update is needed, mention that explicitly in your final response or PR notes.
+- Apply the two-surface maintenance check above after every non-trivial code change.
 
 `note-c` is a portable C SDK. Keep platform-specific behavior behind hooks or in adapter libraries unless the public architecture intentionally changes.

ARCHITECTURE.md

@@ -4,8 +4,22 @@ This file is the architecture entrypoint for `note-c`. Keep it current when code
 
 Companion architecture artifacts:
 
-- `docs/architecture/architecture.html`: human-readable visual architecture map.
-- `docs/architecture/architecture.json`: structured architecture map for AI agents and tooling.
+- `docs/architecture/architecture.html`: human-readable graph traversal view.
+- `source-research/`: source-derived structured evidence for symbols, dependencies, claims, and build variants.
+
+## How To Use This File
+
+`ARCHITECTURE.md` is the curated architecture entrypoint. It describes the intended system shape, durable boundaries, public contracts, runtime model, portability constraints, and testing strategy that maintainers should preserve when changing `note-c`.
+
+For source-backed implementation evidence, use `source-research/`:
+
+- `source-research/research-index.md`: re-entry point and validation status.
+- `source-research/overview.md`: source-derived system summary.
+- `source-research/inventory/dependency-graph.json`: caller/callee and dependency graph.
+- `source-research/inventory/symbol-index.json`: symbol and artifact lookup.
+- `source-research/inventory/claims-ledger.json`: finalized source-backed claims.
+
+Use this file to understand what the architecture is meant to be. Use `source-research/` to verify how the current source implements it and to scope impact before code changes. Source remains authoritative: if implementation, `source-research/`, and architecture docs disagree, inspect the source, then update the stale architecture or research artifact in the same change.
 
 ## Purpose
 
@@ -17,10 +31,10 @@ Companion architecture artifacts:
 
 - `note.h`: public SDK API, version constants, hook typedefs, request helpers, and compatibility surface.
 - `n_lib.h`: internal declarations shared across implementation files.
-- `n_request.c`: request/response lifecycle, transaction orchestration, and high-level Notecard communication behavior.
-- `n_serial.c`: serial transport implementation and chunked serial transmit/receive behavior.
-- `n_i2c.c`: I2C transport implementation and chunked I2C transmit/receive behavior.
-- `n_hooks.c`: registration and invocation of platform hooks for memory, time, mutexes, debug output, and transports.
+- `n_request.c`: request/response lifecycle, transaction orchestration, retry/timeout behavior, and request ownership boundaries.
+- `n_serial.c`: serial transport implementation and chunked newline-framed serial transmit/receive behavior.
+- `n_i2c.c`: I2C transport implementation and chunked newline-framed I2C transmit/receive behavior.
+- `n_hooks.c`: global function-pointer hook registry, active-interface dispatch, and invocation of platform hooks for memory, time, mutexes, debug output, and transports.
 - `n_cjson.c`, `n_cjson.h`, `n_cjson_helpers.c`: bundled JSON representation and helper APIs.
 - `n_helpers.c`, `n_str.c`, `n_printf.c`, `n_atof.c`, `n_ftoa.c`, `n_b64.c`, `n_cobs.c`, `n_md5.c`, `n_const.c`, `n_ua.c`: portability helpers, encoding, formatting, constants, and utility behavior.
 - `test/`: unit tests and mocks for protecting SDK behavior without requiring real hardware.
@@ -50,16 +64,20 @@ platform driver / hardware bus
 Notecard
 ```
 
-Applications normally build requests as `J` objects, send them through `NoteRequest`, `NoteRequestResponse`, or higher-level helpers, then release responses through the JSON/delete APIs. Transport and platform behavior is supplied through hooks so the same core code can run on microcontrollers, embedded Linux, tests, and other C/C++ environments.
+Applications normally build requests as `J` objects, send them through `NoteRequest`, `NoteRequestResponse`, retrying variants, or higher-level helpers, then release returned responses through the JSON/delete APIs. The consuming request wrappers delete the input request object after transaction; lower-level `NoteTransaction` paths leave request ownership with the caller. `NoteRequestResponseJSON` is a separate raw newline-delimited JSON string path with caller-owned request and response strings.
+
+Transport and platform behavior is supplied through hooks so the same core code can run on microcontrollers, embedded Linux, tests, and other C/C++ environments. Serial and I2C transports move raw newline-framed bytes through hook dispatch. Binary payload helpers, not the transport implementations, own COBS framing and MD5 verification.
 
 ## Public Contracts
 
 The main compatibility contracts are:
 
 - Public functions, typedefs, constants, and macros in `note.h`.
 - JSON object behavior exposed through `J` and helper functions.
+- Request/response ownership semantics for public transaction APIs.
 - Hook signatures for serial, I2C, memory, mutex, time, and debug output.
 - Notecard request/response semantics and timeout/retry behavior.
+- Build configuration behavior for low-memory, single-precision, user-agent, CRC, and portability-helper variants.
 - Version constants and release expectations documented in `README.md`.
 
 Breaking changes to these contracts require deliberate versioning, migration notes, and architecture documentation updates.
@@ -68,10 +86,14 @@ Breaking changes to these contracts require deliberate versioning, migration not
 
 `note-c` is intentionally self-contained and portable. It vendors the JSON implementation and avoids mandatory platform runtime dependencies. Adapter repositories may embed or wrap this repository, including `note-arduino`, `note-zephyr`, `note-espidf`, and POSIX-focused integrations.
 
+Build configuration is part of the portability model. CMake detects platform `strlcpy`/`strlcat` support and only includes bundled `n_str.c` helpers when needed. Low-memory builds disable user-agent support and request CRC paths, omit `n_ua.c`, use compact error/log constants, and reduce allocation chunk size.
+
 ## Runtime Model
 
 At runtime, host code initializes the relevant hooks, constructs Notecard requests, and calls `note-c` APIs. `note-c` serializes requests, sends bytes through the selected hook-backed transport, parses responses, and returns JSON objects or status to the caller.
 
+Hook state is global to the SDK instance. Hook registration stores caller-owned function pointers, and `_noteSetActiveInterface` selects the active serial or I2C dispatch table. Mutex hooks are optional: many hook setters/getters and transport paths use the internal lock macros when available, but not every hook accessor is lock-protected.
+
 Unit tests use mocks to validate behavior without hardware. Hardware validation may be performed through adapter libraries or Notestation-backed workflows when bus-level or device-level behavior matters.
 
 ## Testing Strategy
@@ -91,4 +113,4 @@ Update this file or `docs/architecture/` when a change affects:
 - Cross-repo expectations for adapter libraries.
 - Build, test, CI, release, or versioning strategy.
 
-When updating architecture, keep this Markdown overview, `docs/architecture/architecture.html`, and `docs/architecture/architecture.json` consistent.
+When updating architecture, keep this Markdown overview, `docs/architecture/architecture.html`, and relevant `source-research/` artifacts consistent with the source.

CLAUDE.md

@@ -1,15 +1,19 @@
 # Claude Instructions
 
-This repository uses living architecture documentation. Treat these files as required context, the same way you would treat README files.
+`AGENTS.md` is the canonical repository instruction file. Read it first and follow its architecture-documentation and `source-research/` requirements.
 
 Before non-trivial code changes:
 
 1. Read `AGENTS.md` for repository operating rules.
 2. Read `ARCHITECTURE.md`.
-3. Read `docs/architecture/architecture.json` for the structured map.
-4. Read `docs/architecture/architecture.html` when a visual overview helps.
-5. Read relevant files under `docs/architecture/`.
+3. Read `docs/architecture/architecture.html` when a visual graph or traversal overview helps.
+4. Read relevant files under `docs/architecture/`.
+5. Read `source-research/research-index.md` and the relevant source-research artifacts named in `AGENTS.md` when the task involves architecture, dependencies, public APIs, hooks, transports, runtime flow, build variants, or broad code generation.
 
-When a change affects architecture, update the docs in the same change, including `ARCHITECTURE.md`, `docs/architecture/architecture.json`, and `docs/architecture/architecture.html` when applicable. Architecture-relevant changes include module boundaries, public APIs, hook signatures, dependencies, data/control flow, transport behavior, runtime assumptions, and build/test strategy.
+When a change affects architecture, update the docs in the same change, including `ARCHITECTURE.md`, `docs/architecture/architecture.html`, and relevant files under `docs/architecture/` when applicable. Architecture-relevant changes include module boundaries, public APIs, hook signatures, dependencies, data/control flow, transport behavior, runtime assumptions, and build/test strategy.
 
-If no architecture doc update is needed, say that explicitly in your final response or PR notes.
+When a change affects source-derived behavior, dependencies, public APIs, hooks, runtime flow, build variants, or architecture claims, update `source-research/` and validate it with the `source-first-repo-research` SKILL tools when available.
+
+After every non-trivial code change, explicitly evaluate both maintenance surfaces: architecture docs and `source-research/`.
+
+If no architecture doc or source-research update is needed, say that explicitly in your final response or PR notes.