Read this before USAGE.md. Each word means here what it says below and nothing looser. There are two kinds: Fossil's own words, which keep Fossil's meaning (Fossil's glossary and file formats govern them), and OCX's words, which OCX defines below and writes with "OCX" where the plain word would be ambiguous. Where a word is still open, it says so.

Fossil's words

• Repository: one Fossil database file holding a project's whole history.
• Clone: a repository made from another with fossil clone. Clones of one project share its project code. One cloned over HTTP has its own server-code; one cloned from a repository file keeps the original's (Fossil 2.27, tried 2026-10-10).
• Project code: 40 hex digits that every clone of one project shares.
• Server-code: 40 random hex digits that each repository file has of its own, made by fossil new or by cloning over HTTP; Fossil prints it as "server-id" when it makes one. A plain copy of the file, or a clone made from it, keeps it, so two such repositories answer to one server-code.
• Artifact: one item Fossil stores: a check-in, a file, a ticket change, a forum post, a tag, a wiki page. It is named by the hash of its content, and it never changes: an edit is a new artifact, with a new hash.
• Hash: the SHA1 or SHA3-256 of an artifact's content, in hex; a prefix that is unique in the repository names it too.
• Check-in: the artifact recording one commit: its files, comment, author and parents.
• Checkout: a directory of files opened from a repository at a check-in.
• Forum thread: a root post and the replies under it. Each post is an artifact. Every reply names the thread's original root post and the post it answers.
• Ticket: the changes that share one ticket-id. A ticket-id is 40 random hex digits, made when the ticket is created; it is not the hash of anything, although Fossil's default ticket page labels it "Ticket Hash".
• Ticket change: one artifact setting fields of a ticket, such as adding a comment; it names its ticket's ticket-id. Which fields a ticket has, and which its page shows, are the repository's own settings.
• User: Fossil's account: fossil user, --user, and the U card in every artifact; its name is its login. A person and a program each act as one.
• Receipt: Fossil's record of an artifact's arrival in a repository: the time, the IP address, and the user it was received from (its RCVFROM table; the page /rcvfromlist). A repository keeps its own receipts and does not copy them to clones, so only the repository that received an artifact knows who sent it; a clone records what it pulls as received from its own user.
• Capability: one of Fossil's letters on a user, such as i (check in) or s (setup). Capabilities are the outer limit of what a user may do; i admits any write, to any branch, tag or wiki page.
• Backoffice: Fossil's work after a request, which runs the after-receive hook. A write made on the repository itself starts none.
• After-receive hook: a command Fossil's backoffice runs after artifacts arrive, by sync or from a web page, with each one's hash and a description on standard input. Fossil does not wait for it, keeps nothing it says, and leaves out of its list what arrived more than 24 hours before the newest arrival (docs/fossil.md, "Hooks").

OCX's words

The words of OCX protocol v1, which says what each does.

• OCX message: a JSON block in a forum post or a ticket change, addressed to one node: a request (run, stop) or a report (started, ended) (protocol, section 3).
• Run: the OCX message asking a node to run one process, toward an objective; to completion, or as a session. It is built in layers: workspace, sandbox, limits and process (section 1).
• Layer: one level of a run's message, which a node processes outer to inner (section 1).
• Value: something the node knows, named $$name$$ in a string of a run, and put in its place before use (section 2).
• Objective: what a run is for, and what counts as passing; a field of a run, which a verdict may be judged against.
• Session: a run that is given what it subscribes to, its running process fed each delivery or a process started for each (section 8).
• Manual run: a run whose process waits until a person starts it (section 8).
• Started, ended: the node's reports that it is launching a run's process, and that the run is over for good, with the outcome (section 10).
• Stop: the OCX message asking a node to end a run (section 3).
• Process: a program running for a run: its command, with the environment the run names (section 8).
• Kept logs: the ends of a process's STDERR and STDOUT that the node keeps and posts where the run is (section 8).
• Pattern: the text at a URL, by convention the wiki page run/NAME, holding a run's fields that OCX's create starts a run from; of the server's own wiki page, only a version a user holding admin or setup wrote counts (tools).
• Subscription: what a session is given while it runs: check-ins on the branches in its checkins, and posts and ticket changes from the users in its hears (section 9).
• Delivery: one artifact given to a session, as one line of JSON (section 9).
• Limits: how much a run's process may use, the run's limits layer (section 7).
• Node: a repository on the host that runs its work, the server's with OCX's hook installed, or a clone that OCX's node tool runs on another host, named by its node user (Fossil, senders and nodes, section 5).
• Node user: the Fossil user a node acts as: runs name the node by it, the node's reports count only when received from it, and a node on another host syncs as it. No two hosts share one. It holds the least it needs: nothing on the server's host, and o and i on another.
• Workspace: the directory on a node where a run's clone, checkout and files live, made by the run's workspace steps (section 5).
• Step: one action of a run's workspace layer, such as a clone; never "tool", which names OCX's commands (section 5).
• Sandbox: what a run's process sees and may do on its node, the run's sandbox layer (section 6).

Tools

• Tool: one thing OCX does, defined once: what it does, who may do it, and what it leaves in Fossil. The protocol's artifacts are the standard and the tools a convenience: anyone may write the same artifacts by other means, and they count the same. USAGE.md lists them. In the code each tool is a command: a typed input, a typed answer and one method that takes the dry-run flag.
• Entry point: how a caller reaches the tools: the CLI (ocx2 at a terminal), the CGI (ocx2-cgi, pages beside the Fossil repository) and MCP (ocx2-mcp, for an agent). The CLI reaches every tool, the CGI every one but stage and post, and MCP every one but hook, unhook, export and import, each saying why where it is withheld. Each reads its own form of input into a tool's typed input and writes the answer in its own layout; status names it as entry_point.
• OCX's tools: create, run, receipt, stop, post, audit, push and status, which write the protocol's artifacts, perform runs by hand, and say who sent an artifact (protocol v1's tools).
• Manual run: a run that the node does not start when it arrives; a person starts it by hand with the run tool.
• Trial: a run performed by hand from a definition, with run --trial, which writes nothing to Fossil.
• Hook: OCX's after-receive hook (ocx2-hook), on a node: it acts on the artifacts Fossil lists as arrived, and nothing else. A write made on the node itself starts no backoffice, and the tool that made it acts on it at once. Apart from OCX, when a check-in arrives it brings the repository's git export up to date. It writes its own log, since Fossil keeps nothing it says.
• Input, output, context: a tool's input is what its caller gives it, its output what it found or made, and its context who calls and from where, which the entry point resolves; each is a type, and its schema is derived from that type, never written by hand.
• Answer: what a tool returns, the same in every entry point: its log, its output (the result) when it ran to the end, and why it stopped.
• Log, operation: the operations a tool performed, in order, each typed with its operands, such as take_release with its root and name. A check reads what the run needs; a change changes something.
• List, help, status: list (what runs with no tool named, and what MCP's tools/list gives) is every tool: what it does, who may run it, and the schema of its input; on the web page each tool has its form. help adds the context: the schemas of each output, of the context and of every answer, and where releases live. status shows who and where this run is, each setting with where it came from.
• Dry run: dry_run, which every tool's input takes (--dry-run on a command line): the same tool and answer, changing nothing. Its checks are performed, so it stops where the run would stop now; its changes are only listed in its log.

Judging check-ins

• Gate: the checks a check-in must pass, crystal run ci.cr: the guards, the specs and the coverage ratchet. Green means it passed.
• Verdict: a tag on a check-in recording a judgement of it, pass or fail with a reason and the objective it was judged against: audited for a person's or an agent's, ci for a program's. Anyone may write one, but a verdict on your own check-in never counts (protocol v1's verdicts).

Releases

• Release: a copy of the built programs of one check-in, named for its first twelve hex digits, with the gate's result (gate.txt) and the source (source.txt) beside them.
• Release root: the directory holding releases and the links to them. On the host it is /var/lib/ocx/release2.
• Staged area: staged/ in the release root. A release is written there once; the stager owns it.
• Stage: what stage does: check, build, write the release into the staged area, smoke it, and offer it as next. Staging never changes what is served.
• Next: the link next in the staged area, naming the release offered for acceptance.
• Pre-release candidate: the release offered as next, which Fossil's page ocx2-cgi-next runs, for review before it is accepted.
• Active release candidate: the release served (current), which Fossil's page ocx2-cgi runs.
• Staging server: ollama.openbeagle.org: low stakes, public data, isolated and untrusted hosts, its work recoverable from Fossil's records on other clones (HISTORY.md decision 31). A release reaches a server with private code or costly downtime only after the gating items there.
• Accept: copy the next release into the root and serve it as current, keeping what was current as previous. Only a login with setup accepts, so whoever stages cannot choose what runs; once a release is served, only the active release accepts, the pre-release candidate accepting only a node's first release, trusted on first use.
• Current, previous: the links naming the release served at ocx2-cgi and the one served before it.
• Rollback: serve the previous release again. A second rollback undoes the first.
• Smoke: run a program of the release with no arguments and an empty environment, and require it to answer with its usage.

Building OCX

• Slice: a check-in that implements one specific, justifiable function, passes the gate, and has coverage demonstrating that function. docs/slices.md sets out each slice.