@xulthekl/team-flow 0.24.0 → 0.26.0

package/skills/ce-ideate/references/phase0-scope.md

@@ -0,0 +1,134 @@
+# Phase 0: Resume and Scope
+
+Detailed routing logic for Phase 0 sub-phases. When subject, mode, and format are already clear from the prompt, resolve in one pass and move on.
+
+## 0.0 Resolve Output Mode
+
+Determine `OUTPUT_FORMAT` for the ideation artifact. Output mode is **exclusive** — HTML (`.html`) OR markdown (`.md`), never both. Unlike `ce-plan` and `ce-brainstorm` (which default to `md`), ce-ideate defaults to **`html`** — ideation artifacts are read mainly by humans weighing candidate directions.
+
+Precedence: in-prompt request > user-stated preference > config > default (`html`), with a hard pipeline-mode override.
+
+**Read config.** Resolve `<repo-root>` via `git rev-parse --show-toplevel`. Then read `<repo-root>/.compound-engineering/config.local.yaml`. If unavailable, fall through to defaults.
+
+Resolution steps:
+
+1. **In-prompt request.** Match `output:` shorthand or plain language to `md`/`html` case-insensitively. Distinguish doc-format request from subject matter: "ideate on an HTML export feature" is the work, not a format request.
+   - `output:` alone (no value) → no-op, fall through to step 2.
+   - `output:<unknown>` (e.g., `output:pdf`) → drop the token, fall through, remember to emit a one-line note after final resolution.
+
+2. **User-stated preference.** Honor a preference established earlier in session/memory/instructions. A remembered preference overrides config. Do not search instruction files.
+
+3. **Config.** If config has an **active (non-commented)** `ideate_output:` key matching `md` or `html`, use it. Critical: lines starting with `#` are YAML comments and must be ignored.
+
+4. **Default.** `OUTPUT_FORMAT=html`.
+
+5. **Pipeline override.** Force `OUTPUT_FORMAT=md` in any pipeline or `disable-model-invocation` context.
+
+**Token-parsing convention:** only literal-prefix flag tokens (`output:`, `mode:`) are consumed and stripped. Other `<word>:<word>` tokens pass through verbatim.
+
+**Defer loading the format-rendering reference.** The deliverable is written at Phase 4, so `references/ideation-sections.md` and rendering references are only needed then.
+
+The `output:` preference does NOT auto-propagate to `ce-brainstorm` on handoff.
+
+## 0.1 Check for Recent Ideation Work
+
+Look in `docs/ideation/` for ideation documents (`*.md` or `*.html`) created within the last 30 days.
+
+Treat a prior ideation doc as relevant when:
+- the topic matches the requested focus
+- the path or subsystem overlaps the requested focus
+- the request is open-ended and there is an obvious recent open ideation doc
+- the issue-grounded status matches (don't mix issue-tracker and non-issue ideation)
+
+If a relevant doc exists, ask whether to continue from it or start fresh. If continuing: read the document, summarize what has been explored, preserve previous ideas and rejection summary, update the existing file.
+
+**Write the update back in the existing file's format**, overriding the Phase 0.0 baseline. Format precedence on resume: explicit `output:` arg > resumed file's extension > config > default (`html`); pipeline runs still force `md`.
+
+## 0.2 Subject-Identification Gate
+
+Check whether the subject of ideation is identifiable. If the subject is ambiguous enough that reasonable sub-agents would diverge, output will be scattered.
+
+**Questioning principles (apply in this phase and in 0.4):**
+- Questions exist only to supply what sub-agents need: an identifiable subject (this phase) and enough context for the agent to say something specific (0.4).
+- Never ask about solution direction, constraints, audience, tone, success criteria.
+- Always keep "Surprise me" as a real option.
+- Stop as soon as the subject is identifiable or delegated to "Surprise me." More than 3 total questions is a smell — consider suggesting `ce-brainstorm`.
+
+**Detection — issue-tracker intent (repo mode only).** Trigger only when the prompt uses phrases like `github issues`, `open issues`, `issue patterns`, `what users are reporting`, `bug reports`. Do NOT trigger on `bug in auth`, `fix the login issue` — these are focus hints.
+
+**Detection — subject identifiability.** Test: would a reader, seeing only this prompt, know what subject the agent should ideate on? Vagueness is about what the words *refer to*, not phrase length: `browser sniff` names a feature (identifiable); `quick wins` names only a quality (vague).
+
+**Being inside a repo does not settle vagueness.** `improvements` in any repo is still scattered. The repo provides material for grounding *after* a subject is settled, not the subject itself.
+
+**Genuine ambiguity (repo mode).** When real doubt remains, Glob for the phrase in filenames, or Grep for it in README/docs. Any repo footprint → identifiable; none and still vague → ask.
+
+**The scope question.** Ask via blocking question tool:
+- Stem: "What should the agent ideate about?"
+- Options: "Specify a subject" / "Surprise me" / "Cancel"
+
+Routing:
+- **Specify** → accept the user's follow-up as the subject. Re-apply identifiability check once.
+- **Surprise me** → mark as **surprise-me mode**. Agent discovers subjects from Phase 1 material. CWD inside git repo → route to repo-grounded; otherwise elsewhere-software (require Phase 0.4 to collect substance). Skip Decision 1/2 in Phase 0.3.
+- **Cancel** → exit cleanly.
+
+## 0.3 Mode Classification
+
+Classify the **subject of ideation** (settled in 0.2) into one of three modes:
+
+**Surprise-me short-circuit.** Skip the two-decision classification. Use deterministic rule from 0.2: repo-grounded when CWD is inside git repo, elsewhere-software otherwise. State chosen mode in one sentence and proceed.
+
+For specified subjects, make two sequential binary decisions:
+
+**Decision 1 — repo-grounded vs elsewhere.** Weigh prompt content first, topic-repo coherence second, CWD repo presence as supporting evidence only.
+
+- Positive signals for **repo-grounded**: prompt references repo files, code, architecture, modules, tests, workflows. Issue-tracker intent is always repo-grounded.
+- Negative signals (push toward **elsewhere**): prompt names things absent from the repo (pricing, naming, narrative, business model, personal decisions, brand).
+
+**Decision 2 (only fires if Decision 1 = elsewhere) — software vs non-software.** Classify by whether the *subject* of ideation is a software artifact or system. If the topic concerns a product, app, SaaS, web/mobile UI, feature, it is **elsewhere-software** — even when ideas are about copy, UX, CRO, pricing for that software product. **Elsewhere-non-software** is reserved for topics with no software surface: company naming, narrative writing, personal decisions, non-digital business strategy, physical products.
+
+State the inferred mode in one sentence using plain language. Never print internal taxonomy labels.
+
+**Active confirmation on mode ambiguity.** Only fire when classification is genuinely ambiguous. Ask one confirmation question via blocking tool with two self-contained labels.
+
+**Routing rule (non-software mode).** Run Phase 1 Elsewhere-mode grounding. Load `references/universal-ideation.md` and follow it in place of Phase 2 and Phase 5 menu. Do not run repo-specific codebase scan.
+
+## 0.4 Context-Substance Gate (Elsewhere Modes Only)
+
+Skip in repo mode. In elsewhere modes, Phase 1 agents depend on user-supplied context. A bare prompt leaves agents with nothing to synthesize.
+
+Apply discrimination test: would swapping one piece of the user's stated context for a contrasting alternative materially change which ideas survive? If yes, context is load-bearing — proceed. If no, ask 1-3 narrowly chosen questions focused on **supplying substance**:
+- A URL or file to read
+- A brief description of the current state
+- A paste of an existing draft or brief
+
+**Surprise-me exception.** In surprise-me + elsewhere-software, at least one piece of substance is required. Dismissive responses are not acceptable — tell them the run needs material and end cleanly.
+
+When user provides rich context up front, confirm understanding in one line and skip.
+
+If this step materially changes the topic, re-run 0.2 and 0.3 before dispatching Phase 1.
+
+## 0.5 Interpret Focus and Volume
+
+Infer two things from the argument:
+- **Focus context** — concept, path, constraint, or open-ended
+- **Volume override** — any hint that changes candidate or survivor counts
+
+Default volume: each ideation frame yields ~6-8 ideas (~36-48 raw across six frames; ~25-30 survivors after dedupe); keep top 5-7 survivors.
+
+Honor clear overrides: `top 3`, `100 ideas`, `raise the bar`.
+
+**Depth override.** `go deep` opts into maximum depth: every ideation agent moves to ceiling tier, Phase 2 verification read budget doubles, Phase 3 adds a second critic.
+
+**Tactical scope detection.** Parse focus hint for: `polish`, `typo`, `quick wins`, `small improvements`, `cleanup`. When present, lower Phase 2 ambition floor.
+
+## 0.6 Cost Transparency Notice
+
+Before dispatching Phase 1, surface the agent count and cost shape for the inferred mode in one short line.
+
+Compute the count: 1 grounding-context agent + 1 learnings (skip in elsewhere-non-software) + 1 web researcher + evidence scouts (repo mode only, max 5) + user-research distillers + ideation fleet (5 default: 3 generation + 2 ceiling; 6 all-ceiling in surprise-me or `go deep`; 4 in issue-tracker mode) + 1 basis verifier.
+
+Examples (defaults, no skips):
+- **Repo mode, specified subject:** "Will dispatch ~13 agents, most on cheap tiers."
+- **Repo mode, surprise-me:** "Will dispatch ~10 agents (surprise-me mode: deeper exploration per agent)."
+- **Elsewhere-software:** "Will dispatch ~9 agents."
+- **Elsewhere-non-software:** "Will dispatch ~8 agents."

package/skills/ce-ideate/references/topic-surface.md

@@ -0,0 +1,37 @@
+# Phase 1.5: Topic-Surface Decomposition
+
+Before dispatching frame agents in Phase 2, decompose the topic into 3-5 orthogonal **axes** that name *what aspects of the subject to think about*. Phase 2 frames determine *how to think* (the lens); axes determine *what to think on* (the surface). Without an explicit axis list, parallel frames tend to converge on whichever interpretation of the subject is most salient.
+
+The axis analysis itself is a single orchestrator-side pass against the grounding summary already in context — no additional grounding read, no user-facing question.
+
+## Axis Criteria
+
+- **3-5 axes.** Fewer than 3 means the topic is atomic — skip. More than 5 fragments dispatch and produces thin coverage.
+- **Orthogonal.** A single idea should naturally fall on one axis, not span multiple. Merge axes that overlap heavily.
+- **Derived from grounding.** The grounding summary contains the substance; do not pick axes from a generic template.
+- **At the same level.** Don't mix "the entire pricing page" with "the $9.99 tier copy".
+- **Named in the topic's language.** Use words a reader of the topic would recognize, not meta-language about ideation.
+
+## Worked Examples (illustrative, not a template)
+
+| Topic | Axes |
+|---|---|
+| Social sharing of convergence pages | Send mechanics; discovery (receive side); arrival/dwell experience; compounding over time; actor types |
+| Improve authentication system | Sign-in flow; session management; account recovery; permissions; identity providers |
+| Dark mode for our app | Visual surfaces; toggle UX; system-preference detection; asset variants; edge cases |
+
+## Skip Condition
+
+Some subjects are atomic and resist meaningful decomposition — a single string output (a name, a tagline), a narrowly-scoped tactical fix, or a topic where candidate axes *are* the deliverable. When 3+ orthogonal axes cannot be generated, skip decomposition. Note `Decomposition skipped — atomic subject` in the grounding summary.
+
+**Surprise-me skip.** In surprise-me mode there is no settled subject to decompose. Skip and note `Decomposition skipped — surprise-me mode`.
+
+## Evidence Scouts (repo mode, when axes exist)
+
+Decomposition names what to look at; scouts gather what is actually there. Dispatch one extraction-tier sub-agent per axis (max 5) in parallel. Prompt:
+
+> Gather evidence about **{axis}** in this repo, scoped to {focus/subject}. Search first with native file-search and content-search tools, then read targeted sections — budget ~20 reads. Write an **evidence dossier** to `{scratch-dir}/evidence-{axis-slug}.md`: at most 150 lines of verbatim quotes and short code snippets, each with a `file:line` pointer, covering pain points, workarounds, TODO/FIXME markers, surprising patterns, and leverage points on this axis. Extraction only — quote what the repo says; do not interpret or propose ideas. Return only a gist: 3-5 lines summarizing what the dossier holds, plus its absolute path and entry count.
+
+Append the returned gists (with dossier paths) to the consolidated grounding summary under `Evidence: <axis>`. The dossier files are the evidence layer Phase 2 agents read and cite from. Skip scouts when decomposition was skipped, in surprise-me mode, and in elsewhere modes.
+
+Append the axis list (or skip-reason) to the consolidated grounding summary under `Topic axes`. Phase 2 reads this section to thread axes into sub-agent prompts; Phase 3 uses it for axis-spread scoring; Phase 4 includes it under Grounding Context.

package/skills/ce-proof/SKILL.md

@@ -23,15 +23,12 @@ Set the display name once per doc session by posting to presence with the `X-Age
 
 ## Publish Mode
 
-The primary use is one-way publishing: take an existing local markdown file (a brainstorm, a unified plan, a learning, a draft), read its full contents and post them as the new doc's body (see "Workflow: Create and Share a New Document" for the source-file recipe — never publish placeholder content), and hand the user a shareable URL. The local file stays canonical — publishing does not sync anything back to disk. The user can open the link to read, comment, and share with others; the agent can also participate via the edit APIs below when given the URL. Two entry points, identical mechanics (see "Workflow: Create and Share a New Document"):
+The primary use is one-way publishing: take an existing local markdown file (a brainstorm, a unified plan, a learning, a draft), read its full contents and post them as the new doc's body, and hand the user a shareable URL. The local file stays canonical — publishing does not sync anything back to disk. Two entry points:
 
-- **Direct user request** — a bare user phrase naming a local markdown file and asking to share it via Proof: "share this to proof", "publish this to proof", "open this in proof editor so I can review", "get me a proof link for this doc". The file is whichever markdown the user just created, edited, or referenced; if ambiguous, ask which file. This is a first-class entry point — do not require an upstream caller.
+- **Direct user request** — a bare user phrase naming a local markdown file and asking to share it via Proof: "share this to proof", "publish this to proof", "open this in proof editor so I can review", "get me a proof link for this doc". The file is whichever markdown the user just created, edited, or referenced; if ambiguous, ask which file.
 - **Upstream skill handoff** — `ce-brainstorm`, `ce-ideate`, or `ce-plan` finishes a draft and hands it off to publish for human review, passing the file path and title explicitly.
 
-Only publish markdown. If the source is an HTML unified plan, do not upload it
-to Proof; return the local browser/open path instead. When publishing a unified
-plan, label the title by readiness when available, e.g. `Plan: <title>
-(requirements-only)` or `Plan: <title> (implementation-ready)`.
+Only publish markdown. If the source is an HTML unified plan, do not upload it to Proof; return the local browser/open path instead. When publishing a unified plan, label the title by readiness when available, e.g. `Plan: <title> (requirements-only)` or `Plan: <title> (implementation-ready)`.
 
 Do not silently replace repo-tracked project docs with Proof links. Do not put secrets, credentials, API keys, private tokens, or sensitive personal data in Proof unless the user explicitly approves.
 
@@ -63,94 +60,9 @@ 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
+For detailed curl examples for all operations (create, read, edit, presence, title, delete), read `references/api-recipes.md`.
 
-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.
-
-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) |
-
-### Edit Strategy
+## Edit Strategy
 
 Prefer the narrowest op:
 
@@ -158,183 +70,13 @@ Prefer the narrowest op:
 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
-- 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
+If a `find`/anchor matches more than once, the server rejects with `TARGET_AMBIGUOUS` — disambiguate with `occurrence` / `before` / `after`. Never assume silent first-match.
 
 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.
-
-## 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="docs/plans/2026-05-04-001-feat-foo-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:
+## Workflows
 
-- 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)
-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.
+For complete workflow recipes (review, create, pull to local), read `references/workflows.md`.
 
 ## Safety
 

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

@@ -0,0 +1,145 @@
+# Proof Web API Recipes
+
+Detailed curl examples and error handling for Proof's hosted web API at `https://www.proofeditor.ai`.
+
+## 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.
+
+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) |
+
+### Error handling
+
+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
+- 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.