docs: add living architecture guidance

.cursor/rules/architecture-docs.mdc

@@ -0,0 +1,18 @@
+---
+description: Keep architecture documentation current with code changes
+globs:
+  - "**/*"
+alwaysApply: true
+---
+
+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
+- Relevant files under `docs/architecture/`
+
+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.
+
+If no architecture doc update is needed, say so explicitly in the final response or PR notes.

.github/copilot-instructions.md

@@ -0,0 +1,13 @@
+# Copilot Instructions
+
+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
+- Relevant files under `docs/architecture/`
+
+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.
+
+If a change is implementation-only and does not require architecture doc updates, mention that explicitly in PR notes.

.github/workflows/ci.yml

@@ -68,6 +68,18 @@ jobs:
           name: note_c_ci_image
           path: /tmp/note_c_ci_image.tar
 
+  check_architecture_docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Check embedded architecture graph data
+        run: |
+          node docs/architecture/embed-architecture-json.mjs
+          git diff --exit-code docs/architecture/architecture.html
+
   build_docs:
     runs-on: ubuntu-latest
     if: ${{ always() }}

AGENTS.md

@@ -0,0 +1,21 @@
+# Agent Instructions
+
+This repository uses living architecture documentation. Treat architecture docs like README docs: if a code change changes the shape, flow, boundaries, dependencies, public APIs, runtime model, or testing strategy, update the architecture docs in the same change.
+
+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/`.
+5. Check `README.md` and tests relevant to the behavior being changed.
+
+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.
+- Add or update an ADR under `docs/architecture/decisions/` when the change records a durable design decision or tradeoff.
+- 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.
+
+`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

@@ -0,0 +1,94 @@
+# note-c Architecture
+
+This file is the architecture entrypoint for `note-c`. Keep it current when code changes alter system boundaries, public contracts, transport behavior, build/test strategy, or cross-repo expectations.
+
+Companion architecture artifacts:
+
+- `docs/architecture/architecture.html`: human-readable visual architecture map.
+- `docs/architecture/architecture.json`: structured architecture map for AI agents and tooling.
+
+## Purpose
+
+`note-c` is the portable C SDK for communicating with a Blues Notecard over serial or I2C. It owns the core request/response model, bundled JSON helpers, protocol framing, transport orchestration, and hook-based platform abstraction.
+
+`note-c` should remain platform-neutral. Platform-specific I/O, memory, timing, mutex, and logging behavior belongs behind hooks or in adapter libraries such as `note-arduino`, `note-posix`, `note-zephyr`, or `note-espidf`.
+
+## Major Components
+
+- `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_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.
+- `scripts/`: local automation for checks, documentation, and release support.
+
+## Data and Control Flow
+
+```text
+application or adapter library
+        |
+        v
+public API in note.h
+        |
+        v
+request/response and JSON helpers
+        |
+        v
+transport selection and chunking
+        |
+        v
+registered serial or I2C hook
+        |
+        v
+platform driver / hardware bus
+        |
+        v
+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.
+
+## 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.
+- Hook signatures for serial, I2C, memory, mutex, time, and debug output.
+- Notecard request/response semantics and timeout/retry behavior.
+- Version constants and release expectations documented in `README.md`.
+
+Breaking changes to these contracts require deliberate versioning, migration notes, and architecture documentation updates.
+
+## Dependencies
+
+`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.
+
+## 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.
+
+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
+
+Use the existing unit test suite for core request, JSON, hook, and transport behavior. Add or update tests when a change affects public APIs, retry/timeout behavior, memory ownership, transport chunking, or edge cases that can regress across adapter repositories.
+
+Before heavy Docker-based test runs in the OpenClaw workspace, follow the resource policy in the workspace `AGENTS.md` and run the resource check first.
+
+## Update Triggers
+
+Update this file or `docs/architecture/` when a change affects:
+
+- Public APIs or hook signatures.
+- Transport framing, chunking, timeout, retry, or request lifecycle behavior.
+- Memory ownership or allocation strategy.
+- JSON representation or helper semantics.
+- 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.

CLAUDE.md

@@ -0,0 +1,15 @@
+# Claude Instructions
+
+This repository uses living architecture documentation. Treat these files as required context, the same way you would treat README files.
+
+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/`.
+
+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.
+
+If no architecture doc update is needed, say that explicitly in your final response or PR notes.

GEMINI.md

@@ -0,0 +1,13 @@
+# Gemini Instructions
+
+This repository uses living architecture documentation. Treat these files as required context before non-trivial code changes:
+
+1. `AGENTS.md`
+2. `ARCHITECTURE.md`
+3. `docs/architecture/architecture.json`
+4. `docs/architecture/architecture.html` when a visual overview helps
+5. Relevant files under `docs/architecture/`
+
+When a change affects module boundaries, public APIs, hook signatures, dependencies, data/control flow, transport behavior, runtime assumptions, or build/test strategy, update the architecture docs in the same change, including the Markdown, JSON, and HTML architecture maps when applicable.
+
+If no architecture doc update is needed, say so explicitly in the final response or PR notes.

docs/architecture/README.md

@@ -0,0 +1,55 @@
+# Living Architecture Documentation
+
+Architecture docs are maintained with the code. Future agents and humans should be able to read these files before changing `note-c` and quickly understand the current system shape, boundaries, and tradeoffs.
+
+## Rules for Agents
+
+Before non-trivial code changes:
+
+1. Read the nearest applicable `AGENTS.md`, `CLAUDE.md`, or equivalent tool instruction file.
+2. Read `ARCHITECTURE.md`.
+3. Read relevant files under `docs/architecture/`.
+
+After code changes:
+
+- Update architecture docs when behavior, boundaries, dependencies, APIs, data flow, runtime topology, or testing strategy changes.
+- Add an ADR for durable decisions that future maintainers should understand.
+- Keep docs concise and factual. Prefer diagrams and lists over prose walls.
+- Delete or rewrite stale architecture notes. Do not preserve obsolete statements just because they used to be true.
+- If the change does not affect architecture, state that explicitly in the final response or PR notes.
+
+## File Types
+
+- `../../ARCHITECTURE.md`: repository-level architecture entrypoint.
+- `architecture.html`: single-file visual map for humans. It embeds data from `architecture.json` so it can be opened directly from disk.
+- `architecture.json`: structured map for AI agents and tooling.
+- `embed-architecture-json.mjs`: refreshes the embedded JSON block in `architecture.html` from `architecture.json`.
+- `decisions/*.md`: architecture decision records.
+- `templates/repo-architecture.md`: template for future architecture docs.
+- `../../AGENTS.md`, `../../CLAUDE.md`, `../../GEMINI.md`, `../../.github/copilot-instructions.md`, and `../../.cursor/rules/architecture-docs.mdc`: AI entrypoints that point future tools back to these docs.
+
+## What Belongs Here
+
+Architecture docs should capture:
+
+- Module responsibilities.
+- Data/control flow between major components.
+- Public contracts and compatibility constraints.
+- Runtime and platform assumptions.
+- Testing strategy for behavior that crosses module boundaries.
+- Important tradeoffs, especially when there were plausible alternatives.
+
+Keep `../../ARCHITECTURE.md`, `architecture.html`, and `architecture.json` synchronized when architecture changes. When changing graph data, edit `architecture.json`, then run:
+
+```bash
+node docs/architecture/embed-architecture-json.mjs
+```
+
+The CI pipeline runs the same embed script and fails if `docs/architecture/architecture.html` changes afterward. Treat `architecture.json` as the hand-edited graph source and commit the refreshed HTML artifact with it.
+
+Architecture docs should not become:
+
+- Full API reference.
+- Changelog.
+- Exhaustive file-by-file inventory.
+- Raw meeting notes.