Generated from knowledge-map.json by crystal run spec/support/generate.cr; edit that file, not this one. Which document holds what, so each topic is written in one place and the others link to it. spec/guards/delineation_spec.cr holds every document of the tree to this map; records kept outside the tree are listed under elsewhere, and new test records go in Fossil tech-notes, linked from here; docs/knowledge-map.md is generated from it.
Why OCX exists
| Document | Answers | Holds | Kind |
|---|---|---|---|
| README.md | What is OCX, and what governs it? | the axioms; the virtues; the building blocks: Fossil, Crystal, Linux; where the release is served | guide |
| KEEP.md | What has the maintainer said to keep? | the maintainer's standing directions, verbatim | guide |
| PLAN.md | What is OCX for, what guards it, and what is still missing? | the objective; the precepts with their README virtues; the proposed precepts of axiom 6, and the cases testing it; where each function stands; how each kind of agent works on protocol v1: hosted agents, the native agent for local models, an agent's MCP surface, and agents that cannot hold a key; the parity contract; the phases; the working rules; open design questions | guide |
| ROADMAP.md | Where is each building block headed beyond this project? | the building blocks' direction | guide |
| HISTORY.md | What was decided, and why? | where OCX came from; the numbered decisions | record: add a decision; never rewrite one |
The words and the map
| Document | Answers | Holds | Kind |
|---|---|---|---|
| GLOSSARY.md | What does a word mean here? | the project's words | guide |
| docs/refresher.md | How do I check my reading of OCX's words? | questions on OCX's words, to check a reading | guide |
| docs/writing.md | How do I write a document a newcomer can follow? | how to write documents for people | guide |
| ARCHITECTURE.md | How do OCX's parts fit its purpose? | OCX in six points: what holds what, who may do what, and what is not built; OCX's layers, in one line; how the parts are arranged | guide |
| knowledge-map.json | Which document holds what? | which document holds each topic | data |
| docs/knowledge-map.md | Which document holds what, to read? | generated: generated from knowledge-map.json |
Using OCX
| Document | Answers | Holds | Kind |
|---|---|---|---|
| SCENARIOS.md | How do I use OCX for a goal, and does each step work yet? | the maintainer's scenarios and the state of each step | guide |
| USAGE.md | What does each tool take and answer? | each tool's inputs and answers; patterns and how to write one; installing a node and the hook; asking for a login, approving it and collecting its password | guide |
| patterns/stage.md | How does a session send a stage run? | the stage run pattern and its send command | guide |
| ocx-node/README.md | How do I build, start and use the container node? | the container node setup, approval, agent sign-in, run examples and host needs | guide |
| ocx-node/patterns/ci.md | How does a session send a CI run to the container node? | the CI run pattern and its command | guide |
| ocx-rootfs/README.md | How do I build, start and test the public server and the client from a BQ2 seed? | the two root folders: their build, start commands, test and what they leave out | guide |
| scripts/README.md | What do the maintainer's scripts start, and why can agents add to the record but not destroy it? | what serve, confine and receipt-reader start, and the sandbox each runs in; why scripts/ needs the maintainer's review | guide |
| AGENTS.md | How does an agent work in this repository? | an agent's workflow in its workspace; the check-in comment's form | guide |
| docs/invite.md | How does an invited agent join? | an invited agent's steps | guide |
| docs/remote-agents.md | How does an agent that holds no password for the server work on a project through OCX? | MCP over HTTP and through a provider's tunnel; a run's secrets; syncing an agent's work through the call; the pattern run/mcp-tunnel and how to bring an agent in | guide |
| spec/cards/examples/README.md | How do Crystal and Stone run the same card examples? | how to run the shared card examples | guide |
Protocol v1
| Document | Answers | Holds | Kind |
|---|---|---|---|
| docs/how-a-post-reaches-an-agent.md | How does a post reach an agent? | how a post reaches an agent: the server, the daemon and the watcher | guide |
| docs/protocol-v1.md | What does protocol v1 define, what is it for, and what stays stable? | what protocol v1 is for; the message kinds and their layers; values; the workspace, sandbox, limits and process layers; subscriptions and delivery guarantees; a run's life; refusals; ended's outcomes; the protocol's words; stability: what may be added and what never changes | definition |
| docs/protocol-v1-fossil.md | What does protocol v1 rest on? | Fossil as the medium; finding a message in an artifact; who sent an artifact, and who may do what; nodes: clones on agent machines, with projects named by password files; versions | definition |
| docs/protocol-v1-verdicts.md | How is a verdict written and counted? | writing and reading verdicts | definition |
| docs/protocol-v1-questions.md | What is a question to a user, and what closes it? | a question's and a decision's keys, and when a question waits | definition |
| docs/protocol-v1-tools.md | Which of OCX's tools write protocol v1's artifacts? | the tools for protocol v1 and where each is offered | definition |
| docs/protocol-v1-examples.md | What do whole messages look like? | example messages with what a node writes back | definition |
| docs/protocol-v1-failures.md | What comes of each failure or race? | the failure cases, numbered for the specs | definition |
Building OCX
| Document | Answers | Holds | Kind |
|---|---|---|---|
| docs/parity-v1.md | What did the ocx branch do that ocx2 lacks, and in what order is it built? | parity with the ocx branch and the order to build | guide |
| docs/backlog.md | What has been raised but not yet decided? | ideas awaiting the maintainer's review | guide |
| docs/agent-tools-proposal.md | Which tools would let an agent, a weak local model included, read, change, check and save a run's checkout over MCP, and what must the maintainer decide first? | the proposed editing tools over MCP, the lessons they follow, and the questions awaiting the maintainer | guide |
| docs/protocol-v2-proposal.md | What would protocol version 2 change, in which words, and what must the maintainer approve first? | version 2's vocabulary in Fossil's terms, each overloaded word and how it goes, what was decided since the first draft, the tools and names it renames, what the implementation touches, the demonstrations owed, and the order to build it | guide |
| docs/protocol-v2-draft.md | In the proposed version 2, how is a message found, who sent it, which clone acts on a run and whose reports count, and how is its workspace made? | version 2's messages, senders, the key clone, the clone's user and the process's user, values and workspace steps, the password step included | guide |
| docs/protocol-v2-draft-owner.md | In the proposed version 2, who owns a repository's runs on a host, what wakes it, and what goes? | the one-owner invariant, the events and their triggers, the idempotent start, publication owned to its end, what OCX keeps, what goes, and the demonstrations owed | guide |
| docs/protocol-v2-draft-process.md | In the proposed version 2, how is a run's process confined and fed, how does a run end, and what is refused? | version 2's sandbox, limits, process, subscriptions, outcomes, a run's life, refusals, what OCX keeps on a host, verdicts, stability, and a whole run | guide |
| docs/interfaces.md | Exactly what does each interface do, and which spec shows it? | each interface's behavior and its specs | guide |
| docs/crystal.md | How is OCX's Crystal written? | the rules for Crystal code | guide |
| docs/fossil.md | What has been learned about Fossil? | lessons about Fossil | guide |
| docs/fossil-git.md | What has been learned about Fossil's git export and import? | lessons about Fossil's git export and import | guide |
| docs/linux.md | What has been learned about Linux? | lessons about Linux | guide |
What the code is made of
| Document | Answers | Holds | Kind |
|---|---|---|---|
| docs/design/modules.json | What is each module of src/ for? | each module's purpose and layer | data |
| docs/design/modules.md | What is each module of src/ for, to read? | generated: generated from docs/design/modules.json | |
| docs/survey/functionality.json | Which behavior does each file and spec serve? | each behavior with its parts and specs | data |
| docs/survey/gaps.json | Which survey gaps are known? | the survey's known gaps | data |
| docs/design/facts.json | Which Fossil settings does the code read? | the Fossil settings OCX reads | data |
| docs/precepts/precepts.json | Which precepts do the guards hold? | the guarded precepts | data |
| docs/precepts/gaps.json | Which precepts lack a guard, a refutation or a CI run? | the precepts' known gaps | data |
| docs/precepts/exceptions.json | What is excepted from a precept, and why? | the precepts' exceptions | data |
| docs/precepts/pace.json | How long may the gate take? | the gate's time limit | data |
Records
| Document | Answers | Holds | Kind |
|---|---|---|---|
| docs/slices.md | How was the rebuild first sliced? | the rebuild's first slices | record: kept as it stood |
| docs/slices-parity.md | How was parity with the ocx release first built? | the first parity slices | record: kept as it stood |
| docs/slices-git.md | How was the git round trip built? | the git round-trip slices | record: kept as it stood |
| docs/slices-v1.md | How was protocol v1 first built? | protocol v1's first slices | record: kept as it stood |
| docs/review-v1.md | What did the review of 2026-10-12 and 13 find? | the review of v1 | record: kept as it stood |
| docs/review-v1-tables.md | What did the review of the tables draft find? | the review of the tables draft | record: kept as it stood |
Records kept elsewhere
- The battery of uninitiated readers, 2026-10-10 to 13: how readers of every reasoning level fared on each draft of protocol v1: the method, the findings, every round's prompts, definitions, answers and transcripts, and the harness that ran them, as they stood at check-in f68b57bd52
- The battery of local models with the agent tools, from 2026-10-15: each run of battery/main.cr: its summary table and every trial's exact requests, tool answers and replies, as Fossil tech-notes, one a run, never edited
- Definition checks by local models, from 2026-10-17: each check of a proposed text's definitions: the drafts, the text and questions each model was handed, the expected answers and every answer, as a Fossil tech-note with one plain .tar, never edited
- Adversarial tests on scratch repositories, from 2026-10-18: each attack on a release served by Fossil as its own CGI on a scratch repository: the setup script, each attacker's report, and the triage with each finding's reproduction, as a Fossil tech-note with one plain .tar, never edited; a setup script corrected later is attached beside it
Kinds
- guide: written by hand, current, for people and agents
- definition: the protocol's standard: changed only by the protocol's own rules
- data: read by guards or code; edited by hand
- generated: written from data; edit its source
- record: kept as it stood, to say what happened; a new test record is a Fossil tech-note, not a file in the tree