slivingdoc: Instructions file for Codex

AGENTS.md — slivingdoc

Architecture docs

architecture/ holds one doc per command and subsystem: an overview, the product contract, pull, commit, conflicts, checkpoints, the notebook, the Git engine, the workspace, storage, the S3 store, hosted storage mode, login and storage selection, the CLI, the terminal presentation, the MCP server, configuration, errors, logging, security, guarantees, testing, build, releasing, running, and recorded decisions. Start at architecture/README.md: it indexes every doc with a one-line summary and suggests a reading order per task. Open the doc for your concern before scanning the code; it lists the files and symbols to read.

Keep them true. The docs are only useful if an agent can trust them without re-checking the code:

• A change that alters behavior, a flow, a file's role, a public name, a flag, an error code, an invariant, or a rule described in an architecture doc updates that doc in the same commit.
• A new command or subsystem gets a new architecture/<concern>.md in the same shape (intro with "Read this when", Key files, Flow, Behavior, Gotchas, Related) and a line in architecture/README.md. A removed or renamed file or symbol is removed or renamed in every doc that cites it.
• Code comments cite a doc by path (architecture/commit.md), never by section number or line.
• Cite files and symbols, never line numbers. Describe only what the code does; plans go in worklogs or issues.
• If you find a doc that disagrees with the code, the code wins: fix the doc in your change, or say so if you cannot.

Architecture

slivingdoc is a standalone MCP server that gives many agents one shared directory of UTF-8 text notes, stored durably in S3-compatible object storage or, when SLIVINGDOC_TOKEN is set or slivingdoc login stored an account login, in a space of the slivingdoc hosted storage API (architecture/hosted-mode.md, architecture/login.md). It uses Git data structures and merge behavior internally but never invokes a Git executable and never exposes a Git repository. The contract is split by concern under architecture/. Three states shape every operation. L is the caller-controlled visible directory. P is the server-owned private state (repository, baseline, locks). R is the accepted remote state indexed by the stored object current.