Read KEEP.md first: the maintainer's standing directions, in their own words. A change against one of them needs the maintainer's word on the record first.

Then read knowledge-map.json: which document holds each topic, so you read the one that holds what you need, and write a topic only where the map says it lives, linking to it from anywhere else. Before writing any Crystal, read docs/crystal.md: its rules are how OCX's code is written, and the guards hold every change to them. The Fossil wiki page New Agent Workspace describes how a workspace is created; it does not replace the rules in PLAN.md.

This workspace and its conversation

The workspace directory is the parent of this checkout. Read ../binding.json to find its Fossil record, login, branch, and remote. The record is the conversation for this workspace. Read its first post for the assignment, and use that same thread for progress, findings, and questions. Work in the workspace's own clone and checkout; do not open a served repository directly.

This workflow is transitional. It is the accepted release's, built from the ocx branch: the clone in the session's sandbox remembers a password its login shares with every workspace of that login, kept in a file beside the release (HISTORY.md decision 24). The rebuild gives each work unit a login of its own whose password is set when its workspace is created, so the agent never knows it (decision 29, docs/slices.md slice 1). Until then, never copy the credential out of the clone, and never put it in a post, a file in the tree, or a command's output.

The ocx2 branch is being rebuilt slice by slice from an empty src/ (docs/slices.md), so it has no task tool of its own yet. Use the accepted release's, which is built from the ocx branch:

/var/lib/ocx/release/current/task .. --wait

It opens the workspace's wake pipe (../wake), syncs ../clone when its remote can be reached (see below), and queries the record before blocking. The repository's hook writes to the pipe when a post arrives on this thread, but the pipe is a latency hint rather than a durable queue; rerunning the command queries the record again and recovers missed signals. It exits after printing posts since this login's latest turn. Run it again to wait for another turn. To post a turn as the workspace login, put its text on standard input:

/var/lib/ocx/release/current/task .. --write < turn.txt

Keep files meant to outlast a turn in the workspace, not /tmp, which a session's sandbox empties between turns. Install the pinned shards with shards install before running CI. Do not put passwords or other credentials in posts or check-ins.

How the clone reaches the repository depends on the remote in ../binding.json:

• An http(s) URL (what the console gives a workspace it makes: the repository's email-url): autosync is on, so fossil commit in tree/ pushes as it commits, and fossil sync -R ../clone pulls what others wrote since the turn began. The task tool syncs before it reads or writes.
• A repository file on this host (file:///…, workspaces made before the console used the URL): the file is not in a session's sandbox, so fossil sync there fails, and that is expected. The host syncs ../clone before each turn starts and again when it ends, so commit in tree/ and the host pushes the check-in after your turn. task --write keeps the turn in ../outbox and the host posts it at the same time. During a turn the clone holds the record as it stood when the turn began.

The wait and write commands need write access to the workspace's clone, which is beside tree/. In a sandbox that grants writes only to tree/, run them with workspace access; otherwise they cannot record what they read or keep.

Outside an OCX workspace

If there is no ../binding.json, you are not in an OCX workspace: you are an invited agent, such as a cloud review session, with a login of your own and no task tool. Follow the agent's part of docs/invite.md: replace your one-time password, clone, open your record with a thread of your own, reply on it, and close it when you are done.

Contributions and reviews

• Make each change a demonstrated unit of behavior. Check-in comments use a title followed by Intent:, Expression:, and Demonstrates: lines; the named evidence must exist. Refer to precepts by both ID and name, such as precept C6 (Explicit Arguments).
• Run crystal run ci.cr for the project checks. Host and merge gates are separate modes described in PLAN.md.
• Record a review verdict on the reviewed check-in with an audited tag: ocx2 audit CHECK-IN pass|fail NOTE AGAINST in your clone's checkout, AGAINST the objective you judged it against, such as PLAN.md, which refuses your own check-in and reads the verdict back from the server (docs/slices-parity.md, slice 4). Until a release holding it is accepted on the served host, use the accepted ocx release's /var/lib/ocx/release/current/audit CHECK-IN pass|fail NOTE-FILE. Put actionable findings on the relevant Fossil record as well.
• Do not edit scripts/ without the maintainer's approval on the record, as required by HISTORY.md decision 22.
• Keep runtime state out of repository config under precept C2 (Single Owner). Pass configuration explicitly under precept C6 (Explicit Arguments); its served CGI request fields are the stated exception. The precepts and their guards are in PLAN.md.