Decision records¶
This directory records the why behind non-obvious choices. It is historical context, not the product contract or a backlog:
- current behavior lives in the topic pages linked from the documentation index;
- planned work, bugs and delivery status live in GitHub issues;
- completed user-visible work is summarized by releases and
CHANGELOG.md.
Topics¶
| Topic | Decision records | Current-state documentation |
|---|---|---|
| Cross-cutting architecture | Architecture | Overview |
| KB model and imports | Data plane | Data plane |
| MCP tools, search and lint | Control plane | Control plane |
| HTTP, stdio and authorization | Transport and authorization | Transport and authorization |
| Commits, synchronization and conflicts | Concurrency and git | Concurrency |
| Skills, services and secrets | Skills, services and secrets | Skills, services and secrets |
| Provisioned artifacts | Synchronization and provisioning | Synchronization |
| CLI, TUI and providers | Client and configurator | Configurator |
| Configuration, deployment and releases | Deployment and release | Deployment |
| Repository and documentation policy | Project governance | Contributing |
Finding a decision¶
Search the directory instead of maintaining a second title/status index:
rg '^## (AD|D)[0-9]+|keyword' docs/decisions/
Every implementation decision has one canonical topic file and a stable
<a id="dNN"></a> anchor. Link directly to
docs/decisions/<topic>.md#dNN.
Adding a decision¶
- Survey open
planissues before choosing an ID. A plan title reserves its D number until it is implemented or explicitly abandoned. - Choose the next number above both the decision files and existing plan issue titles. Never infer it from a single topic file.
- The plan issue is the design handoff. Add the final D entry only in the implementation PR, in the one topic file that owns the choice.
- Record the decision, rationale and consequences. Put current behavior in the corresponding topic page and future work in a GitHub issue.
- Do not add status tables, milestone lists or duplicate entries. Cross-topic decisions have one owner and are linked from other pages when useful.