Read this before USAGE.md. Each word means here what it says below and nothing looser. Fossil's own words keep Fossil's meaning (Fossil's glossary and file formats govern them); OCX's words are defined below, written with "OCX" where the plain word would be ambiguous. Where a word is still open, it says so. A refresher checks your reading, if you want one.

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.
• Project code: 40 hex digits that every clone of one project shares.
• Server-code: 40 random hex digits Fossil gives a repository file when fossil new or a clone over HTTP makes it; Fossil prints it as "server-id". A plain copy of the file, or a clone made from the file, keeps the same one (Fossil 2.27). A run names a node's repository by it, or a prefix of it, in its clone (below, "Clone, the key").
• Artifact: one item Fossil stores: a check-in, a file, a ticket change, a forum post, a tag, a wiki page. Its hash names it, and it never changes: an edit is a new artifact.
• Hash: the SHA1 or SHA3-256 of an artifact's content, in hex; a prefix 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 an artifact, each reply naming the root post and the post it answers. Users holding 2 may read its posts; one by a user without 4 waits for a moderator.
• Ticket: the changes that share one ticket-id: 40 random hex digits made when the ticket is created, hashing nothing, though Fossil's ticket page labels it "Ticket Hash".
• Ticket change: one artifact setting fields of a ticket, such as adding a comment; it names its 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 or a program acts as a user.
• Receipt: Fossil's record of an artifact's arrival in a repository: the time, the IP address and the user it came from (the page /rcvfromlist). Receipts are not copied to clones: only the repository that received an artifact knows who sent it, and 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): 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 page of the repository has answered, in a process of its own, such as running the after-receive hook. Only a page served starts it, a sync being one; fossil backoffice runs it by hand. A write on the repository file itself starts none; the next one a page starts lists it (docs/fossil.md, "Hooks").
• After-receive hook: a command Fossil's backoffice runs with what the repository received since it last ran, however it arrived, each one's hash and a description on standard input. Fossil does not wait for it, keeps nothing it says, and leaves out what arrived more than 24 hours before the newest arrival.

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: a request to one node (run, stop), or that node's report (started, ended); or a question to a user (question) and anyone's answer to it (decision), which no node acts on. A node starts a run only from a user holding admin or setup, or one holding R within its owner's bounds, and refuses any other; it heeds a stop as "Stop" says. Any user who may read the post or ticket holding it may read it.
• R: a capability letter Fossil does not define, which OCX reads as "may send runs": its user may send runs and stop the runs it sent. An admin gives it to a user, or takes it away, every other letter as it was, with OCX's send_runs (NEW TERM, needs approval), since Fossil's own user page may drop it when that user is saved there. A node takes such a run only within what its owner allows in the file r-senders.json of the release it runs, staged from the tree; its owner is whoever accepts that release (USAGE.md, "Let an agent send runs"; refusal 1).
• Run: an OCX message whose kind is run, asking a node to run one process toward an objective. Any forum post, root or reply, or ticket change may hold one; that artifact's hash names it. An edit holding a run is another run; the one edited stands until stopped. Its layers: workspace, sandbox, limits, process (sections 1 and 3).
• 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, against which a check-in's verdict may be judged.
• Session: a run whose process.session is true. Every run's process first reads a line naming its run and objective; a session is then given, through its watcher, each delivery received after its run that passes its subscription: on that input, or, with deliveries start, each in a process of its own (section 8). With ends, it is also given each ended that counts written where it is, such as its build's (HISTORY.md decisions 87 and 102).
• Manual run: a run whose process.manual is true, waiting for a person to start it with run RUN --repository CLONE on its agent machine (section 8).
• Question: an OCX message whose kind is question, asking the user its for names, as a run asks a node; for says only whose console lists it as waiting. It holds the question in a line or two, in words. It offers two to four options, the recommended one first, or none. It may say what the decision changes, and what to read first, each shown as a link. It starts nothing. It waits on that user until they decide, whoever else has, and stays open until its sender, or, when it names in run the run whose process asks it, whoever sent that run, confirms it answered, whatever else is said there (questions).
• Decision: an OCX message whose kind is decision, naming a question by its hash, written where the question is by any user who may write there, who is shown beside it, by its receipt. Its note holds their words, or an option's words exactly, never its number. From the question's sender, or from whoever sent the run the question names as asking it, when that run counts, it is the confirmation, but for the first decision of the user it is for: its note says in words why the question is answered, and it closes the question; nothing else does, and no decision after it changes it (questions). The maintainer's word, as question is theirs (HISTORY.md decision 99); a message whose kind is response, its first name, is read as one.
• 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; a node acts only on one from a user holding admin or setup, or from the user holding R that sent the 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, which OCX's create copies into a new run; from the server's wiki, the newest version a user holding admin or setup wrote (tools).
• Subscription: what a session is given of what the server receives after the run: posts anywhere in the run's thread and changes to its ticket, from the users its hears names (["*"]: all); and check-ins on the branches its checkins names. Never a run, a stop or a started, nor an ended unless the run's ends is true; a question or a decision is given as a post. Never what its process.user sent, nor a node user but such an ended (section 9). A stop ends only the run it names: another session where it is keeps its subscription.
• Delivery: one artifact a watcher gives its session as one line of JSON, at most once, in server order, received after the run and brought by a complete pull (section 9).
• Limits: how much a run's process may use, the run's limits layer (section 7).
• Server: NEW TERM, needs approval. In the maintainer's words: "a publicly hosted Fossil server providing synchronization". OCX's docs also say "the server" for the repository it serves for one project, the served repository (senders).
• Agent machine: a machine holding a clone of each project it works on. One program, the daemon, runs there under a service manager, which restarts it if it stops (How a post reaches an agent).
• Node: a clone running OCX on an agent machine, not a user. Its daemon pulls whole clones and hands runs to watchers, which post as the node user. A run names that user and optionally the clone's server-code in clone (nodes). Whether Fossil's identifiers suffice to define a node remains open (KEEP.md), in part answered by the server-code (HISTORY.md decision 77).
• Daemon: the one program on each agent machine that waits on Fossil's chat, pulls each clone whole, finds new artifacts, decides open runs and remembers what it handled; a service manager restarts it (How a post reaches an agent).
• Node user: the Fossil user a node writes as, chosen on the agent machine. It holds goC4w, never admin or setup; i for verdicts, y for shares. Shared users require runs naming each clone (nodes).
• Run state: NEW TERM, needs approval. The local file beside a run's lock: taken prevents a second launch, ending holds the exact ended to retry, done settles the run (section 4).
• Completion number: NEW TERM, needs approval. A clone's highest receipt number after a complete pull, published by rename for watchers to read through (section 4).
• Clone, the key: optional: a run may leave it out, and most will. In a run, clone names the repository, a clone among those whose node uses the run's node user, that is to act on it, by its server-code or a prefix of it of 10 to 40 lower-case hex digits; a node whose server-code does not start with it leaves the run alone. In started and ended, it is the server-code of the repository whose node wrote the report, and for a run naming a clone only that clone's reports count. Without it, any node of the node user may act (protocol v1, section 3). A third use of the word, beside a repository made by fossil clone and the workspace step clone.
• Watcher: a detached ocx2 watch process for one run, started by the daemon or run; the maintainer approved the word in HISTORY.md decision 103. It is the parent of the process it launches: setsid for an unconfined run or one at a terminal, starting its own session whose process groups end with it; timeout for a wall; bubblewrap for a sandbox; otherwise the run's command. Each starts the next that applies; sh sets cpu, processes or files limits, then becomes the command. Holding the run's lock, so the run is in its care, it reads the state: with taken, it ends what the old lock names and posts lost; with ending, it retries that exact report; with done, it does nothing. Otherwise it decides again, makes the workspace, writes taken, posts started before launching, and gives session deliveries at completed pulls. It posts kept logs, shares files and writes a verdict when asked and the run was neither stopped nor lost (no shares for deliveries: start, no verdict for any session). It removes a saved workspace when asked, once nothing of the process is left, then posts the exact ended held in its state before marking done. It handles stops and failures. It exits at once, writing no report, when another watcher holds its run, the run is not its node's, its user has another run in care, letting go of its run lock as it finds that (decision 122), or a run from a user holding R alone waits for another such run in care (decision 108). It lives until its run ends or is found not to start; told to end before launch with no stop, it leaves the run for a later watcher. It hands on no other run. Where it sits: modules; its death: crashes; its own failure after started: case 33.
• Workspace: the directory on a node where a run's clone, checkout and files live, made by the run's workspace steps (section 5).
• Saved: of a run's work, held by the server: no change, file Fossil does not track or stash left in its checkout, and no artifact its clone has not sent. A run whose directory step has "remove_on": "saved" has its workspace removed once it has ended and its work is saved; a node reads remove, the key's older name, as remove_on (HISTORY.md decisions 80 and 103).
• 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

• Card: a card/NAME wiki page in any repository, named by that repository's project name and NAME, whose JSON says what indexed repository records to find, which columns to show, and what sentence to say. The card tools answer it across named repositories; each front end reads the same data.

• Receipt service: the receipt reader, scripts/receipt-reader.cr, the maintainer's small read-only program that answers who sent an artifact from the served repositories.

• Launcher: scripts/confine.cr (confine), which serve starts and which starts the ocx2 daemon, the receipt reader and the web page's /receipt path, each in a fixed sandbox.

• Tool: one thing OCX does, defined once: what it does, who may do it, and what it leaves in Fossil. A convenience: the same artifacts written by other means count the same. USAGE.md lists them; protocol v1's tools, those protocol v1 needs. In the code each is a command.

• Entry point: how a caller reaches the tools: the CLI (ocx2), the CGI (ocx2-cgi, the OCX page, at /ext/ocx2-cgi under the repository's address in Fossil, its header linking console) and MCP (ocx2-mcp, for an agent). The CLI reaches every tool; the CGI and MCP each withhold some, saying why. Each turns its caller's input into the tool's, and lays out the answer its own way; status names it.

• Working branch: the branch OCX's tools commit an agent's work on, never trunk. save uses a checkout's branch named agent/…, or else one named for the caller and the checkout, the same each time, shown by context before any save. No run or started names it. With its user's password, an agent may commit anywhere with Fossil (PLAN.md, "Branch contributions").

• Trial: performing a run's definition by hand with run --trial, writing nothing to Fossil. Not built: run takes no --trial.

• Hook: Fossil's own git export command, installed as its after-receive hook by hook; it keeps a mirror current and schedules no run-work (USAGE.md, "Install or remove the hook").

• Register: what register does on the asker's own machine, asking for a login like Fossil's self-registration, but the user is made only when an admin approves (USAGE.md, "Ask for a login").

• Approve: what approve does with an admin's one press on the asker's link: make that user holding exactly the capabilities asked, never admin or setup, and never change a user it did not make. If an admin opens only a link the asker itself printed, only the asker's code can collect the password.

• Collect: what collect does: give the asker an approved login's password, for the code whose SHA-256 its link named.

• 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 (not the context tool), which the entry point resolves; each is a type, its schema derived from it.

• 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. Each either reads what the tool needs or changes something.

• List, help, status: list (what runs with no tool named, and what MCP's tools/list gives) shows every tool: what it does, who may run it and its input's schema. help adds the schemas of each output, the context and every answer, and where releases live. status shows who calls and from where, each setting with its source, and each run that has not ended and where it stands, as the record or the clone's completed pull says.

• Console: what console shows: a person's view, in the order of HISTORY.md decision 18: the questions waiting on them, those they may confirm answered, every other open question, then the runs of every node user an administrator's run names: those not ended and the five that ended last; each option a press of post. Each entry point lays it out its own way, a page of its own on the web, from questions, which answers the questions as data (decision 100). The maintainer's word, and trunk's (decision 98).

• 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 tool would stop now; its changes are only listed in its log.

• Project: a served repository made by project, empty or from git, with its git export, hook, ticket fields, node user and run users ready. See USAGE.md.

Judging check-ins

• Gate: the checks a check-in must pass, crystal run ci.cr: the guards, the specs and the coverage ratchet (no file may lose coverage). 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), the source (source.txt) and, when the tree holds it, r-senders.json. In a run, $$release$$ names the release its node ran when the run started, even after a later accept (section 2).
• Release root: the directory holding releases, the links to them and the node's own directory: /var/lib/ocx/agents-daemon on the staging server's host; daemon, watch and run need one on the agent machine.
• Staged area: staged/ in the release root. A release is written there once; whoever stages 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: the host ollama.openbeagle.org and the servers on it: low stakes, public data, an isolated and untrusted host, its work recoverable from Fossil's records on other clones (HISTORY.md decision 31).
• Accept: copy the next release into the root and serve it as current, keeping what was current as previous. Only a user holding setup accepts, so whoever stages cannot choose what runs. Through ocx2-cgi-next, it accepts only a first release, while none is served, 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.