Implementation Notes: neokapi Framework
Implementation notes contain tactical details for the neokapi framework (Apache-2.0): SQL schemas, wire protocols, algorithm pseudocode, Go interface signatures, and other reference material. They exist alongside the Architecture Decisions, which describe the design choices; notes describe the implementation.
The notes are grouped into the same series as the decisions (F foundations, E engine, C context, S surfaces, M multilingual), so a note sits under the heading of the AD it details. A final group holds the notes on this repository's own infrastructure.
F: Foundations
| Note | Parent AD | Content |
|---|---|---|
| Content-Model Parity Across Wire Projections | F-04 · F-02 | The lossless model↔proto↔store round-trip invariant, what must round-trip, and the extend-without-breaking checklist gated by a conformance test |
E: Engine
| Note | Parent AD | Content |
|---|---|---|
| Implementing Formats | E-02 | Step-by-step guide for new format readers and writers |
| Skeleton store and streaming | E-02 | The skeleton store, its backings and writer fallbacks, and how the whole-document readers stream through it |
| Docx paragraph replay | E-02 | How a WordprocessingML round trip puts an unchanged paragraph back as its original bytes, and what the corpus and the parity slice measure |
| Content-Fidelity Surfacing | E-02 | Surfacing non-translatable context: the inverted toggle, channels, parity force-off |
| Scaling the processing primitive | E-01 | The same processing primitive in-process, as a queue-backed worker and as a gRPC daemon, and the seams that let it scale as a service |
| Flow Steps Format | E-04 · E-03 | YAML step list, compilation to the graph, script steps |
| Session-Scoped Tool Authoring | E-03 | Guide for writing tools against BlockStore |
| The change applier | E-09 · E-03 | The change-set types, strict decoding and schema, ApplyBlock and its rules, status consequences, Diff, and how tools write through it |
| The file home | E-09 | How the change service's file home stages an edit, commits under an advisory lock, applies it again when the file moved, and writes editions kept in files of their own |
| Plugin Model | E-05 | In-process registry contract for plugin binaries |
| Plugin protocol v1 | E-05 | The versioned plugin contract: manifest rules, the three transports, the Mode-C gRPC surface and wire format, and the conformance suite |
C: Context
| Note | Parent AD | Content |
|---|---|---|
| kapi.yaml Project File | C-01 | kapi.yaml recipe schema and examples |
| Workspace storage | C-03 | The files a workspace keeps, the tables in each pool, cross-file queries, pool settings and read-only opening |
| Context atlas | C-11 · C-12 | The kapi context atlas --json document the desktop's Explore view draws, field by field |
| Terminology Data Model | C-08 | Go structs, Terminology interface |
| Content Memory Matching Algorithm | C-09 | Tiered matching, version chains, TMX mapping |
S: Surfaces
| Note | Parent AD | Content |
|---|---|---|
| CLI Conventions | S-01 | Input/output/exit-code/project contracts, per-command surface table |
| MCP Tools Reference | S-03 | Where the MCP tool handlers live, how a tool reaches the server, and what shape its result takes |
| WASM Engine ABI | S-01 | The JS contract the browser build of the CLI exposes to @neokapi/engine, the change contract's entry points, and its reverse bridges |
M: Multilingual
| Note | Parent AD | Content |
|---|---|---|
| Multimodal Content | M-03 | The two axes of adaptation, and the timing/geometry/recognition annotations that carry them |
| OMML Math Conversion | M-04 | core/math Exp AST, OMML reader, nor-splice algorithm, coverage ledger |
Repo infrastructure
These notes describe how this repository builds, measures and presents itself, and answer to no architecture decision.
| Note | Content |
|---|---|
| CDN asset offloading | Why the large immutable docs assets are served from S3 + CloudFront, and how they are published |
| Brand tokens and the documentation palette | Where the brand colours live, how the docs sites and the diagram kit are painted from them, and what the drift gate asserts |
| Agent evaluation | Whether coding agents apply a project's rules, measured on a generated repository against an answer key |
| Paired agent evaluation | The same content tasks through file tools, the kapi CLI skill, MCP and the edit commands, compared |
| Markdown in the UI | Which metadata fields carry markdown, and the shared Markdown typeset primitive that renders them |