{
  "about": "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.",
  "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"
  },
  "elsewhere": [
    {
      "name": "The battery of uninitiated readers, 2026-10-10 to 13",
      "link": "https://ollama.openbeagle.org/ollama/doc/f68b57bd52/docs/battery/README.md",
      "holds": "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"
    },
    {
      "name": "The battery of local models with the agent tools, from 2026-10-15",
      "link": "https://ollama.openbeagle.org/ollama/timeline?y=e",
      "holds": "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"
    },
    {
      "name": "Definition checks by local models, from 2026-10-17",
      "link": "https://ollama.openbeagle.org/ollama/timeline?y=e",
      "holds": "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"
    },
    {
      "name": "Adversarial tests on scratch repositories, from 2026-10-18",
      "link": "https://ollama.openbeagle.org/ollama/timeline?y=e",
      "holds": "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"
    }
  ],
  "documents": [
    {
      "file": "README.md",
      "area": "Why OCX exists",
      "kind": "guide",
      "answers": "What is OCX, and what governs it?",
      "holds": [
        "the axioms",
        "the virtues",
        "the building blocks: Fossil, Crystal, Linux",
        "where the release is served"
      ]
    },
    {
      "file": "KEEP.md",
      "area": "Why OCX exists",
      "kind": "guide",
      "answers": "What has the maintainer said to keep?",
      "holds": [
        "the maintainer's standing directions, verbatim"
      ]
    },
    {
      "file": "PLAN.md",
      "area": "Why OCX exists",
      "kind": "guide",
      "answers": "What is OCX for, what guards it, and what is still missing?",
      "holds": [
        "the objective",
        "the precepts with their README virtues",
        "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"
      ]
    },
    {
      "file": "ROADMAP.md",
      "area": "Why OCX exists",
      "kind": "guide",
      "answers": "Where is each building block headed beyond this project?",
      "holds": [
        "the building blocks' direction"
      ]
    },
    {
      "file": "HISTORY.md",
      "area": "Why OCX exists",
      "kind": "record",
      "answers": "What was decided, and why?",
      "holds": [
        "where OCX came from",
        "the numbered decisions"
      ],
      "edit": "add a decision; never rewrite one"
    },
    {
      "file": "GLOSSARY.md",
      "area": "The words and the map",
      "kind": "guide",
      "answers": "What does a word mean here?",
      "holds": [
        "the project's words"
      ]
    },
    {
      "file": "docs/refresher.md",
      "area": "The words and the map",
      "kind": "guide",
      "answers": "How do I check my reading of OCX's words?",
      "holds": [
        "questions on OCX's words, to check a reading"
      ]
    },
    {
      "file": "ARCHITECTURE.md",
      "area": "The words and the map",
      "kind": "guide",
      "answers": "How do OCX's parts fit its purpose?",
      "holds": [
        "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"
      ]
    },
    {
      "file": "knowledge-map.json",
      "area": "The words and the map",
      "kind": "data",
      "answers": "Which document holds what?",
      "holds": [
        "which document holds each topic"
      ]
    },
    {
      "file": "docs/knowledge-map.md",
      "area": "The words and the map",
      "kind": "generated",
      "answers": "Which document holds what, to read?",
      "holds": [],
      "edit": "generated from knowledge-map.json"
    },
    {
      "file": "SCENARIOS.md",
      "area": "Using OCX",
      "kind": "guide",
      "answers": "How do I use OCX for a goal, and does each step work yet?",
      "holds": [
        "the maintainer's scenarios and the state of each step"
      ]
    },
    {
      "file": "USAGE.md",
      "area": "Using OCX",
      "kind": "guide",
      "answers": "What does each tool take and answer?",
      "holds": [
        "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"
      ]
    },
    {
      "file": "patterns/stage.md",
      "area": "Using OCX",
      "kind": "guide",
      "answers": "How does a session send a stage run?",
      "holds": [
        "the stage run pattern and its send command"
      ]
    },
    {
      "file": "ocx-node/README.md",
      "area": "Using OCX",
      "kind": "guide",
      "answers": "How do I build, start and use the container node?",
      "holds": [
        "the container node setup, approval, agent sign-in, run examples and host needs"
      ]
    },
    {
      "file": "ocx-node/patterns/ci.md",
      "area": "Using OCX",
      "kind": "guide",
      "answers": "How does a session send a CI run to the container node?",
      "holds": [
        "the CI run pattern and its command"
      ]
    },
    {
      "file": "ocx-rootfs/README.md",
      "area": "Using OCX",
      "kind": "guide",
      "answers": "How do I build, start and test the public server and the client from a BQ2 seed?",
      "holds": [
        "the two root folders: their build, start commands, test and what they leave out"
      ]
    },
    {
      "file": "scripts/README.md",
      "area": "Using OCX",
      "kind": "guide",
      "answers": "What do the maintainer's scripts start, and why can agents add to the record but not destroy it?",
      "holds": [
        "what serve, confine and receipt-reader start, and the sandbox each runs in",
        "why scripts/ needs the maintainer's review"
      ]
    },
    {
      "file": "AGENTS.md",
      "area": "Using OCX",
      "kind": "guide",
      "answers": "How does an agent work in this repository?",
      "holds": [
        "an agent's workflow in its workspace",
        "the check-in comment's form"
      ]
    },
    {
      "file": "docs/invite.md",
      "area": "Using OCX",
      "kind": "guide",
      "answers": "How does an invited agent join?",
      "holds": [
        "an invited agent's steps"
      ]
    },
    {
      "file": "docs/remote-agents.md",
      "area": "Using OCX",
      "kind": "guide",
      "answers": "How does an agent that holds no password for the server work on a project through OCX?",
      "holds": [
        "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"
      ]
    },
    {
      "file": "docs/how-a-post-reaches-an-agent.md",
      "area": "Protocol v1",
      "kind": "guide",
      "answers": "How does a post reach an agent?",
      "holds": [
        "how a post reaches an agent: the server, the daemon and the watcher"
      ]
    },
    {
      "file": "docs/protocol-v1.md",
      "area": "Protocol v1",
      "kind": "definition",
      "answers": "What does protocol v1 define, what is it for, and what stays stable?",
      "holds": [
        "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"
      ]
    },
    {
      "file": "docs/protocol-v1-fossil.md",
      "area": "Protocol v1",
      "kind": "definition",
      "answers": "What does protocol v1 rest on?",
      "holds": [
        "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"
      ]
    },
    {
      "file": "docs/protocol-v1-verdicts.md",
      "area": "Protocol v1",
      "kind": "definition",
      "answers": "How is a verdict written and counted?",
      "holds": [
        "writing and reading verdicts"
      ]
    },
    {
      "file": "docs/protocol-v1-questions.md",
      "area": "Protocol v1",
      "kind": "definition",
      "answers": "What is a question to a user, and what closes it?",
      "holds": [
        "a question's and a decision's keys, and when a question waits"
      ]
    },
    {
      "file": "docs/protocol-v1-tools.md",
      "area": "Protocol v1",
      "kind": "definition",
      "answers": "Which of OCX's tools write protocol v1's artifacts?",
      "holds": [
        "the tools for protocol v1 and where each is offered"
      ]
    },
    {
      "file": "docs/protocol-v1-examples.md",
      "area": "Protocol v1",
      "kind": "definition",
      "answers": "What do whole messages look like?",
      "holds": [
        "example messages with what a node writes back"
      ]
    },
    {
      "file": "docs/protocol-v1-failures.md",
      "area": "Protocol v1",
      "kind": "definition",
      "answers": "What comes of each failure or race?",
      "holds": [
        "the failure cases, numbered for the specs"
      ]
    },
    {
      "file": "docs/parity-v1.md",
      "area": "Building OCX",
      "kind": "guide",
      "answers": "What did the ocx branch do that ocx2 lacks, and in what order is it built?",
      "holds": [
        "parity with the ocx branch and the order to build"
      ]
    },
    {
      "file": "docs/backlog.md",
      "area": "Building OCX",
      "kind": "guide",
      "answers": "What has been raised but not yet decided?",
      "holds": [
        "ideas awaiting the maintainer's review"
      ]
    },
    {
      "file": "docs/agent-tools-proposal.md",
      "area": "Building OCX",
      "kind": "guide",
      "answers": "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?",
      "holds": [
        "the proposed editing tools over MCP, the lessons they follow, and the questions awaiting the maintainer"
      ]
    },
    {
      "file": "docs/protocol-v2-proposal.md",
      "area": "Building OCX",
      "kind": "guide",
      "answers": "What would protocol version 2 change, in which words, and what must the maintainer approve first?",
      "holds": [
        "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"
      ]
    },
    {
      "file": "docs/protocol-v2-draft.md",
      "area": "Building OCX",
      "kind": "guide",
      "answers": "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?",
      "holds": [
        "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"
      ]
    },
    {
      "file": "docs/protocol-v2-draft-owner.md",
      "area": "Building OCX",
      "kind": "guide",
      "answers": "In the proposed version 2, who owns a repository's runs on a host, what wakes it, and what goes?",
      "holds": [
        "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"
      ]
    },
    {
      "file": "docs/protocol-v2-draft-process.md",
      "area": "Building OCX",
      "kind": "guide",
      "answers": "In the proposed version 2, how is a run's process confined and fed, how does a run end, and what is refused?",
      "holds": [
        "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"
      ]
    },
    {
      "file": "docs/interfaces.md",
      "area": "Building OCX",
      "kind": "guide",
      "answers": "Exactly what does each interface do, and which spec shows it?",
      "holds": [
        "each interface's behavior and its specs"
      ]
    },
    {
      "file": "docs/crystal.md",
      "area": "Building OCX",
      "kind": "guide",
      "answers": "How is OCX's Crystal written?",
      "holds": [
        "the rules for Crystal code"
      ]
    },
    {
      "file": "docs/fossil.md",
      "area": "Building OCX",
      "kind": "guide",
      "answers": "What has been learned about Fossil?",
      "holds": [
        "lessons about Fossil"
      ]
    },
    {
      "file": "docs/fossil-git.md",
      "area": "Building OCX",
      "kind": "guide",
      "answers": "What has been learned about Fossil's git export and import?",
      "holds": [
        "lessons about Fossil's git export and import"
      ]
    },
    {
      "file": "docs/linux.md",
      "area": "Building OCX",
      "kind": "guide",
      "answers": "What has been learned about Linux?",
      "holds": [
        "lessons about Linux"
      ]
    },
    {
      "file": "docs/design/modules.json",
      "area": "What the code is made of",
      "kind": "data",
      "answers": "What is each module of src/ for?",
      "holds": [
        "each module's purpose and layer"
      ]
    },
    {
      "file": "docs/design/modules.md",
      "area": "What the code is made of",
      "kind": "generated",
      "answers": "What is each module of src/ for, to read?",
      "holds": [],
      "edit": "generated from docs/design/modules.json"
    },
    {
      "file": "docs/survey/functionality.json",
      "area": "What the code is made of",
      "kind": "data",
      "answers": "Which behavior does each file and spec serve?",
      "holds": [
        "each behavior with its parts and specs"
      ]
    },
    {
      "file": "docs/survey/gaps.json",
      "area": "What the code is made of",
      "kind": "data",
      "answers": "Which survey gaps are known?",
      "holds": [
        "the survey's known gaps"
      ]
    },
    {
      "file": "docs/design/facts.json",
      "area": "What the code is made of",
      "kind": "data",
      "answers": "Which Fossil settings does the code read?",
      "holds": [
        "the Fossil settings OCX reads"
      ]
    },
    {
      "file": "docs/precepts/precepts.json",
      "area": "What the code is made of",
      "kind": "data",
      "answers": "Which precepts do the guards hold?",
      "holds": [
        "the guarded precepts"
      ]
    },
    {
      "file": "docs/precepts/gaps.json",
      "area": "What the code is made of",
      "kind": "data",
      "answers": "Which precepts lack a guard, a refutation or a CI run?",
      "holds": [
        "the precepts' known gaps"
      ]
    },
    {
      "file": "docs/precepts/exceptions.json",
      "area": "What the code is made of",
      "kind": "data",
      "answers": "What is excepted from a precept, and why?",
      "holds": [
        "the precepts' exceptions"
      ]
    },
    {
      "file": "docs/precepts/pace.json",
      "area": "What the code is made of",
      "kind": "data",
      "answers": "How long may the gate take?",
      "holds": [
        "the gate's time limit"
      ]
    },
    {
      "file": "docs/slices.md",
      "area": "Records",
      "kind": "record",
      "answers": "How was the rebuild first sliced?",
      "holds": [
        "the rebuild's first slices"
      ],
      "edit": "kept as it stood"
    },
    {
      "file": "docs/slices-parity.md",
      "area": "Records",
      "kind": "record",
      "answers": "How was parity with the ocx release first built?",
      "holds": [
        "the first parity slices"
      ],
      "edit": "kept as it stood"
    },
    {
      "file": "docs/slices-git.md",
      "area": "Records",
      "kind": "record",
      "answers": "How was the git round trip built?",
      "holds": [
        "the git round-trip slices"
      ],
      "edit": "kept as it stood"
    },
    {
      "file": "docs/slices-v1.md",
      "area": "Records",
      "kind": "record",
      "answers": "How was protocol v1 first built?",
      "holds": [
        "protocol v1's first slices"
      ],
      "edit": "kept as it stood"
    },
    {
      "file": "docs/review-v1.md",
      "area": "Records",
      "kind": "record",
      "answers": "What did the review of 2026-10-12 and 13 find?",
      "holds": [
        "the review of v1"
      ],
      "edit": "kept as it stood"
    },
    {
      "file": "docs/review-v1-tables.md",
      "area": "Records",
      "kind": "record",
      "answers": "What did the review of the tables draft find?",
      "holds": [
        "the review of the tables draft"
      ],
      "edit": "kept as it stood"
    },
    {
      "file": "spec/cards/examples/README.md",
      "area": "Using OCX",
      "kind": "guide",
      "answers": "How do Crystal and Stone run the same card examples?",
      "holds": [
        "how to run the shared card examples"
      ]
    }
  ]
}