r3: Instructions file for Codex

r3 — Render. Review. Refine.

r3 is a local-first workspace for published artifacts and human/agent conversations. A per-user server owns immutable content and persisted threads; the browser, CLI, and agents use the same HTTP/JSON contract. The server, worker, CLI, and SPA ship as one self-contained binary. Read README.md for usage.

Write README.md for human readers evaluating and getting started with r3. Keep agent instructions, protocol semantics, and exhaustive feature details in the agent guide or reference documentation.

Use CONTEXT.md for domain terminology. Backend names the entity; server and notification worker name its storage and local notification roles. Subscription names notification routing state; selected subscription names the one currently chosen. Existing protocol fields retain their wire spellings.

This file, the artifact design, schema explanation, and the deep-reference skills below are the design source of truth. Update the document that owns a decision when it changes. Verification maps behavior to executable acceptance checks. Earlier live-file reviews have been retired; imported historical evidence remains readable but does not define new API behavior.

Architecture

The HTTP/JSON contract is the product. Start at shared/artifacts.ts (re-exported by shared/types.ts), then server/artifact-api.ts, cli/artifact-commands.ts, and web/src/artifact-api.ts. Keep all three clients aligned.

publisher: capture local files/git → CLI HTTP upload ─┐
browser: fetch + authenticated event stream ──────────┼→ backend server
agent: CLI/HTTP publications, threads, claims ───────┘    SQLite + immutable blobs
local agent harness ← persistent worker ← outward stream ← selected backend
opaque preview document → scoped version bytes + trusted r3 runtime

• The server is the only SQLite writer. Storage and domain services are explicitly constructed and injected; importing modules must not open a database.
• Ordinary requests use artifact/version identity. The server never resolves a publisher path, Git repository, worktree, or live file. Git and directory capture run on the publisher. Direct upgrades from live-review stores require r3 1.5.0 first; current startup upgrades only artifact schemas.
• Projects are optional groups, assigned explicitly or inferred from a sanitized publisher-supplied Git remote under server policy. Their IDs do not derive from paths or URLs. Later publications preserve the group; deletion preserves artifacts.
• One logical agent session identifies one run. Multiple agents, including subagents, use distinct IDs. Sessions are attribution, not credentials, accounts, artifact ownership, or live presence.
• Local mode starts the same backend server lazily and announces it in $XDG_RUNTIME_DIR/r3/daemon.json. A private Unix sidecar bootstraps local CLI credentials. A loopback-only server needs no login unless requireLogin=true; any external bind, host, public URL, or trusted proxy always requires login and refuses requireLogin=false. No-login mode refuses forwarded requests, issues no credentials, and the browser warns once about it unless disableLoginNotice is set. Publication URLs stay stable; r3 open needs a one-time sign-in ticket only when local login is required. Browser boot never exposes the API credential. Backend selection is R3_URL, nearest project .r3.json, user backendUrl, then automatic local. Saved credentials are keyed by the complete normalized URL; r3 login supports browser approval or an API key. The separate persistent worker opens only private Unix IPC and outgoing backend streams. CLI data/watch go directly to the backend. Read remote protocol for auth, recovery, and wire rules.
• The loopback application listener dispatches scoped preview paths separately from its authenticated API. Previews use the browser's r3 address automatically; every rendered document has an opaque browser origin and no application credentials. App HTML downloads are attachments; the workspace checks browser capabilities and obtains any required consent before loading executable documents.
• SSE carries invalidations after committed writes. Clients refetch state on ready or reconnect. No filesystem watcher or live-content fallback remains.