@ssheleg/agent-sync 1.2.2

package/plugins/agent-sync/skills/agent-sync/SKILL.md

@@ -0,0 +1,372 @@
+---
+name: agent-sync
+description: "Use when several coding agents work one repository at the same time and must not collide - claiming a task, reserving the next decision/question/ticket id, journaling a run, filing or answering a cross-repo dependency, or regenerating the shared board. Triggers - 'claim this task' / 'возьми задачу', 'who is working on X' / 'кто сейчас делает X', 'reserve an id' / 'зарезервируй id', 'sync the board' / 'обнови доску', 'set up agent coordination' / 'настрой координацию агентов', /agent-sync. Use it BEFORE editing any shared registry file (decisions, open questions, roadmap, workstreams, dependencies) in a project that has .claude/agent-sync.json, even when the user never mentions coordination - an unclaimed edit to those files is how two agents overwrite each other."
+compatibility: "Requires the task-pipeline skill for its stages (npx sshlg-skills install). Needs python3 3.9+ (stdlib only, HTTP included - nothing to pip install) and bash for the hooks. The knowledge backend is configured per project; with none configured it degrades to git-file leases. Enforcement hooks are Claude Code only - on other agents the same checks run as a self-check."
+license: MIT
+metadata:
+  version: "1.2.2"
+  author: appvillis-com
+---
+
+# agent-sync — one project, many agents, no collisions
+
+Two planes, and one rule between them:
+
+> **Git is the record plane. The cloud is the coordination plane.**
+> A fact that must survive is written to git first and referenced from the cloud.
+> A fact about *who is doing what right now* lives in the cloud and expires.
+
+No cloud object is ever the only home of a durable fact. Everything below exists to
+keep that true while several agents write at once.
+
+## Four traps — read these before anything else
+
+**1. The knowledge base never decides a lease.** It cannot: twelve concurrent appends to
+one Outline document returned twelve successes and left **three** lines. Exclusion comes
+from something with real compare-and-swap. The plane carries the record and nothing else.
+Full measurements in `references/lease-protocol.md`.
+
+**2. Know which lease you have, and say so.** `leaseBackend: "local"` is an atomic file
+create — exclusive between processes on one filesystem, **advisory across machines**.
+`leaseBackend: "git"` pushes a ref, and the remote's non-fast-forward rejection **is** a
+compare-and-swap — exclusive across machines. `acquire` prints which. A pretended lease is
+worse than no lease: the other agent stops checking.
+
+**`acquire` also writes the claim through to the roadmap**, and `release` restores exactly
+what was there — one row, one cell, refused on ambiguity, `git diff` empty after a
+round-trip. **Read `references/roadmap.md`** before configuring `claimTags` or closing a
+task; closing is a statement about the work and stays yours.
+
+**3. Hooks exist only in Claude Code.** Elsewhere nothing blocks a guarded edit: run
+`guard` yourself and record the run as `ungated`. Do not describe a project as protected
+when it is not.
+
+**4. Parse liberally, and never call an unreadable log a lost race.** The store rewrites
+what you wrote — Outline turns a `- ` bullet into `* `. Emit `- `, accept `-`/`*`/`+`,
+count anything entry-shaped that fails, and **fail loudly** past 2% unparseable. Reporting
+`lost` when the truth is *unreadable* names a holder who does not exist. Watch for a
+silent pre-filter: a `continue` before the regex hides bad lines from the counter built to
+expose them.
+
+## Bringing this into ANY project — the whole chain
+
+```
+scaffold  → create the documentation architecture, only where it is absent
+adopt     → read the repository, propose a config, write nothing
+init      → write the approved config + the gitignored env file
+            (operator pastes the token — never you)
+reconcile --set-baseline    → make history a counted backlog, once
+setup     → generate the snapshot that describes this project's wiring
+check     → validate the whole thing; non-zero if it is not healthy
+```
+
+**`check` is what makes the skill self-sufficient.** It refuses to call a setup healthy
+on any of: a register file that does not exist or whose allocation pattern matches
+nothing; a guard glob that matches no file (a rule that protects nothing); a claim-tag
+pattern with nothing to look for; a gate command whose script is missing; a mirror source
+that is not there; missing or empty credentials; a `.gitignore` that does not cover the
+env file — or the env file being **tracked by git**, which is the one unrecoverable
+mistake here; a missing, hand-edited or stale snapshot; **a snapshot no agent instruction
+file links**, because agents that cannot find it will infer the pipeline instead; and a
+register with no as-built baseline. Every one of those failed for real during this tool's
+own adoption.
+
+Run `check` after adopting, after changing the config, and in CI.
+
+**`scaffold` never overwrites.** It seeds a decision register with an allocation line and
+an `AGENTS.md` that points at the snapshot, and leaves every existing file untouched — a
+tool that rewrites a project's own conventions on adoption is worse than one that does
+nothing.
+
+## Existing project: start with `adopt`
+
+Run `adopt` before `init`. It reads the repository and prints what it found — id
+registers, registry files, gates — plus the decisions it **refuses to make for you**,
+then proposes a config. It writes nothing.
+
+```bash
+python3 "$SKILL_DIR/scripts/agent_sync.py" adopt
+```
+
+Confirm the registers and guarded files with the operator before writing them. A
+register pointed at the wrong file makes every later check confidently wrong, and a
+guarded list that misses a shared file leaves the one place collisions actually happen
+unprotected. In a submodule it declares no registers at all: decisions belong to the
+parent repository.
+
+Then: `init` → paste the approved config → `reconcile --set-baseline` → `setup` →
+commit the snapshot and link it from the project's agent instructions.
+
+## First command in a project: `init`
+
+**Never run anything else against an uninitialised project.** `init` is where the
+storage question gets asked and answered, once, and written down.
+
+**Ask the operator these two things in chat — do not guess, do not pick a default:**
+
+1. **Where should coordination state live?**
+   - a knowledge cloud (`outline`) — the shared record, awareness and board across
+     machines. **It does not decide leases**; nothing in it can (trap 1);
+   - or local files (`fs`) — no credentials, no shared awareness, every run `ungated`.
+
+   The lease is decided separately by `leaseBackend` — `git` for cross-machine exclusion,
+   `local` otherwise.
+2. **If cloud: the instance URL.** The URL is configuration, not a secret, so you
+   may write it. The **token is not** — you never ask for it in chat, never read it
+   back, and never place it yourself.
+
+Then run it with their answers:
+
+```bash
+python3 "$SKILL_DIR/scripts/agent_sync.py" init --backend outline --url https://<their-instance>
+python3 "$SKILL_DIR/scripts/agent_sync.py" init --backend fs
+```
+
+`init` writes `.claude/agent-sync.json` (shape, committed), writes
+`.env.agent-sync` with the keys and an **empty** token line (identity, mode 600),
+adds `.env.agent-sync` and `.agent-sync/` to `.gitignore`, and then prints exactly
+what the operator must do themselves — create the token in their own instance and
+paste it into that one line. It never overwrites an existing config or env file
+without `--force`.
+
+Relay those closing instructions to the operator verbatim. Getting the token into
+the file is their step, and the design depends on it staying theirs.
+
+## Then, before every session
+
+```bash
+python3 "$SKILL_DIR/scripts/agent_sync.py" status
+```
+
+Idempotent. Inspects, repairs what is missing, prints a status block, names exactly
+ONE next action.
+
+**Read the two awareness sections it prints — they are the point, not decoration.**
+
+- **Other runs working this project right now.** Who holds what, this minute. Do not
+  take those on, and do not "just look at" the files they cover. A lease you cannot
+  see makes you blocked; a lease you can see makes you coordinated.
+- **New since you last looked.** Cross-repo dependency moves that landed while you
+  were away. A dependency that moved may unblock what you planned — or invalidate it.
+  This list is watermarked per run, so it stays quiet until something actually
+  changes; when it speaks, it matters.
+
+An agent that skips this block will re-derive work someone else is doing and act on a
+dependency state that changed an hour ago.
+
+What else `status` decides for you:
+
+- No credentials in the environment → degraded mode, reported, and it continues.
+  Missing credentials are not an error, they are a smaller mode.
+- `task-pipeline` absent → it prints the install line and stops. Do not improvise a
+  substitute flow; without those stages there is nothing to bind to.
+
+```bash
+npx sshlg-skills install
+```
+
+## The commands
+
+| Command | Does |
+|---|---|
+| `init` | **Run first.** Ask where state lives, write config + gitignored env file, print the operator's step |
+| `status` | Inspect, repair, report, name one next action |
+| `bootstrap` | Create the cloud container and print the id to paste into the env file |
+| `acquire <KEY>` | Take the lease on a task id. Prints `won` or `lost <holder>` |
+| `renew <KEY>` | Extend the lease. The `PostToolUse` hook does this for you |
+| `release <KEY>` | Give the lease back. Always do this, including on failure |
+| `reserve <REG>` | Reserve the next id in a register (`DEC`, `OQ`, `DEP`, …). Prints the id |
+| `release-id <REG> <ID>` | Return an id you did not end up writing to git |
+| `journal <text>` | Append one line to this run's journal |
+| `record <text>` | Append what you **actually built** — `--decision DEC-…`, `--files a,b` |
+| `reconcile` | Intent (git) vs as-built (cloud). `--set-baseline` once per project |
+| `signal <DEP-ID> <state>` | Move a cross-repo dependency: `filed`/`accepted`/`delivered`/`closed`/`refused` |
+| `guard <path>` | Answer whether this run may write that path. Exit 0 = yes, 2 = no |
+| `board` | Regenerate the shared board and this repo's page. `--mirror` also renders the configured git docs into the plane |
+| `whoami` | Print this run's id and its held leases |
+| `setup` | Write the generated snapshot of how **this** project is wired, for agents to read |
+| `adopt` | Inspect an existing project and **propose** a config — writes nothing |
+| `scaffold` | Create the missing documentation architecture. Never overwrites |
+| `check` | Validate the whole setup end to end. Non-zero when it is not healthy |
+
+`$SKILL_DIR` is this skill's own directory. Every command reads
+`.claude/agent-sync.json` from the project root and needs no arguments beyond those
+listed.
+
+## Claiming — the shape that matters
+
+```
+acquire → do the work → release
+```
+
+Never skip `release`, including on failure: an abandoned lease blocks the task until its
+TTL expires, and the next agent cannot tell "in progress" from "crashed an hour ago".
+
+**The lease is not the claim.** The lease says who holds it *now* and expires; the durable
+claim is the tag in git, written through by `acquire` and cleared by `release`. One fact,
+one home — do not invent a third place that records ownership.
+
+**Read `references/lease-protocol.md`** before changing acquisition, expiry, stealing or
+id allocation.
+
+## Guarded files
+
+The config lists registry files several agents write. Before editing one:
+
+```bash
+python3 "$SKILL_DIR/scripts/agent_sync.py" guard docs/DECISIONS.md
+```
+
+Exit 2 means another run holds it. Do not edit anyway, and do not "just fix one line" —
+a clobbered decision looks exactly like a decision.
+
+Claude Code's `PreToolUse` hook runs this for you. Elsewhere nothing does.
+
+## Reserving an id
+
+Reading a "Next free ID" line is not reserving it — two agents read the same number and
+both use it.
+
+```bash
+python3 "$SKILL_DIR/scripts/agent_sync.py" reserve DEC   # → DEC-0216
+```
+
+Allocation is positional over the log, so every agent computes the same answer. Reserve
+and not write it to git? `release-id` it — otherwise the number is a hole the board
+reports as a leak, and nobody can tell a hole from work on a branch.
+
+## Nothing in a log is ever edited or deleted
+
+Logs are **replayed in order**, so an edit silently rewrites a conclusion other agents
+already acted on. Correct by **appending**: release a lease, `release-id` an unused id,
+supersede a wrong as-built entry with a later one. Generated pages are the only
+exception, and one that lost its `agent-sync:generated` marker is **refused**, not
+overwritten. Lifetimes: `references/two-sources.md`.
+
+## Two documentation sources, and the duty to reconcile them
+
+Git docs answer **how it should be** — written before the code, often without it.
+The as-built record answers **how it actually is** — derived from what agents really
+wrote. Neither is a copy of the other, and neither outranks the other, because they
+answer different questions. **The gap between them is the finding**, not a defect.
+
+The duty runs at both ends of every task:
+
+- **Before starting** (docs-study stage) — `reconcile`, then read both sides for the
+  area you are about to touch. Resolve each divergence: the git doc is stale, or the
+  as-built record is wrong, or they genuinely disagree and that is a decision to make.
+  Building on an unresolved divergence means writing code against a system that does
+  not exist.
+- **After finishing** (docs stage) — `record` what you actually built, update the git
+  documents that state intent, then `reconcile` again. A task that updated one side
+  has left the next agent a divergence to find the hard way.
+
+`reconcile` is mechanical and says so: it compares ids, commits and presence, and refuses
+to judge whether the built thing matches the document. That reading is yours.
+
+Every project also carries a **generated snapshot** of its own wiring (`setup`) — commit
+it and link it from the agent instructions, so agents read the pipeline instead of
+inferring it.
+
+**Read `references/two-sources.md`** before the first reconcile, and whenever deciding
+which side a document belongs on.
+
+## Binding to task-pipeline
+
+This skill supplies stages; it does not define them. Stage names are
+`task-pipeline`'s own.
+
+| Stage | What to do here |
+|---|---|
+| 0 Intake grill | Add the cloud KB and the board to the harvest's source ledger; `acquire` **before** the brief is committed |
+| 1 Docs study | `reconcile` — study git docs **and** the as-built record, resolve every divergence before writing code |
+| 2 Brainstorm | `journal`; warn if a live run holds an overlapping key |
+| 3 Spec | `reserve` every id before writing it to git |
+| 4 Plan | Register file ownership for the plan's parallel groups |
+| 5 Dev | Lease renews itself; own the submodule-commit → parent-gitlink bump |
+| 6 Tests · 7 Lint · 8 Post-deploy | `journal` each gate result |
+| 9 Docs + wiki | The main write point — `record` what was built, update the git docs, `signal` the dependency flips, `reconcile` again, then `board` |
+| 10 Acceptance | `release` every lease, write the durable claim tag through to done |
+
+**Read `references/pipeline-binding.md` when wiring `pipeline.json`** — it holds the
+`skills[]` entries and the gate expressions.
+
+## Configuration
+
+Two files, and the split between them is the whole security model.
+
+**`.claude/agent-sync.json`** — *shape*, committed: which backend, TTLs, which files
+are guarded, which registers exist, which gates to run.
+
+**`.env.agent-sync`** — *identity*, created by `init`, mode 600, gitignored:
+
+```
+AGENT_SYNC_BACKEND=outline
+AGENT_SYNC_OUTLINE_URL=https://<instance>
+AGENT_SYNC_OUTLINE_TOKEN=          # the operator fills this line, nobody else
+AGENT_SYNC_OUTLINE_COLLECTION=     # printed by `bootstrap`
+```
+
+Load it before running agents:
+
+```bash
+set -a && . ./.env.agent-sync && set +a
+```
+
+Never write a host name or token into the config, a test, an example or a commit. Do not
+handle a token value, echo it, or pass it in `argv`. If the operator offers one in chat,
+tell them to put it in that file instead.
+
+**A submodule's config declares only its own registers.** Cross-repository facts belong to
+the parent; a service repo listing the parent's decision register is a config defect.
+
+## Backends
+
+| Backend | Read when |
+|---|---|
+| `outline` | `references/backend-outline.md` — before any Outline call |
+| `fs` | `references/backend-fs.md` — local files, no shared awareness |
+
+**Read `references/adapter-contract.md` before adding a backend** — six primitives, the
+capability flags, and a degradation path that must be honest.
+
+## Generated objects
+
+The board and the mirror are machine-written. Their first line is
+
+```
+<!-- agent-sync:generated source=<repo>@<sha> at=<iso8601> — edit in git, not here -->
+```
+
+A write to an object missing that marker is refused, not forced. If a human took over a
+generated page, report it and stop.
+
+The mirror is a **rendering** of git, stamped with the source commit. It has no
+authority. When its stamp and `HEAD` disagree, the board gate fails — that is
+drift, not a formatting problem.
+
+## Non-negotiables
+
+- Append, read back, then act. Never rewrite a coordination document.
+- `release` what you `acquire`, on every path including failure.
+- Credentials never reach `argv`, a log line, or the repository.
+- Degrade out loud. `ungated` is an acceptable state; a false claim of enforcement is not.
+- Everything the cloud holds about a durable fact is a link to git, never a substitute.
+
+## References
+
+Each file is loaded on its own trigger, not by default.
+
+| File | Read it when |
+|---|---|
+| `references/adapter-contract.md` | adding or auditing a knowledge backend |
+| `references/lease-protocol.md` | changing acquisition, expiry, stealing or id allocation |
+| `references/backend-outline.md` | making any Outline API call, or debugging one |
+| `references/backend-fs.md` | running without a cloud backend, or explaining degraded mode |
+| `references/pipeline-binding.md` | wiring `pipeline.json`, or adding a stage hook |
+| `references/hooks.md` | installing, debugging or removing the Claude Code hooks |
+| `references/two-sources.md` | before the first reconcile, or when deciding where a document belongs |
+| `references/roadmap.md` | configuring `claimTags`, taking or closing a task, or re-planning a board |
+
+If this copy arrived without `references/`, fetch them from
+`https://raw.githubusercontent.com/appvillis-com/agent-sync/main/plugins/agent-sync/skills/agent-sync/references/<file>`.

package/plugins/agent-sync/skills/agent-sync/references/adapter-contract.md

@@ -0,0 +1,80 @@
+# Adapter contract
+
+**Read this when** adding a knowledge backend, auditing one, or deciding whether a
+candidate backend can be trusted with leases.
+
+A backend is an adapter that implements six primitives and declares three
+capabilities. Nothing else about it is the coordinator's business.
+
+## Primitives
+
+| Primitive | Signature | Semantics |
+|---|---|---|
+| `tree.ensure` | `(path) -> id` | Idempotently create the container/document at `path`, return its id. MUST NOT overwrite existing content. |
+| `log.append` | `(id, line) -> ok` | Append exactly one `\n`-terminated line to the end of the object's text, **server-side**, with no read-modify-write cycle. |
+| `log.read` | `(id) -> text` | Return the object's full text. Line order MUST be identical for every reader at a given revision. |
+| `doc.put` | `(id, text) -> ok` | Replace the object's text wholesale. Generators only. |
+| `doc.get` | `(id) -> text` | Return the object's text. |
+| `search` | `(query, limit) -> [{id,title,snippet}]` | Full-text search. Feeds the pipeline's stage-0 knowledge harvest. |
+
+## Capabilities
+
+```json
+{ "atomicAppend": true, "totalOrderRead": true, "search": true,
+  "exclusiveLease": false }
+```
+
+- **`atomicAppend`** — `log.append` reaches the server as an append. If the adapter
+  implements it as *read text, concatenate, write text back*, this is **false**, no
+  matter how fast that is.
+- **`totalOrderRead`** — concurrent appends land in one order and every reader sees
+  the same order. A backend that merges concurrently, or that returns per-reader
+  views, is **false**.
+- **`search`** — `search` is implemented rather than stubbed.
+- **`exclusiveLease`** — whether *this backend* can decide a contended lease. Almost
+  always **false**: it requires compare-and-swap, and none of the document stores has
+  it. Declaring it true without one is the most damaging lie an adapter can tell, so
+  the default is false and the burden of proof is on the adapter.
+
+## Degradation — non-negotiable
+
+**No adapter is the lease authority.** Exclusion is an atomic local lock; the adapter
+carries the record and the awareness. If `atomicAppend` or `totalOrderRead` is false the
+coordinator additionally:
+
+1. states it once, in plain words, at session start;
+2. keeps the local lock as the only arbiter (`references/backend-fs.md`);
+3. marks every run `ungated` on the board.
+
+There is no third option. A lease that is not actually exclusive is worse than no
+lease at all, because the other agent stops checking.
+
+## Errors and retries
+
+Every primitive returns a typed failure; none may raise past the caller.
+
+| Condition | Handling |
+|---|---|
+| Rate limited | Honour the backend's own retry hint; exponential backoff; at most 5 attempts, then fail loudly |
+| Auth failure | Fail immediately. Never retry a credential — it is not going to become valid |
+| Not found | For `tree.ensure`, create. For everything else, report the missing path; do not create silently |
+| Transport error | Retry twice with backoff, then fail with the underlying message intact |
+
+Never swallow an error into a success. A coordination layer that reports a write it
+did not make is the failure this whole design exists to prevent.
+
+## Credentials
+
+- Read from the environment only. Never from the config file, never from `argv`.
+- Never echo, never log, never include in a journal line or a board render.
+- When absent: degraded mode with a clear message, not a crash and not a prompt.
+
+## Adding a backend — checklist
+
+- [ ] Six primitives implemented, each returning a typed failure
+- [ ] Three capabilities declared **honestly**; `atomicAppend` false unless the append is server-side
+- [ ] Credentials read from env only, and absent from every code path that builds a command line
+- [ ] Rate-limit hint honoured
+- [ ] `tree.ensure` proven idempotent by calling it twice against a live instance
+- [ ] `log.append` proven atomic: two processes appending 100 lines each yield 200 lines, in one order both readers agree on
+- [ ] Degradation path exercised: force `atomicAppend: false` and confirm the coordinator refuses lease authority and says so

package/plugins/agent-sync/skills/agent-sync/references/backend-fs.md

@@ -0,0 +1,57 @@
+# Filesystem backend — the degraded mode
+
+**Read this when** running without a cloud backend, or explaining to an operator
+what they do and do not get.
+
+## What it is
+
+Plain files under `.agent-sync/` in the repository:
+
+```
+.agent-sync/
+├── claims.log          # the append log
+├── reservations.log
+├── signals.log
+├── runs/<runId>.log
+└── board.md            # generated
+```
+
+## Capabilities — declared honestly
+
+```json
+{ "atomicAppend": false, "totalOrderRead": false, "search": false }
+```
+
+`atomicAppend` is false: agents on two clones append to two files, and a merge decides the
+order after the fact — not at the moment the protocol needs one.
+
+## What follows from that
+
+**No adapter is ever the lease authority** — not this one, not the cloud. Exclusion comes
+from `leaseBackend` (`local` = `O_EXCL`, `git` = a pushed ref). What this backend costs is
+**awareness**: with it configured, the coordinator:
+
+1. says so at session start, in one plain sentence;
+2. keeps the lease exactly as configured — `leaseBackend` is independent of this choice;
+3. marks every run `ungated` on the board, because nobody else can read the state.
+
+## The lease is not this backend's job
+
+Do not look for a lease mechanism here. `leaseBackend: "local"` decides with an atomic
+file create; `leaseBackend: "git"` decides with a pushed ref whose non-fast-forward
+rejection is a real compare-and-swap. Both work regardless of which knowledge backend is
+configured — see `lease-protocol.md`.
+
+## When this is the right choice
+
+- A project with one agent at a time, which wants the journal and the board without
+  standing up a service.
+- An air-gapped or offline repository.
+- A first run, before the operator has chosen a knowledge backend.
+
+## When it is the wrong choice
+
+- Several agents at once: they hold leases correctly but cannot **see** each other, and
+  the whole point of the coordination plane is that they can.
+- Anything where the operator has been told the project is coordinated. The lease still
+  works; the awareness does not, and the board must keep saying `ungated`.

package/plugins/agent-sync/skills/agent-sync/references/backend-outline.md

@@ -0,0 +1,103 @@
+# Outline backend
+
+**Read this when** making any Outline API call or debugging one.
+
+[Outline](https://www.getoutline.com) is a collaborative knowledge base, available
+hosted or self-hosted. Both work; the instance URL is configuration, never code.
+
+## Shape of the API
+
+- Base: `<AGENT_SYNC_OUTLINE_URL>/api` — the instance URL comes from the
+  environment. **Never hardcode a host, not even in a test or an example.**
+- **Every endpoint is `POST`**, including reads.
+- `Authorization: Bearer <token>` and `Content-Type: application/json`.
+- Every response is enveloped: `{"ok": true, "status": 200, "data": {…}}` or
+  `{"ok": false, "error": "…", "message": "…", "status": 4xx}`. Check `ok`; an
+  HTTP 200 with `ok: false` is a failure.
+
+## Capabilities
+
+```json
+{ "atomicAppend": true, "totalOrderRead": true, "search": true }
+```
+
+`atomicAppend` is true because `documents.update` accepts
+`editMode: "append"`, which appends server-side without a read-modify-write cycle.
+
+**There is no `lastRevision` parameter and no other optimistic-concurrency
+control.** This is the single most important fact about this backend: a `replace`
+update is last-write-wins and will silently discard a concurrent edit. Coordination
+state is therefore never modelled as a document you rewrite — see
+`lease-protocol.md`.
+
+## Primitive mapping
+
+| Primitive | Call | Body |
+|---|---|---|
+| `tree.ensure` (container) | `POST /api/collections.create` | `{name}` — or `collections.list` first and reuse |
+| `tree.ensure` (document) | `POST /api/documents.create` | `{collectionId, parentDocumentId?, title, text, publish: true}` |
+| `log.append` | `POST /api/documents.update` | `{id, text: "<line>\n", editMode: "append"}` |
+| `log.read` | `POST /api/documents.info` | `{id}` → `data.text` |
+| `doc.put` | `POST /api/documents.update` | `{id, text, editMode: "replace"}` |
+| `doc.get` | `POST /api/documents.info` | `{id}` → `data.text` |
+| `search` | `POST /api/documents.search` | `{query, limit, collectionId?}` |
+
+`publish: true` on create, or the document stays a draft and no other agent can
+read it.
+
+## Calling it without leaking the token
+
+`curl -H "Authorization: Bearer $TOKEN"` puts the credential in `argv`, where every
+other process on the machine can read it. Use a config file on stdin instead:
+
+```bash
+payload=$(mktemp); chmod 600 "$payload"
+printf '%s' "$body_json" > "$payload"
+
+curl -sS --config - <<EOF
+url = "$AGENT_SYNC_OUTLINE_URL/api/documents.update"
+request = "POST"
+header = "Authorization: Bearer $AGENT_SYNC_OUTLINE_TOKEN"
+header = "Content-Type: application/json"
+data-binary = "@$payload"
+EOF
+
+rm -f "$payload"
+```
+
+The heredoc reaches curl on stdin, so neither the token nor the payload appears in
+the process table. Delete the payload file on every exit path.
+
+**Prefer the bundled `scripts/agent_sync.py` over hand-rolling any request.** It
+calls the API through `urllib` inside its own process — no subprocess, no `argv`,
+nothing for another process to read. The `curl` recipe above is for the case where
+you must issue a call by hand; it is the safe way to do that, not the better way.
+
+## Rate limits
+
+`429` comes back with `Retry-After` (seconds) plus `X-RateLimit-Limit`,
+`X-RateLimit-Remaining` and `X-RateLimit-Reset`. Honour `Retry-After`, then back off
+exponentially, at most 5 attempts. Do not spin.
+
+## Getting a token
+
+The operator creates an API key in their own instance's settings and puts it in
+their environment. Do not ask for the value in chat, do not read it back, and do not
+write it anywhere in the repository.
+
+```
+AGENT_SYNC_OUTLINE_URL=https://<your-instance>
+AGENT_SYNC_OUTLINE_TOKEN=<created by the operator>
+AGENT_SYNC_OUTLINE_COLLECTION=<collection id, printed by `init`>
+```
+
+## Verifying an instance
+
+```bash
+curl -sS -o /dev/null -w '%{http_code}\n' -X POST \
+  "$AGENT_SYNC_OUTLINE_URL/api/auth.info" -H 'Content-Type: application/json' -d '{}'
+```
+
+`401` is the healthy answer without a token: the host is up and demands auth.
+A connection error means the URL is wrong or the instance is down — that is not a
+credentials problem, and retrying with a different token will not help.