Architecture Decisions: neokapi

These are the Architecture Decisions for the neokapi framework, the open content engine. Everything here is Apache-2.0 and describes the framework modules: the repository root, the cobra-free host runtime, the shared CLI base, the kapi binary, Kapi Desktop, and the in-repo plugins.

Each decision describes the current state of its subsystem. When a subsystem evolves, its decision is updated in place, and the history lives in version control.

Tactical detail (SQL schemas, wire formats, algorithm pseudocode) is separated into Implementation Notes.

How the corpus is organized

Six series, by concern. A decision's identifier is its series letter and its position within the series, and it does not change when a neighbour is added or retired:

Series	Concern
F: Foundations	what the framework is, what a unit of content is, and how it is identified and serialized
E: Engine	how content is read, processed, written, and extended
C: Context	what a project knows, where it keeps it, and what governs it
S: Surfaces	the CLI, the desktop app, agent surfaces, and the runtime libraries
M: Multilingual	what it takes for content to exist in more than one language
A: Assurance	how the framework proves it works

Each series is a directory, and its decisions sort by sidebar_position within it. The sidebar is generated from the directory, so adding a decision means adding a file.

F: Foundations

AD	Title	Scope
F-01	The framework and its modules	the Go modules, go.work, the enforced dependency direction
F-02	The content model	Part and Resource, Block, Run, Overlay, the semantic vocabulary, Layers
F-03	Identity	short ids, the durable content key, occurrences
F-04	The content-model wire schema	the canonical proto, protoconvert, frozen field numbers, the drift guard

E: Engine

AD	Title	Scope
E-01	The processing engine	channel-based streaming, the Executor, parallel block tools, collectors
E-02	The format system	readers and writers, detection, registries, skeletons, non-translatable context
E-03	The tool system	the Tool interface, locale cardinality, annotations, side effects, schemas
E-04	Flows and I/O binding	source and sink bindings, process-only runs, ingest versus run transforms
E-05	The plugin system	manifest-driven out-of-process plugins, the transport modes, presets
E-06	Execution trust	the exec class, per-project consent keyed to the approved argv
E-07	Model and translation providers	the model provider interface, machine-translation backends, credentials
E-08	Document structure tiers	tagged structure versus geometric reconstruction, the native and browser readers
E-09	The change contract	the change set, revisions and preconditions, the change service, homes and the file home, the commit hooks

C: Context

AD	Title	Scope
C-01	The project model	the kapi.yaml recipe, the .kapi/ layout, the store interface, ProjectContext
C-02	Coordinates and governance	the product × channel space and the declared axes, per-file resolution, validity windows
C-03	The context store and graph	the checkout's projection at .kapi/work/store.db, the workspace holding each project's context store, the property graph and its query shapes
C-04	Block state and the decision record	the decision ledger, document identity, the shards a checkout writes, basis and target-hash staleness
C-05	Freshness and the composite ref	one ref per stream, compare-and-swap per component, the staleness gate
C-06	Context retrieval	by location and by content, on the CLI and over MCP
C-07	Voice profiles	the profile model, starter packs, the word-rule and voice checks, scoring
C-08	Terms	the concept model, the terms store, tiered lookup, validity
C-09	Content memory	tiered matching, entity generalization, version chains and governed reuse, the two-stage rebuild
C-10	Redaction and clearance	the placeholder model, the local vault, the three policy readers
C-11	Context operations	the append-only operation log, candidates that advise, the policy for who decides
C-12	Places	the gazetteer a geo axis reads, declared places, containment and overlap, the map's outlines

S: Surfaces

AD	Title	Scope
S-01	The kapi CLI	the command tree, output formats, the credential store, exit codes
S-02	Kapi Desktop	the desktop app, the project home and point map, the Context hub, governance editing, runs through the up venue
S-03	Agent surfaces: MCP and skills	the embedded skill and its four habits, the curated MCP surface, the context write tools, the edit tools over the change contract and the review tools
S-04	Toolbox utilities	the multi-call binary, block-text projection, exit codes
S-05	The i18n runtime for React	the runtime, build-time extraction, re-attach, in-context review
S-06	The visual editor data model	the render projection, the shared preview kit, the edit round-trip

M: Multilingual

AD	Title	Scope
M-01	Bilingual format interop	the extract and merge round trip, target alignment, exchange carriers
M-02	Segmentation	the stand-off overlay, the engine registry, per-project selection
M-03	Multimodal content	image, audio and video extraction, confidence-gated escalation, provenance
M-04	Math and equations	the equation converter, formula blocks, translatable prose inside math
M-05	Prompts and batching	the prompt library, batching, the placeholder protocol
M-06	Content packages	the block bundle and the project parcel
M-07	Metadata in other languages	tool, format and plugin metadata, compiled catalogs

A: Assurance

AD	Title	Scope
A-01	Testing and documentation	the test pyramid, the eval bands, the docs site and its pseudo-locale, recordings
A-02	Parity with the Okapi Framework	the parity suite in the bridge repository, its scheduled report, faithful output