dsh-compound-engineering 0.0.0-stage → 0.1.0

package/skills/ce-promote/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: ce-promote
+description: "Draft launch or promotion copy for a shipped feature."
+disable-model-invocation: true
+argument-hint: "[optional: what shipped and/or channels, e.g. 'a tweet thread and a LinkedIn post']"
+---
+
+# Promotion Copy
+
+Turn a feature that just shipped into copy-pasteable, user-facing announcement copy, right inside the engineering workflow — so the messaging doesn't wait for a separate marketing pass.
+
+**Done when:** every drafted channel is presented as a labeled, copy-pasteable block and the user has been offered a revision. **This skill drafts only — it never posts, publishes, schedules, commits, or opens PRs.** Posting is a human action.
+
+It works **with or without Spiral**: with nothing installed it drafts directly from the editorial and social fundamentals in Path B (Direct drafting). When the Spiral CLI is present and authed, drafts come back voice-matched to the user's brand — an enhancement, never a requirement.
+
+## Phase 1 — Figure out what shipped
+
+A free-form description in the arguments is the source of truth. Otherwise derive it from context, using what is available and never waiting on any single source:
+
+- **Merged/active PR** — `gh pr view --json title,body,url` (the title and body usually state the user-facing value)
+- **The diff** — `git diff main...HEAD --stat`, skimming notable changes so the claim is grounded in what actually changed
+- **Changelog** — the top or `[Unreleased]` entry in `docs/changelog.md`, `CHANGELOG.md`, or similar
+- **Recent commits** — `git log --oneline -15` for the arc of the change
+
+Then write a 1-3 sentence summary of the **user-facing value**: what a user can now do that they couldn't before, and why they'd care. Outcome, not implementation — "You can now export any report to CSV in one click", not "Added a CsvSerializer and an export endpoint." If you can't confidently tell what shipped, ask one short question rather than guessing.
+
+## Phase 2 — Pick channels
+
+Default to an X post (or short thread) plus a one-line changelog / release blurb. If the user named channels — LinkedIn, email, a blog intro, a demo script — draft those instead of or in addition to the defaults. Scale to the change: a small fix warrants one or two short drafts, a flagship feature a cross-channel set. Don't force a fixed template.
+
+## Phase 3 — Draft the copy
+
+Detect Spiral's state with two quick, non-blocking commands:
+
+```bash
+which spiral
+spiral auth status --json 2>/dev/null
+```
+
+- No binary -> **Absent**
+- `"authenticated": true` -> **Ready**
+- `"authenticated": false` -> **Unauthed**
+- Output isn't JSON (older CLI that ignores `--json`) -> ready iff it contains `spiral_sk_`, else unauthed
+
+**Ready** -> Path A (Spiral ready). **Absent or Unauthed** -> Path 0 (Offer Spiral setup), then Path A if setup completes, else Path B (Direct drafting). Never let a Spiral failure, timeout, or odd output block or slow the skill — when in doubt, treat it as not-ready and continue.
+
+### Path 0 — Offer Spiral setup (once, declinable)
+
+Go straight to Path B when running non-interactively — there is no human to answer. Otherwise offer setup **once**: read `references/spiral-cli.md` and follow its Path 0 section for the opt-out check, the blocking question, the agent-run `spiral login --json` flow (the API key never passes through the agent, and the user never pastes one into chat), the install path, and how the opt-out is recorded. Skip to Path B only when *that* check finds a recorded opt-out. That section defines what counts as recorded; a naive config scan misreads `ce-setup`'s commented template example as one, silently suppressing the offer.
+
+Two properties that section depends on: **any dismissal records the opt-out**, so a single first-run decline stops the offer for good in this repo, and a decline always proceeds to Path B rather than blocking. If a human is present but no blocking-question tool is in the current tool list, fall back to a numbered list of the two options in chat and wait — do not skip the offer, and never call a user-facing question tool to discover whether one exists.
+
+### Path A — Spiral ready (voice-matched)
+
+**Read `references/spiral-cli.md` before composing the prompt.** Whether Spiral returns a multi-channel set or several variations of one channel is phrasing-driven (channel keywords and cue words vs. `--num-drafts`), and getting it wrong silently returns the wrong number or shape of drafts — don't restate those rules from memory.
+
+Always pass `--instant` and `--json`; parse `drafts[]` (each carries its own `channel`) plus `session_id`. **Present every returned draft, grouped by `channel`** — Spiral decides how many drafts per channel, so never assume one-per-channel or drop extras. If the `spiral write` call errors or returns no usable drafts, fall back silently to Path B for the affected channels.
+
+### Path B — Direct drafting
+
+No Spiral needed. Draft every channel through the `ce-noslop` skill. (The Spiral path goes further: brand-voice matching, humanization, saved styles, and cross-channel campaign orchestration.)
+
+**Every channel:**
+
+- Lead with the user-facing outcome — what someone can now do, not how it was built.
+- One idea per piece.
+
+**Distributed channels:** the first line is the hook and has to make the reader want the next line (feeds truncate). No preamble. Match each channel's native shape and length; never reuse one draft verbatim across channels. One clear CTA where the channel supports it. Hashtags 0-2, and only where the channel expects them.
+
+**Per channel:**
+
+- **X** — value in the first line; ~1-3 tight lines. Thread only when there's more than one beat worth its own line.
+- **Changelog / release blurb** — one declarative line naming the new capability. Plain, not promotional.
+- **LinkedIn** — a short paragraph: human angle (why it matters), then the what. Warmer than X.
+- **Email** — benefit-stating subject + 2-4 sentence body + one CTA.
+- **Blog intro** — one opening paragraph framing the problem and the new capability; leave the deep-dive to the author.
+- **Demo script** — 3-6 spoken beats: hook, problem, action, payoff.
+
+One strong draft per channel by default; produce more only when asked ("3 tweet options"), capped at ~3.
+
+## Phase 4 — Present the drafts
+
+Show every draft as a clean, copy-pasteable block labeled by channel:
+
+```
+### X post
+<the copy>
+```
+
+When Path A produced them, also show the `session_id` and each draft's `url` so the user can open and tweak them in the Spiral web app. Offer to revise (tone, length, angle, more variations, another channel). **Do not post, publish, schedule, commit, or open a PR** — end by reminding the user the drafts are theirs to ship.

package/skills/ce-promote/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/skills/ce-promote/references/spiral-cli.md

@@ -0,0 +1,149 @@
+# Spiral CLI reference
+
+Spiral (`@every-env/spiral-cli`) drafts copy in a user's brand voice. `ce-promote` uses it as an **optional enhancement** — every call must be wrapped so a missing, unauthed, or erroring CLI never blocks the skill.
+
+## Detection — three states
+
+```bash
+which spiral
+spiral auth status --json 2>/dev/null
+```
+
+- **Absent** — `which spiral` finds nothing. → Path 0 (offer to install + connect).
+- Otherwise parse `spiral auth status --json`:
+  - **Ready** — `"authenticated": true` (equivalently `"status": "authenticated"`, any `source`). Use Path A.
+  - **Unauthed** — `"authenticated": false`. → Path 0 (offer to sign in).
+  - **Older CLI** that ignores `--json` (output isn't JSON): fall back to the human-readable signal in that same output — ready iff it contains `spiral_sk_`, else unauthed.
+
+Prefer the JSON `authenticated` flag over substring-matching `spiral_sk_` — the flag is the designed contract, and the substring is only the backward-compat fallback. Any error or timeout → treat as not-ready and continue; never block.
+
+## Path 0 — Offer setup (first run, declinable)
+
+When Spiral is unauthed or absent, offer setup once. First check the opt-out so this never nags.
+
+### Check the opt-out
+
+<!-- ce-config-layers:start -->
+**Resolve ordinary CE yaml keys from the two repo files.**
+
+- **Read** `<repo-root>/.compound-engineering/config.local.yaml`, then `config.yaml` (`<repo-root>` = `git rev-parse --show-toplevel`). Missing files are skipped. Gitignore does not change resolution.
+- **Win** with the first active (non-commented) value. For scalars, empty is unset; an invalid value continues to the next layer, then the skill default. For lists and maps, a present key — including an empty list or map — replaces the whole key.
+- **Do not** use this rule for `docs_root` — that key is `config.yaml` only.
+<!-- ce-config-layers:end -->
+
+Resolve the repo root (never CWD), then apply the ordinary-key rule above for `ce_promote_spiral_optout`. If the winning **uncommented** top-level value is exactly `true`, **skip Path 0** and go straight to Path B (draft the post directly, without the Spiral CLI). **Ignore commented lines** — `ce-setup`'s template ships a `# ce_promote_spiral_optout: true` example, and a commented line is documentation, not an opt-out (a naive substring match would wrongly suppress the offer for any project that accepted the default template). Otherwise, offer setup.
+
+### Ask
+
+Use the host's blocking question tool already in the current tool list (match by capability, not by a host-specific name). Presence in the current tool list is proof the tool exists; never call a user-facing question tool to discover whether it exists. If a matching tool is listed but unloaded, use the host's tool-discovery primitive to load that capability — do not search for another host's tool name. If no such tool is in the list or a real question call errors, present the same options as a numbered list in chat and wait for a reply — never silently skip.
+
+For the **unauthed** state, the **agent itself** runs `spiral login --json` (CLI >= 1.8.0): it's non-blocking and the API key never passes through the agent — the agent shares the returned `auth_url`, the user approves in a browser, and the credential is delivered server->CLI. The blocking question is mainly the escape hatch.
+
+Use the question stem to teach the mechanic, offer the escape hatch, AND disclose that declining is durable (so the permanent side effect isn't hidden behind a transient-sounding label): "Spiral personalizes and humanizes the copy in your voice. [It's installed but not signed in / It isn't installed yet] — sign in now, or have the agent draft directly without Spiral? (Declining drafts your copy now and won't bring up Spiral again in this project; you can set it up anytime by asking.)"
+
+Offer exactly **two** options (labels must be self-contained):
+
+- **Unauthed** state: `Sign in to Spiral` · `Draft directly without Spiral`
+- **Absent** state: `Install Spiral` · `Draft directly without Spiral`
+
+There is deliberately no separate "don't ask again" option: **dismissing is itself the opt-out.** A single first-run decline records the flag and the offer never recurs in this repo. This is what keeps a per-ship skill from nagging — never make the user choose a special variant to stop being asked.
+
+### Act on the choice
+
+- **Sign in to Spiral** (installed, unauthed) — the agent runs `spiral login --json` itself. It's non-blocking, and the **API key never touches the agent** (the token is exchanged server->CLI via a device-code flow). Parse the JSON `status`:
+  - `already_authenticated` — `{ "authenticated": true, "status": "already_authenticated", "prefix": "..." }`: a credential already exists; nothing to approve. Go to Path A. (To switch accounts the user runs `spiral logout` first.)
+  - `pending` — `{ "status": "pending", "auth_url": "...", "user_code": "ABCD-2345", "expires_in": 900 }`: surface the `auth_url` for the user to open and approve in their browser (the `user_code` is embedded in the URL — show it too so they can confirm it matches), then wait. Once the user says they've approved, confirm by running `spiral auth status --json`: it returns `"authenticated": true` when claimed, or `"status": "pending"` if not yet (re-check, don't busy-loop with sleeps — let the user's confirmation drive the re-check). If it stays unclaimed or the code expires (~`expires_in`s), offer to retry or fall to Path B. On success -> Path A.
+  - **Never have the user paste an API key into chat** — with agent login the agent never handles the key at all.
+  - **Older CLI (< 1.8.0, no agent login):** if `spiral login --json` returns the legacy `API key required ... --token` text instead of JSON, suggest `npm i -g @every-env/spiral-cli@latest`, or have the user run `spiral login` themselves in their terminal (browser sign-in) and re-check `spiral auth status`. If they would rather not, go to Path B.
+- **Install Spiral** (absent) — the pairing-code command installs and connects in one step. Direct the user to Settings → Connect an Agent at https://app.writewithspiral.com to copy their command, which looks like:
+  ```bash
+  npx @every-env/spiral-cli@latest setup --pairing-code <code>
+  ```
+  The pairing code is single-use and expires in ~15 minutes, so the user must fetch a fresh one from the web app — do not hardcode it. Once installed, if still unauthed, follow the **Sign in to Spiral** flow above (`spiral login --json`). If the user can't or won't install, go to Path B.
+- **Draft directly without Spiral** — record the opt-out (below) so the offer never re-prompts in this repo, then go to Path B. (A failed/abandoned **sign-in or install** attempt does NOT record the opt-out — only an explicit "draft directly" dismissal does — so a user whose auth didn't complete still gets one clean re-offer next run.)
+
+### Record the opt-out (best-effort)
+
+Resolve the repo root, then add `ce_promote_spiral_optout: true` as a top-level key to `<root>/.compound-engineering/config.local.yaml`, using the native file-write/edit tool:
+
+- **File already exists:** ensure an **uncommented** `ce_promote_spiral_optout: true` line is present — add one (or uncomment the example) unless an uncommented one already exists. A commented `# ce_promote_spiral_optout: true` (from `ce-setup`'s template) does **not** count as present; leaving only the comment would let the comment-ignoring read path re-prompt next run.
+- **File absent:** create it (and its `.compound-engineering/` directory) with the key, AND make sure the machine-local config won't be committed. Check whether the root-relative path `<root>/.compound-engineering/config.local.yaml` is already ignored (`git check-ignore -q <path>`); if it isn't, append `.compound-engineering/*.local.yaml` to git's **local exclude file** — resolve that file's path with `git rev-parse --git-path info/exclude` (this is correct in worktrees too, where `.git` is a *file* and `info/exclude` lives in the common git dir; do **not** hardcode `<root>/.git/info/exclude`). Use the local exclude, **not** `.gitignore`: it keeps the rule local and avoids dirtying a tracked file on what was a drafts-only action. `ce-setup` is the canonical place that adds the shared `.gitignore` entry for teammates. Without any ignore, a user who runs `/ce-promote` before `/ce-setup` could accidentally commit machine-local opt-out state.
+
+If the root can't be resolved or any write fails, proceed to Path B anyway; the opt-out is a convenience, never a blocker.
+
+After recording, confirm it in one line so the write isn't silent and the user knows how to undo it — e.g. "Got it — I won't bring up Spiral here again (saved to `.compound-engineering/config.local.yaml`, kept out of git). Want it back later? Just ask, or remove the `ce_promote_spiral_optout` key." Keep it to a single line; don't belabor it.
+
+## Generate
+
+```bash
+spiral write "<prompt>" --instant --num-drafts <1-5> --json
+```
+
+- `--instant` — skip clarifying questions. **Always use it**; this is a headless context with no human mid-call.
+- `--json` — machine-readable output. Always use it.
+- `--num-drafts <1-5>` — number of drafts (single-channel mode only; see gotcha).
+- `--workspace <uuid>` — scope to a brand-voice workspace. List with `spiral workspaces`. Use only if the user names one.
+- `--style <uuid>` — pin a specific voice/style. Use only if the user names one.
+
+### Output shape
+
+JSON with (fields verified against the Spiral CLI `write` output):
+
+```json
+{
+  "session_id": "uuid",
+  "status": "complete | needs_input",
+  "drafts": [
+    { "id": "uuid", "title": "...", "content": "markdown", "channel": "x",
+      "url": "https://app.writewithspiral.com/chat/<session>?draft=<id>", "display_hint": "inline | expandable" }
+  ],
+  "text": "pipeline commentary — DO NOT show the user unless drafts is empty",
+  "style_used": null,
+  "quota_remaining": 42
+}
+```
+
+- `channel` (lowercase) is one of `x`, `linkedin`, `email`, `newsletter`, `blog`, `instagram_tiktok`, `research`, or `null`.
+- `url` opens that draft in the Spiral web app for editing. Drafts persist to the user's account — surface `session_id` + each `url` in your output (Phase 4).
+- **Do not surface the `text` field** to the user — it's internal pipeline commentary. Only fall back to it if `drafts` is empty.
+- With `--instant`, `status` should be `complete`. If it comes back `needs_input` (rare with `--instant`), don't relay Spiral's questions to the user — either answer from the context you already have via a `--session` follow-up, or fall back to Path B for that channel.
+
+If parsing fails or `drafts` is empty, fall back to direct drafting for the affected channels.
+
+## The multi-channel / cue-word gotcha (important)
+
+Multi-channel output is **phrasing-driven, not a flag.** Spiral enters "campaign mode" when the prompt contains **≥2 channel keywords** (tweet/X, LinkedIn, email, blog, …) **OR** any cue word: `campaign`, `across`, `multi-channel`, `everywhere`, `cross-post`.
+
+Two consequences to encode:
+
+### (a) To get N variations of ONE channel
+
+Ask for `"3 tweet options for <feature>"` and:
+
+- **Avoid** the cue words above. Ironically, a prompt literally containing `campaign` or `multi-channel` trips campaign mode — so describe the task **without** those words.
+- Pass `--num-drafts 3`.
+
+If you accidentally include a cue word, Spiral decides it's a single campaign piece and returns **1 draft**, ignoring `--num-drafts`.
+
+✅ `spiral write "3 tweet options for one-click CSV export" --instant --num-drafts 3 --json`
+❌ `spiral write "a tweet campaign for CSV export" --instant --num-drafts 3 --json`  (collapses to 1 draft)
+
+### (b) To get a real multi-channel set
+
+Phrase the prompt with the multiple channels named. Spiral returns **one set of drafts per channel**, each draft carrying its `channel`. In this mode **`--num-drafts` is ignored** — per-channel counts apply.
+
+✅ `spiral write "announcing one-click CSV export — a tweet and a LinkedIn post" --instant --json`
+✅ `spiral write "a campaign across email, LinkedIn, and Twitter for CSV export" --instant --json`
+
+This one-call cross-channel set is the ideal fit for `ce-promote` when the user wants to announce across surfaces.
+
+**Spiral picks per-channel counts itself.** In campaign mode the count per channel is Spiral's call, not yours — e.g. "a tweet and a LinkedIn post" (verified live) returned 3 X drafts + 2 LinkedIn drafts (5 total), each tagged with its `channel`. Group the returned `drafts` by `channel` for Phase 4; don't assume one per channel.
+
+## Failure handling
+
+Detection that comes back not-ready routes through Path 0 above. Once on Path A, any of these → fall back to direct drafting (SKILL.md Path B), silently, for the affected channels:
+
+- `spiral write` exits non-zero, hangs, or emits non-JSON
+- `drafts` is empty or missing expected fields
+
+Never surface raw Spiral errors to the user as a blocker. The skill always produces drafts.

package/skills/ce-proof/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: ce-proof
+description: Publish, read, comment on, or edit markdown in Proof. Use for Proof links, sharing specs/plans/drafts, or publish handoffs from planning workflows; avoid proofread, math, evidence, or proof-of-concept meanings.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - WebFetch
+---
+
+# Proof - Collaborative Markdown Editor
+
+Proof is a collaborative document editor for humans and agents. It is reached through the hosted web API at `https://www.proofeditor.ai`, over HTTP from `Bash`.
+
+**Outcome:** the user holds a working tokenized Proof link, or the doc carries the read, comment, suggestion, or edit they asked for.
+
+**Done:** the operation is confirmed at its own level, and the user has the result plus a short summary. A create is confirmed by the `tokenUrl` it returned. A mutation is confirmed by `ok: true`; on a `202` or a `partial: true` response, confirm by re-reading `v3/document`. A pull is confirmed by the local file it wrote, and a read by the content it returned.
+
+**Read `references/api.md` before the first Proof read or mutation, HTTP or MCP.** It defines the endpoints: `share/markdown`, the v3 document and edit endpoints, presence, title, and `DELETE /api/documents/<slug>`. It also carries the operation tables, the error and retry classes, and the `curl` permission hint for Claude Code.
+
+**Read `references/workflows.md`** before reviewing a shared doc, before creating and sharing one, and before pulling a doc to a local file. Those flows have exact recipes there.
+
+If typed `proof_*` MCP tools are already available in the harness (`proof_share_markdown`, `proof_v3_document`, `proof_v3_edit`, `proof_presence`, `proof_document_title`, `proof_document_delete`, `proof_report_bug`), prefer them. Otherwise use the HTTP recipes. In MCP mode the server injects `by`, `X-Agent-Id`, and presence identity. Pass the `?token=` value from the Proof URL as `shareToken` for edits and presence on docs the signed-in user does not own.
+
+Delete authority is unchanged in MCP mode. An unclaimed doc still needs its `ownerSecret`, and a claimed doc needs its owner's session. An editor `accessToken` passed as `shareToken` cannot delete.
+
+## Identity
+
+Every write is attributed with both fields, and they do not vary. The machine ID is `ai:compound-engineering`, sent as `by` on every op and as the `X-Agent-Id` header. The display name is `Compound Engineering`, sent as `name` on `POST /presence`, set once per doc session so Proof binds it to that agent ID. A caller may pass a different `identity` pair when a distinct sub-agent should own the doc. Never improvise a variant such as `ai:compound`.
+
+## Credentials and boundaries
+
+- `accessToken` is the everyday bearer for read, edit, presence, and events. `ownerSecret` carries owner authority only — delete and other owner-level ops — and is never the everyday bearer. Capture both at create time, and persist `ownerSecret` for the session separately from `accessToken`, in shell vars or equivalent; it is required for owner delete while the doc is unclaimed. Neither belongs in repo-tracked files, commits, or durable logs, and `ownerSecret` never appears in user-facing copy.
+- Hand humans the tokenized link (`tokenUrl`), never a bare `/d/<slug>` — the token in that link is also what lets a signed-in user claim an ownerless doc.
+- Public creates are ownerless until a signed-in Every user claims the doc in the browser. Claiming permanently revokes `ownerSecret` while `accessToken` keeps working, so delete then needs the owner's Every session — ask the owner, or use their session token. Two responses mean the secret was revoked: a `403` with `code: "DOCUMENT_DELETE_FORBIDDEN"` and `reason: "CREDENTIAL_NOT_OWNER"`, or a `401` when presenting the creation `ownerSecret`. Stop using the secret rather than retrying. `reason: "DOCUMENT_HAS_NO_OWNER"` is the opposite: the doc is still unclaimed, so only the original `ownerSecret` can delete it and an Every session cannot.
+- Never put secrets, credentials, API keys, private tokens, or sensitive personal data into a Proof doc unless the user explicitly approves, and never silently replace a repo-tracked project doc with a Proof link.
+- Emptying the markdown does **not** scrub comment marks. Quotes and commentary stay readable to anyone with the share credential, so a content wipe is not a privacy cleanup. Deleting the document is — with `ownerSecret` while the doc is unclaimed, or as the owner after a claim.
+- Do not auto-delete after a publish handoff. Review docs must linger. Delete when the user asks, or when finishing an explicitly ephemeral scratch doc.
+
+## Publish mode
+
+The primary use is one-way publishing. Read an existing local markdown file in full, post its contents as the new doc's body, and hand the user the shareable URL. The local file stays canonical — publishing syncs nothing back to disk.
+
+Two entry points share those mechanics. One is a bare user request naming a local markdown file ("share this to proof", "get me a proof link for this doc"); ask which file only if it is ambiguous, and expect no upstream caller. The other is a handoff from `ce-brainstorm`, `ce-ideate`, or `ce-plan` passing the file path and title.
+
+Only publish markdown. If the source is an HTML unified plan, return the local browser/open path instead of uploading it. When publishing a unified plan, label the title by readiness when it is known, e.g. `Plan: <title> (requirements-only)` or `Plan: <title> (implementation-ready)`.
+
+Publish the source file's bytes, never hand-written or placeholder content. `references/workflows.md` gives the `jq --rawfile` recipe that escapes newlines, quotes, and backticks correctly. After a publish handoff, show the user the URL and return control.
+
+## Editing
+
+`GET /api/agent/<slug>/v3/document` and `POST /api/agent/<slug>/v3/edit` are the only endpoints an agent reads from and writes to. Comments, replies, resolutions, suggestions, and content changes are all `operations` in the v3 edit body, so a path you did not read in `references/api.md` is one you invented.
+
+Read `v3/document` as the source of truth before editing. Then choose the narrowest operation that expresses the change: a scoped `replace`, `insert`, or `delete` for prose; `suggest` when the change should be visible as tracked changes; `set_document` only when the user asks for a whole-doc replacement, or the change cannot be expressed narrowly. Targets are visible text in `markdown`, never raw markdown syntax or block refs.
+
+`comments[]` and `suggestions[]` from that read are the review state. Reply, resolve, unresolve, accept, or reject by id. v3 has no delete-comment op. A comment marked `orphaned: true` is still readable and replyable, but its old quote is no longer a live anchor.
+
+Errors that mean stop and check, before retrying anything:
+
+- `TARGET_AMBIGUOUS` — the anchor matched more than once and nothing changed. Disambiguate with `occurrence` / `before` / `after` from `error.candidates`; never assume silent first-match, and never blind-retry a comment.
+- `retryable: false` — fix the request. `retryable: true` with `error.current` — re-resolve targets against `current`, then retry once.
+- `202` / `PENDING`, or `ok: false` with `partial: true` — the write may have committed. Re-read `v3/document` before chaining or reporting success, and retry only the failed op (a repeated `Idempotency-Key` replays safely).
+- Still failing after a fresh read and one safe retry — report the bug per `references/api.md` rather than looping.
+
+Pulling a doc down to a local file overwrites that file. When the pull is a side effect of some other action rather than something the user asked for, confirm the path first.

package/skills/ce-proof/references/api.md

@@ -0,0 +1,176 @@
+# Proof web API reference
+
+Required read before any Proof HTTP call. Endpoints, operation tables, error handling, and lifecycle; the skill body carries the identity, credential, and safety boundaries.
+
+## Web API
+
+On Claude Code, each new `curl` pattern prompts for permission. Suggest the allowlist rule `"Bash(curl * https://www.proofeditor.ai/*)"` under `permissions.allow` if the user wants a quieter session; do not add it silently.
+
+Auth on document surfaces (preferred first):
+
+- `Authorization: Bearer <accessToken>`
+- `x-share-token: <accessToken>`
+- `?token=<accessToken>` on the request URL
+
+Canonical agent read/write (v3 only — do not invent other agent mutation paths):
+
+- Read: `GET /api/agent/<slug>/v3/document`
+- Write: `POST /api/agent/<slug>/v3/edit`
+
+### Create a Shared Document
+
+No authentication required on the public create route. Returns a shareable URL with tokens.
+
+```bash
+curl -sS -X POST https://www.proofeditor.ai/share/markdown \
+  -H "Content-Type: application/json" \
+  -d '{"title":"My Doc","markdown":"# Hello\n\nContent here."}'
+```
+
+**Response fields to keep:**
+
+```json
+{
+  "slug": "abc123",
+  "tokenUrl": "https://www.proofeditor.ai/d/abc123?token=xxx",
+  "accessToken": "xxx",
+  "ownerSecret": "yyy",
+  "shareUrl": "https://www.proofeditor.ai/d/abc123",
+  "_links": {
+    "read": "https://www.proofeditor.ai/api/agent/abc123/v3/document",
+    "edit": { "method": "POST", "href": "/api/agent/abc123/v3/edit" },
+    "delete": { "method": "DELETE", "href": "/api/documents/abc123" }
+  }
+}
+```
+
+Use `tokenUrl` as the shareable link. Extract `slug`, `accessToken`, and `ownerSecret` immediately — `ownerSecret` is required for cleanup while the doc is still unclaimed.
+
+### Read a Shared Document
+
+If you already have a shared Proof URL, fetch with content negotiation or v3:
+
+```bash
+curl -sS -H "Accept: application/json" "https://www.proofeditor.ai/d/{slug}?token=<token>"
+curl -sS -H "Accept: text/markdown" "https://www.proofeditor.ai/d/{slug}?token=<token>"
+
+curl -sS "https://www.proofeditor.ai/api/agent/{slug}/v3/document" \
+  -H "Authorization: Bearer <token>" \
+  -H "X-Agent-Id: ai:compound-engineering"
+# -> { ok, revision, title, markdown, comments[], suggestions[], mutationReady? }
+```
+
+ACTIVE docs can be read tokenlessly via `v3/document`. Mutations, presence, and events need a tokenized credential. Tokenless `GET /d/<slug>` JSON reports `role: null` and no mutation links — that is truthful capability reporting, not a browser lock.
+
+`comments[]` and `suggestions[]` on the v3 read are the source of review state. Use a comment's `id` for `reply` / `resolve` / `unresolve`. Use a suggestion's `id` for `accept` / `reject`. v3 supports resolving and unresolving comments; it does **not** support deleting comments. A comment with `orphaned: true` and an empty `quote` has lost its anchor — its thread is still readable and replyable, but do not treat its old target text as a live anchor.
+
+When `mutationReady` is `false`, `revision` may be `null` — omit `baseRevision` and re-read shortly.
+
+### Edit a Shared Document
+
+Send `{ by, baseRevision?, operations: [...] }` to `POST /api/agent/{slug}/v3/edit`. Targets are **visible text** in `markdown` (not raw markdown syntax, not block refs). There is no base token. `baseRevision` (integer from the last read) is an optional conflict guard — omit it to apply at head. `Idempotency-Key` is optional; use one for important writes and retries.
+
+```bash
+curl -sS -X POST "https://www.proofeditor.ai/api/agent/{slug}/v3/edit" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <token>" \
+  -H "X-Agent-Id: ai:compound-engineering" \
+  -H "Idempotency-Key: $(uuidgen)" \
+  -d '{
+    "by":"ai:compound-engineering",
+    "operations":[
+      {"op":"replace","find":"old visible text","with":"new text"},
+      {"op":"comment","on":"text to anchor on","body":"Is this still accurate?"}
+    ]
+  }'
+```
+
+**Content operations:**
+
+| op | body |
+|---|---|
+| `replace` | `find`, `with` (optional `occurrence` / `before` / `after`) |
+| `insert` | `after` or `before` + `markdown` (anchor: quote, `heading:Title`, `section:Title`, `"start"`, or `"end"`) |
+| `delete` | `find` |
+| `set_document` | `markdown` (whole-doc replace as a minimal diff; safe with live collaborators) |
+
+**Review operations:**
+
+| op | body |
+|---|---|
+| `comment` | `on`, `body` (optional `occurrence`) |
+| `reply` | `comment` (id), `body`, optional `resolve: true` |
+| `resolve` / `unresolve` | `comment` (id) |
+| `suggest` | `kind: "insert"\|"delete"\|"replace"`, `find`, `with?` (`with` required for insert/replace) |
+| `accept` / `reject` | `suggestion` (id) |
+| `modify_suggestion` | `suggestion` (id), `with` — replace the proposed text of a pending plain insert/replace suggestion |
+
+`suggest` also accepts typed structural forms (`command: "table.*"`, `"format.*"`, `"node.update"`, and atom `target: {node: "image"|"hr"|...}`); see `https://www.proofeditor.ai/agent-docs` before using them. A request holds at most 100 operations; `set_document` accepts at most 2 MiB of markdown.
+
+### Edit Strategy
+
+Prefer the narrowest op:
+
+1. Literal or scoped prose change → `replace` / `insert` / `delete`
+2. Visible track-changes desired → `suggest` (then `accept`/`reject` as needed)
+3. Whole-doc replacement → `set_document` only when the user asks for full replacement or the change cannot be expressed narrowly
+
+If a `find`/anchor matches more than once, the server rejects with `TARGET_AMBIGUOUS` and `error.candidates` — nothing is changed. Disambiguate with `occurrence` (`"first"`, `"last"`, or 0-based index) or `before`/`after`. Never assume silent first-match.
+
+Content ops in one request apply atomically; review ops then apply in order. If a review op fails after content committed, the response is `ok: false` with `partial: true` — re-read and retry only the failed op (same `Idempotency-Key` safely replays).
+
+**Errors** use `{ ok:false, error:{ code, message, retryable, opIndex?, target?, candidates?, current? } }`. Codes: `AUTH`, `NOT_FOUND`, `INVALID_REQUEST`, `TARGET_NOT_FOUND`, `TARGET_AMBIGUOUS`, `CONFLICT`, `TOO_LARGE`, `BUSY`, `PENDING`, `INTERNAL`.
+
+- `retryable: false` — fix the request; do not blind-retry
+- `retryable: true` with `error.current` — re-resolve targets against `current` and retry once
+- `TARGET_AMBIGUOUS` — add `occurrence` / `before` / `after` from `candidates`
+- `BUSY` — brief backoff and retry
+- Retryable `CONFLICT` on a structural suggestion — a connected editor is on an older suggestion reader; retry after it reconnects. Non-retryable `CONFLICT` — the op crosses frontmatter, raw HTML, or unknown content; use a whole-block op or leave it
+- `accept` that keeps failing with `SUGGESTION_OWNERSHIP_MISSING` after a fresh read — the suggestion is wedged; `reject` it (always allowed) and recreate instead of retrying `accept`
+- Settled `200` with `ok:true` — inspect returned `revision` / document; chain without an extra read when the body is complete
+- `202` / `PENDING` — write may have committed; re-read `v3/document` before chaining or reporting success
+
+After every successful edit: confirm `ok:true`, confirm the intended text/comment/suggestion, then report the Proof link with a short summary.
+
+### Presence
+
+```bash
+curl -sS -X POST "https://www.proofeditor.ai/api/agent/{slug}/presence" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <token>" \
+  -H "X-Agent-Id: ai:compound-engineering" \
+  -d '{"name":"Compound Engineering","status":"reading","summary":"Joining the doc"}'
+```
+
+Common statuses: `reading`, `thinking`, `acting`, `waiting`, `completed`, `error`.
+
+### Title
+
+```bash
+curl -sS -X PUT "https://www.proofeditor.ai/api/documents/{slug}/title" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <token>" \
+  -d '{"title":"Updated document title"}'
+```
+
+### Delete
+
+Only owner credentials can delete:
+
+```bash
+curl -sS -X DELETE "https://www.proofeditor.ai/api/documents/{slug}" \
+  -H "Authorization: Bearer <ownerSecret>"
+```
+
+Viewer, commenter, and editor `accessToken` values cannot delete. Success returns `shareState: "DELETED"`; later reads return deleted-document responses (`410` on many routes).
+
+**Lifecycle:** Do **not** auto-delete after every publish handoff — review docs must linger. Persist `ownerSecret` for the session. Delete when the user asks to remove/clean up, or when finishing an explicitly ephemeral scratch doc the user is done with.
+
+### Marks and privacy
+
+Emptying the markdown (including `set_document` to blank/minimal content) does **not** scrub comment marks. Quote and commentary fields can remain readable via `v3/document` to anyone with the share credential. Without owner delete authority, content wipe is not a privacy cleanup — delete the document with `ownerSecret` (while unclaimed) or ask the owner after claim.
+
+### When the loop breaks
+
+If a mutation keeps failing after a fresh read and one safe retry, call `POST https://www.proofeditor.ai/api/bridge/report_bug` with the failing request ID, slug, and raw response. The server enriches and files an issue. Ask before including the user's name/email.
+

package/skills/ce-proof/references/workflows.md

@@ -0,0 +1,124 @@
+# Proof workflows
+
+Required read before running one of these end to end: reviewing a shared doc, creating and sharing a new one, or pulling a doc down to a local file. Endpoint and operation detail lives in `api.md`.
+
+## Workflow: Review a Shared Document
+
+When given a Proof URL like `https://www.proofeditor.ai/d/abc123?token=xxx`:
+
+1. Extract the slug and token
+2. Bind presence with the CE identity defaults
+3. Read via `v3/document`
+4. Edit with `v3/edit` (narrow content ops; review ops for comments/suggestions)
+
+```bash
+TOKEN="xxx"
+SLUG="abc123"
+AGENT="ai:compound-engineering"
+
+curl -sS -X POST "https://www.proofeditor.ai/api/agent/$SLUG/presence" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "X-Agent-Id: $AGENT" \
+  -d '{"name":"Compound Engineering","status":"reading","summary":"Reviewing doc"}'
+
+DOC=$(curl -sS "https://www.proofeditor.ai/api/agent/$SLUG/v3/document" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "X-Agent-Id: $AGENT")
+REVISION=$(printf '%s' "$DOC" | jq -r '.revision // empty')
+
+# Comment on visible text
+curl -sS -X POST "https://www.proofeditor.ai/api/agent/$SLUG/v3/edit" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "X-Agent-Id: $AGENT" \
+  -H "Idempotency-Key: $(uuidgen)" \
+  -d "$(jq -n --argjson rev "${REVISION:-null}" '{
+    by:"ai:compound-engineering",
+    baseRevision: (if $rev == null then null else $rev end),
+    operations:[{op:"comment",on:"text to comment on",body:"Your comment here"}]
+  } | if .baseRevision == null then del(.baseRevision) else . end')"
+
+# Narrow content edit
+curl -sS -X POST "https://www.proofeditor.ai/api/agent/$SLUG/v3/edit" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "X-Agent-Id: $AGENT" \
+  -H "Idempotency-Key: $(uuidgen)" \
+  -d '{"by":"ai:compound-engineering","operations":[{"op":"replace","find":"old","with":"new"}]}'
+
+# Tracked suggestion
+curl -sS -X POST "https://www.proofeditor.ai/api/agent/$SLUG/v3/edit" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "X-Agent-Id: $AGENT" \
+  -H "Idempotency-Key: $(uuidgen)" \
+  -d '{"by":"ai:compound-engineering","operations":[{"op":"suggest","kind":"replace","find":"old","with":"new"}]}'
+```
+
+## Workflow: Create and Share a New Document
+
+**Publishing a local file (the primary case):** read the file and JSON-encode its full contents into the `markdown` field with `jq --rawfile` so newlines, quotes, and backticks are escaped correctly. Never hand-write the body or leave an inline placeholder — that publishes a placeholder doc instead of the source artifact.
+
+```bash
+SRC="path/to/plan.md"
+TITLE="Plan: Foo"
+
+RESPONSE=$(jq -n --arg title "$TITLE" --rawfile md "$SRC" '{title:$title, markdown:$md}' \
+  | curl -sS -X POST https://www.proofeditor.ai/share/markdown \
+    -H "Content-Type: application/json" -d @-)
+
+URL=$(echo "$RESPONSE" | jq -r '.tokenUrl')
+SLUG=$(echo "$RESPONSE" | jq -r '.slug')
+TOKEN=$(echo "$RESPONSE" | jq -r '.accessToken')
+OWNER_SECRET=$(echo "$RESPONSE" | jq -r '.ownerSecret')   # required for owner delete while unclaimed
+
+# Keep OWNER_SECRET in session memory only — never write it into the repo tree.
+
+curl -sS -X POST "https://www.proofeditor.ai/api/agent/$SLUG/presence" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "X-Agent-Id: ai:compound-engineering" \
+  -d '{"name":"Compound Engineering","status":"reading","summary":"Uploaded doc"}'
+
+echo "$URL"
+```
+
+After publish handoffs from planning workflows, surface the URL and return control — do not delete the doc automatically.
+
+When the user later asks to clean up an unclaimed doc you created:
+
+```bash
+curl -sS -X DELETE "https://www.proofeditor.ai/api/documents/$SLUG" \
+  -H "Authorization: Bearer $OWNER_SECRET"
+```
+
+## Workflow: Pull a Proof Doc to Local
+
+Sync the current Proof doc state to a local markdown file. Used for:
+
+- Ad-hoc snapshots of a Proof doc to disk
+- Pulling a shared Proof doc that the user (or others) edited back down to a local working copy
+- Refreshing a local working copy against the live Proof version
+
+Canonical read for this workflow: `GET /api/agent/$SLUG/v3/document`.
+
+```bash
+SLUG=<slug>
+TOKEN=<accessToken>
+LOCAL=<absolute-path>
+
+STATE_TMP=$(mktemp "${TMPDIR:-/tmp}/ce-proof-state.XXXXXX")
+curl -sS "https://www.proofeditor.ai/api/agent/$SLUG/v3/document" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "X-Agent-Id: ai:compound-engineering" > "$STATE_TMP"
+REVISION=$(jq -r '.revision // empty' "$STATE_TMP")
+
+TMP="${LOCAL}.proof-sync.$$"
+jq -jr '.markdown' "$STATE_TMP" > "$TMP" && mv "$TMP" "$LOCAL"
+rm "$STATE_TMP"
+```
+
+`jq -jr` streams markdown bytes without going through a shell variable, so trailing newlines survive. `mv` within the same filesystem is atomic.
+
+**Confirm before writing when the pull isn't directly asked for.** If a workflow ends up pulling as a side-effect of a different action, surface the impending write with a short confirm like "Sync Proof doc to `<localPath>`?" A silent overwrite is surprising.