@aopslabs/aops 0.3.31 → 0.3.32

package/aops-assets-release/skills/aops-bootstrapper-authoring/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: aops-bootstrapper-authoring
+version: 5
+description: "Use when an AI agent needs to create or update AOPS hosted bootstrapper prompts or skills, publish canonical versions, refresh .aops hosted mirrors, and install global Codex/Claude pointers without hand-editing mirrors."
+metadata:
+  short-description: "AOPS hosted bootstrapper prompt/skill authoring guide"
+  tags:
+    - aops
+    - bootstrapper
+    - group:bootstrapper
+    - prompt-authoring
+    - skill-authoring
+    - hosted-assets
+---
+
+# AOPS Bootstrapper Authoring
+
+This skill covers the hosted asset authoring flow for AOPS bootstrapper prompts and skills. It is a thin discipline guide; exact command flags come from `aops-cli prompt --help`, `aops-cli skill --help`, and nested help.
+
+## When to use this skill
+
+Use this skill when the operator asks to:
+
+1. Create a reusable bootstrapper prompt.
+2. Create a reusable bootstrapper skill.
+3. Update an existing hosted bootstrapper prompt or skill.
+4. Publish a hosted prompt/skill version under `slug:aops`.
+5. Refresh `.aops/hosted/**` mirrors after hosted publish.
+6. Install or refresh global Codex prompts/skills and Claude commands/skills pointers.
+
+Use `aops-cli-agentspace` for general memory and hosted asset surface orientation. Use `aops-cli-projectman` for PM tracking. Use `aops-cli-core` for sync and guard-flag conventions.
+
+## Ownership model
+
+1. Hosted prompt/skill canonical truth lives in AOPS server/DB and is changed through `aops-cli prompt ...` or `aops-cli skill ...`.
+2. `.aops/hosted/prompts/**` and `.aops/hosted/skills/**` are read-only mirrors refreshed by `aops-cli sync pull --apply --hosted-project-slug aops --json`.
+3. Global Codex/Claude files are pointers generated by `pnpm skills:claude-codex:all:sync`; do not hand-edit them as truth.
+4. Planning and handoff state belongs in Projectman and Agentspace memory, not in the hosted prompt body.
+
+## Required metadata
+
+For bootstrapper prompt shells, use these tags:
+
+```bash
+--tag aops --tag bootstrapper --tag group:bootstrapper --tag codex-prompt --tag claude-command
+```
+
+For bootstrapper skill shells, use these tags:
+
+```bash
+--tag aops --tag bootstrapper --tag group:bootstrapper
+```
+
+Recommended extra tags:
+
+- `prompt-authoring`
+- `skill-authoring`
+- `hosted-assets`
+- domain or workflow tags such as `memory`, `summary`, `collab`, `docman`
+
+Version `--meta @file.json` should include at least:
+
+```json
+{
+  "group": "bootstrapper",
+  "bootstrapper": true,
+  "codexPrompt": true,
+  "claudeCommand": true,
+  "tags": ["aops", "bootstrapper", "group:bootstrapper"]
+}
+```
+
+For hosted skills, omit `codexPrompt` / `claudeCommand` unless the skill also ships a prompt wrapper.
+
+## Prompt authoring workflow
+
+1. Confirm command shape:
+
+   ```bash
+   aops-cli prompt --help
+   aops-cli prompt list --help
+   aops-cli prompt create --help
+   aops-cli prompt version create --help
+   aops-cli prompt version publish --help
+   ```
+
+2. Search existing prompts:
+
+   ```bash
+   aops-cli prompt list --project-name aops --name "<name>" --json
+   ```
+
+3. Create shell when needed:
+
+   ```bash
+   aops-cli prompt create --project-name aops \
+     --name "<name>" \
+     --description "<description>" \
+     --status published \
+     --tag aops \
+     --tag bootstrapper \
+     --tag group:bootstrapper \
+     --tag codex-prompt \
+     --tag claude-command \
+     --apply --json
+   ```
+
+4. Create and publish a version:
+
+   ```bash
+   aops-cli prompt version create --project-name aops \
+     --prompt-id <prompt-id> \
+     --content @./prompt.md \
+     --meta @./meta.json \
+     --apply --json
+
+   aops-cli prompt version publish --project-name aops \
+     --id <prompt-version-id> \
+     --apply --json
+   ```
+
+## Skill authoring workflow
+
+1. Confirm command shape:
+
+   ```bash
+   aops-cli skill --help
+   aops-cli skill list --help
+   aops-cli skill create --help
+   aops-cli skill version create --help
+   aops-cli skill version publish --help
+   ```
+
+2. Search existing skills:
+
+   ```bash
+   aops-cli skill list --hosted-project-slug aops --name "<skill-name>" --json
+   ```
+
+3. Create shell when needed:
+
+   ```bash
+   aops-cli skill create --hosted-project-slug aops \
+     --name "<skill-name>" \
+     --description "<description>" \
+     --short-description "<short>" \
+     --tag aops \
+     --tag bootstrapper \
+     --tag group:bootstrapper \
+     --apply --json
+   ```
+
+4. Create and publish a version:
+
+   ```bash
+   aops-cli skill version create --hosted-project-slug aops \
+     --skill-id <skill-id> \
+     --content @./SKILL.md \
+     --entry-file SKILL.md \
+     --skill-standard aops-skill-v1 \
+     --meta @./meta.json \
+     --apply --json
+
+   aops-cli skill version publish --hosted-project-slug aops \
+     --id <skill-version-id> \
+     --apply --json
+   ```
+
+## Mirror and pointer workflow
+
+After publishing hosted assets:
+
+```bash
+aops-cli sync pull --apply --hosted-project-slug aops --json
+pnpm skills:claude-codex:all:sync
+pnpm skills:claude-codex:all:check
+```
+
+`skills:claude-codex:all:sync` / `all:check` cover skill pointers AND hosted
+prompt pointers (Codex prompts + Claude commands). The plain
+`pnpm skills:claude-codex:sync` / `check` variants pass `--skills-only` and
+silently skip prompt/command pointers — never rely on them after publishing a
+prompt. Raw equivalent of the full sync:
+
+```bash
+node ../../scripts/sync-aops-skills-to-codex.mjs --apply --json --repos .,../<sibling-repo>
+```
+
+Expected healthy pointer check:
+
+- `missing: 0`
+- `stale: 0`
+- new hosted prompts appear under `~/.codex/prompts` and `~/.claude/commands`
+- new hosted skills appear under `~/.codex/skills/<name>/SKILL.md` and `~/.claude/skills/<name>/SKILL.md`
+
+Claude Code command support can vary by build; treat `~/.claude/commands` as a best-effort user command/bootstrap pointer target.
+
+### Canonical home routing
+
+Global pointers written by `pnpm skills:claude-codex:all:sync` order their candidate
+list by **canonical home**: the repo whose own slug matches the hosted asset's
+`sourceProjectSlug` is primary; any other repo is fallback. Tie-breaker is the
+hosted `pulledAt` timestamp. This is on top of the always-first cwd-relative
+read step (Step 1 inside every pointer); the ordering only matters for
+repo-outside runtimes that fall through to the candidate list.
+
+- A bootstrapper published under `slug:aops` has its canonical home in the
+  **aops repo** (`<aops-repo>/.aops/hosted/`). Global pointer puts aops repo
+  first.
+- A bootstrapper published under `slug:eops` has its canonical home in the
+  **eops repo** (`<eops-repo>/.aops/hosted/`). Global pointer puts eops repo
+  first.
+
+Implication when picking the slug for a new bootstrapper:
+
+- Pick the slug that matches the asset's actual domain so it lives in the right
+  repo. A domain-eops bootstrapper (e.g. `eops-bom-grid-resume-bootstrap`)
+  published under `slug:aops` will still work via cwd-relative read inside the
+  aops repo, but the global pointer will route repo-outside runtimes to the
+  aops repo as canonical home and the asset will not appear in the eops repo's
+  mirror at all. That is a pointer-routing bug, not just a scope choice.
+- Cross-domain helper assets that genuinely apply to both repos (such as
+  generic collab/memory bootstrappers) stay under `slug:aops`, since aops is
+  the AOPS tooling home.
+
+Implementation reference: the repository-relative `scripts/sync-aops-skills-to-codex.mjs`
+(`dedupeSources` + `isCanonicalHome`).
+
+## Anti-patterns
+
+1. Hand-editing `.aops/hosted/**` as canonical truth.
+2. Hand-editing global Codex/Claude pointer files instead of running sync.
+3. Creating a prompt or skill without `bootstrapper` and `group:bootstrapper` tags.
+4. Copying full domain guides into a prompt body instead of pointing to skills/docs.
+5. Publishing a new hosted asset without a mirror pull and pointer check.
+6. Treating a failed server write as if a local mirror patch completed the change.
+7. Publishing a domain-specific bootstrapper under the wrong slug (e.g. an
+   `eops-*` bootstrapper under `slug:aops`). The slug choice also picks the
+   canonical-home repo for the global pointer; the wrong slug points
+   repo-outside runtimes at the wrong repo and hides the asset from the right
+   repo's mirror.
+8. Running the skills-only pointer sync (`pnpm skills:claude-codex:sync`) after
+   publishing a hosted prompt and assuming prompt/command pointers were
+   installed; prompt pointers require the full sync
+   (`pnpm skills:claude-codex:all:sync`).

package/aops-assets-release/skills/aops-cli-agentspace/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: aops-cli-agentspace
+description: "Use when an AI agent needs the AOPS CLI Agentspace playbook for token-efficient memory and resume, checkpoints and summaries, experience and playbooks, reusable hosted assets, agent profiles, activity, or structured discussions."
+metadata:
+  version: "28"
+  supersedes: "v27"
+  short-description: "AOPS Agentspace memory, knowledge, assets, and discuss guide"
+  tags:
+    - aops
+    - cli
+    - agentspace
+    - memory
+    - checkpoint
+    - experience
+    - playbook
+    - skill-discovery
+    - agent-profile
+    - discuss
+    - help-first
+---
+
+# AOPS CLI Agentspace
+
+Agentspace owns durable context and reusable knowledge: memory, experience,
+playbooks, prompts, resources, artifacts, skills, agent profiles, activity, and
+structured discussion topics.
+
+It does not own all work state. Projectman owns tasks/plans/issues/reviews,
+Docman owns versioned documents, ChatV3 owns coordination and wake traffic, and
+Git owns repository history.
+
+This is a thin skill. Exact flags live in the smallest `aops ... --help`
+surface, the current `Agentspace User Guide` owns normative workflow, and the
+running server schema owns raw hosted payloads.
+
+## Start Here
+
+1. Run `aops host health --json`.
+2. Read the smallest nested help for the intended family.
+3. Load a bounded brief/search result; do not preload every body.
+4. Use metadata-only `skill ask`/`skill search` before opening skill content.
+5. Preview guarded writes where supported, apply once, and read back the exact
+   record.
+6. Never hand-edit `.aops` mirrors as canonical state.
+
+```bash
+aops host health --json
+aops mem brief --subject project --q "<current work>" --limit 5 --json
+aops skill ask --q "<what the agent needs>" --limit 3 --json
+```
+
+## Canonical Sources
+
+1. Hosted `Agentspace User Guide` in project `slug:aops`, group
+   `domain-guides`, document `agentspace-user-guide`, current v20
+   `9c805e63-3372-4a8c-a3dc-adfa5d4b8577`.
+2. Targeted read-only mirror:
+   `.aops/docman/domain-guides/agentspace-user-guide.md`.
+3. Public release source:
+   `assets/docs/user-guides/agentspace-user-guide.md`.
+4. Exact flags: `aops <family> <command> --help`.
+5. Live discovery:
+   `aops agent tools --domain agentspace --q "<capability>" --limit 20 --summary --json`.
+6. Raw input contract:
+   `aops agent schema --tool <agentspace-tool-id> --summary --json`.
+
+When freshness matters, pull only the intended guide and search its mirror:
+
+```bash
+aops doc mirror pull --project-slug aops \
+  --document-slug agentspace-user-guide --apply --json
+aops doc scope search --project-slug aops \
+  --q "Agentspace <topic>" --local --json
+aops view doc-page agentspace-user-guide#<section-slug> --max-bytes 6000
+```
+
+## Retrieval Ladder
+
+Use broad-to-specific reads:
+
+```bash
+aops mem brief --subject <kind> --q "<focus>" --limit 5 --json
+aops mem synopsis --subject <kind> --q "<focus>" --limit 5 --json
+aops mem search --subject <kind> --q "<terms>" --limit 8 --json
+aops mem resume --subject <kind> --q "<focus>" --limit 8 --json
+aops mem get --id <memory-id> --json
+```
+
+Memory is an evidence pack, not a transcript. Record purpose, canonical refs,
+concrete outcome, validation/review evidence, open risk, and next action. Never
+store secrets, raw logs, full documents, or chat transcripts.
+
+## Checkpoint, Summary, and Retention
+
+Use a checkpoint after a meaningful milestone, decision, blocker, or handoff:
+
+```bash
+aops mem checkpoint --project-slug <slug> --as milestone \
+  --content '@checkpoint.md' --task-id <task-id> --sprint-id <sprint-id> \
+  --source-ref <ref> --validation-state "<evidence>" \
+  --next-action "<next safe action>" --apply --json
+```
+
+Use `aops mem summary` at session end or an explicit summary point. Ordinary
+continuation uses `mem checkpoint`. Durable closeout needs explicit closeout,
+durable, and confirmation flags; inspect help first.
+
+`mem compact` and `mem prune` are review-first retention tools. Run preview,
+inspect the selected source set, and do not write summaries, mark source, prune,
+or delete without explicit operator intent. Destructive pruning requires
+`--apply --confirm`.
+
+## Experience, Playbooks, and Hosted Assets
+
+Capture experience only when it is reusable and evidence-backed:
+
+```bash
+aops exp search --project-slug <slug> --q "<need>" --limit 5 --json
+aops exp capture --project-slug <slug> --type problem-solution \
+  --title "<lesson>" --problem "<problem>" --solution "<verified solution>" \
+  --pm-ref <projectman-ref> --source-ref <source-ref> --preview --json
+aops playbook list --project-slug <slug> --area <area> \
+  --review-state accepted --limit 5 --json
+```
+
+For prompts, resources, artifacts, and skills, start with summary inventory.
+Prompt and skill bodies may be large:
+
+```bash
+aops prompt version list --summary --json
+aops skill version list --summary --json
+aops skill search --q "<capability>" --limit 5 --json
+aops skill current --id <skill-id> --summary --json
+aops resource list --summary --limit 10 --json
+aops artifact ref list --summary --json
+```
+
+Read a selected `SKILL.md` completely before acting. Hosted prompt/skill
+mirrors are read-only; use create/update/version/publish commands and verify the
+new current version through the server.
+
+## Profiles and Activity
+
+Agent profiles compose role intent and prompt/skill/resource references. They
+do not grant runtime permissions or operator approval. Activity is a read-first
+ledger; use `activity list/get --summary` before loading raw payloads.
+
+## Structured Discussion Boundary
+
+Use `aops discuss` for material decisions needing independent stances and a
+durable conclusion. Use `aops-cli-discuss` for the full ritual.
+
+Important current semantics:
+
+- `start --max-turns` is unsupported and fails;
+- `--objective` is folded into the hosted question;
+- `turn --to` supports only `operator`;
+- `turn --reply-to` takes an integer turn sequence;
+- waits exit `0` when the agent may write, `20` for an operator block, `21` for
+  ready/terminal state, and `22` on timeout.
+
+Discuss does not wake ChatV3 listeners. Use `aops-cli-chat` and `aops chat` for
+coordination. Use `aops-cli-projectman` for the resulting plan/review truth.
+
+## Schema Fallback
+
+Do not guess hosted tool ids, payloads, or fixed tool counts:
+
+```bash
+aops agent tools --domain agentspace --q "<capability>" \
+  --limit 20 --summary --json
+aops agent schema --tool <agentspace-tool-id> --summary --json
+aops agent invoke --tool <agentspace-tool-id> \
+  --input '@payload.json' --preview --json
+```
+
+Use raw invoke only when sugar is insufficient and the exact schema is known.
+
+## Done When
+
+- canonical records were read back after mutation;
+- memory contains bounded evidence rather than duplicated truth;
+- relevant help/guide/schema sources agree;
+- destructive retention actions, if any, had explicit operator authority;
+- any material decision, plan, review, document, or wake traffic is stored in
+  its actual owner rather than Agentspace by convenience.

package/aops-assets-release/skills/aops-cli-board-lifecycle/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: aops-cli-board-lifecycle
+version: 6
+description: "Deprecation pointer skill: aops-cli-board-lifecycle is folded into aops-cli-projectman. Routes agents to projectman v5+ for board lifecycle, kanban-task, sprint, microtask, issue, feedback, and handoff policy. Kept for at least one release cycle for compatibility."
+metadata:
+  supersedes: "v5"
+  short-description: "Deprecated: board lifecycle folded into aops-cli-projectman"
+  tags:
+    - cli
+    - projectman
+    - board-lifecycle
+    - deprecated
+    - compatibility
+---
+
+# AOPS CLI Board Lifecycle — v4 Deprecation Pointer
+
+This skill is intentionally folded into **`aops-cli-projectman`**. Board lifecycle policy, kickoff/resume/closeout cadence, sprint linking, microtask plan patching, and memory write rhythm now live as integral sections of the Projectman skill and **`domains/projectman/USER_GUIDE.md`**.
+
+This pointer is kept for compatibility (existing prompts, AGENTS references, runtime catalogs). New task prompts should prefer `aops-cli-projectman` directly.
+
+## Where to go now
+
+| Need | Skill / source |
+|------|---------------|
+| Board kickoff/resume/closeout, kanban task CRUD, sprint phases/microtasks, issue/feedback, handoff | **`aops-cli-projectman`** |
+| Deep mechanics, full anti-pattern list, troubleshooting, workflow scenarios | **`domains/projectman/USER_GUIDE.md`** (Anti-patterns, Troubleshooting, Common workflow scenarios sections) |
+| CLI guard flags, sync, hosted mirror, raw invoke | `aops-cli-core` |
+| discuss / decision / consensus | `aops-cli-discuss` |
+| chat / coordination / wake | `aops-cli-chat` |
+| Document graph CRUD/search/publish | `aops-cli-docman` |
+| Memory + experience + agent-profile + assets | `aops-cli-agentspace` |
+
+## Canonical entry points (quick reference)
+
+```bash
+aops-cli pm board kickoff --board <slug> --title "..." --goal "..." --apply --json
+aops-cli pm board resume --board <slug> --json
+aops-cli pm board closeout --board <slug> --content "..." --apply --json
+aops-cli pm sprint update-plan --id <sprint-id> --phases-json @./plan.json --apply --json
+aops-cli pm sprint set-status --id <sprint-id> --status completed --apply --json
+```
+
+## Deep reading
+
+```bash
+# broad search across the project's guides (local mirror, no id needed):
+aops-cli doc scope search --project-slug aops --q "board lifecycle" --local --json
+aops-cli doc scope search --project-slug aops --q "closeout" --local --json
+# exact search within a known guide version:
+aops-cli doc search --document-version-id <docver-id> --q "board lifecycle" --local --json
+# section tree of a known guide version (hosted-only — no local fallback):
+aops-cli doc outline get --document-version-id <docver-id> --json
+```
+
+There is no `aops-cli docman … --slug` command — use the ladder; reference sections by document title + section name + keywords, not bare numbers.
+
+For flag-level detail: `aops-cli pm board --help`, `aops-cli pm sprint --help`, etc.
+
+## Compatibility note
+
+`aops-cli-board-lifecycle` is **not hard-sunset**. It remains a stable index. Future maintenance happens in `aops-cli-projectman` and `domains/projectman/USER_GUIDE.md`; do not expand this file back into a full board lifecycle guide.
+
+If `--help` and this skill disagree, `--help` wins (canonical command surface). If the user guide and this skill disagree, the user guide wins.

package/aops-assets-release/skills/aops-cli-chat/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: aops-cli-chat
+version: 10
+description: "Use when an AI agent needs the AOPS ChatV3 CLI playbook: encrypted channel/session handling, rooms, members, presence, bindings, cursor-safe read/listen loops, destructive guards, live tool discovery, or the optional experimental wake watcher."
+metadata:
+  supersedes: "v9"
+  short-description: "AOPS ChatV3 encrypted coordination and cursor-safety guide"
+  tags:
+    - aops
+    - cli
+    - chatv3
+    - chat
+    - encrypted
+    - channels
+    - rooms
+    - sessions
+    - cursors
+    - bindings
+    - help-first
+---
+
+# AOPS CLI ChatV3
+
+`aops chat` is the canonical ChatV3 command tree for encrypted channels,
+rooms, agent-owned local sessions, coordination messages, cursors, presence,
+and loose references. `aops chatv3` is a compatibility alias for existing
+automation; prefer `aops chat` in new work.
+
+ChatV3 is FLOW, not durable truth. Discuss owns design decisions, Projectman
+owns plans/issues/reviews, Agentspace owns durable memory, and Docman owns
+guides/ADRs/specifications.
+
+This public operational skill does not grant access to proprietary ChatV3
+source code or restricted packages. The source repository's `LICENSE` and
+`NOTICE` remain controlling.
+
+## Start Here
+
+1. Run `aops host health --json`.
+2. Read `aops chat --help` and the smallest nested `--help` command.
+3. List your own saved sessions; never guess or borrow another agent's session.
+4. Read from the saved cursor before listening.
+5. Treat `listen` exit `22` as a normal no-message timeout.
+6. Escalate beyond sugar only through live tool discovery and schema reads.
+
+```bash
+aops host health --json
+aops chat --help
+aops chat session list --json
+aops agent tools --domain chatv3 --summary --json
+```
+
+The installed launcher may be `aops`; the package launcher is `aops-cli`.
+
+## Canonical Sources
+
+1. Hosted `ChatV3 User Guide` in `slug:aops`, group `domain-guides`, document
+   slug `chatv3-user-guide`.
+2. Targeted mirror:
+   `.aops/docman/domain-guides/chatv3-user-guide.md` (read-only cache).
+3. Exact flags: `aops chat <command> --help`.
+4. Live capability discovery:
+   `aops agent tools --domain chatv3 --summary --json`.
+5. Raw input contract:
+   `aops agent schema --tool <chatv3-tool-id> --summary --json`.
+
+Help wins for sugar flags. The running schema wins for raw hosted payloads.
+The current published user guide wins for normative workflow.
+
+When guide freshness matters, pull only the intended hosted document:
+
+```bash
+aops doc mirror pull --project-slug aops \
+  --document-slug chatv3-user-guide --apply --json
+aops doc scope search --project-slug aops --q "ChatV3 cursor" --local --json
+```
+
+## Fast Command Map
+
+| Need | Primary surface |
+| --- | --- |
+| Create or join | `chat channel create`, `chat join` |
+| List channels/sessions | `chat channels`, `chat session list`, `chat session get` |
+| Rooms | `chat room list`, `create`, `join`, `leave`, `members` |
+| Channel members | `chat member list`, `remove`, `restore` |
+| Messages | `chat send`, `chat read`, `chat listen` |
+| Presence | `chat presence set`, `chat presence list` |
+| References | `chat binding add`, `list`, `remove` |
+| Orientation | `chat room brief`, `chat room summary` |
+| Leave or forget local state | `chat leave`, `chat session forget` |
+| Guarded cleanup | `chat channel delete`, `chat channel purge-before` |
+| Unsupported sugar | `agent tools`, `agent schema`, then `agent invoke` |
+
+## Secret and Session Rules
+
+1. A `chv3://join/...` invite contains secrets. Never put it in source, issues,
+   PM records, screenshots, logs, shell history, or chat messages.
+2. Session stores contain encrypted member credentials and mode-specific key
+   material. Never print, copy, or commit them.
+3. Use only the session created for this agent/task. If `session list` is empty,
+   stop and request a fresh securely transferred invite.
+4. Use `--session-owner` only when ownership is explicit. Use `--store-path`
+   for isolated tests, not to bypass owner separation.
+5. `--force` replaces local session state; never use it merely to silence an
+   ownership or identity conflict.
+
+## Cursor-Safe Foreground Loop
+
+```bash
+aops chat read --session <session-id> --room <room> \
+  --after-seq <saved-cursor> --json
+
+aops chat listen --session <session-id> --room <room> \
+  --after-seq <latest-seq> --timeout-sec 55 --json
+
+# After processing the batch, write receipts from the previous cursor.
+aops chat read --session <session-id> --room <room> \
+  --after-seq <previous-saved-cursor> --limit <batch-size> \
+  --mark-delivered --mark-read --json
+```
+
+- `read` and `listen` return `messages`, `messageCount`, `latestSeq`, and
+  `caughtUp`; `messages: []` is valid.
+- Exit `0` means messages arrived. Exit `22` means a normal timeout.
+- Detect a gap when the first returned `seq` is greater than the saved cursor
+  plus one. Keep the cursor unchanged and read again from the last contiguous
+  processed sequence.
+- `latestSeq` is the maximum returned sequence or the supplied cursor, not the
+  room high-water mark. With a bounded page, `caughtUp: false` only means the
+  page was non-empty; continue until a read returns no messages.
+- Mark delivered/read only after processing the returned messages.
+- Keep listening bounded and foreground unless the operator explicitly asks
+  for persistent monitoring.
+
+## Coordination Boundary
+
+Send short outcomes and canonical ids. Prefer a binding over burying an
+important reference in prose:
+
+```bash
+aops chat binding add --session <session-id> --room <room> \
+  --binding-type projectman.review-request --ref-id <rr-id> \
+  --title "Review request" --json
+```
+
+A room ACK is not a review approval. Use Projectman RR/status/result ids as
+review truth. Use Discuss for final design stances. Compose durable facts from
+`room summary`; do not copy source messages verbatim into memory.
+
+## Live Tool Discovery
+
+The public CLI is intentionally smaller than the hosted ChatV3 domain. Do not
+invent tool ids or payloads:
+
+```bash
+aops agent tools --domain chatv3 --summary --json
+aops agent schema --tool <chatv3-tool-id> --summary --json
+aops agent invoke --tool <chatv3-tool-id> \
+  --input '@./payload.json' --json
+```
+
+Use raw invoke only after the exact schema is known and sugar is insufficient.
+
+## Destructive and Privileged Operations
+
+- `channel delete` is irreversible and requires the exact `--confirm-slug`.
+- `channel purge-before` is preview-only unless `--confirm` is supplied.
+- Member remove/restore changes access; verify channel-versus-room scope first.
+- Never run destructive cleanup without explicit operator authorization.
+
+```bash
+aops chat channel purge-before --before <ISO-timestamp> --json
+# Apply only after separate approval:
+aops chat channel purge-before --before <ISO-timestamp> --confirm --json
+```
+
+## Experimental Wake Watcher
+
+`aops chat wake-watch` is experimental, optional, foreground-only guidance.
+Do not start it as part of a normal read/listen loop. It needs an exact target
+Codex session, explicit operator approval, a complete ignore set, and isolated
+watcher identity. Read its live `--help` before any use.
+
+## Troubleshooting
+
+- No saved session: stop; obtain a new invite securely.
+- Cursor gap: read the missing contiguous sequence; do not force cursors.
+- Join/decrypt failure: verify invite host, session owner/store, encryption
+  mode, channel state, nested help, then live schema.
+- Missing capability: use `agent tools` and `agent schema`; do not guess.
+- Timeout exit `22`: no new messages; this is not a persistent failure.
+- Mirror disagreement: hosted Docman is canonical; refresh the targeted mirror.
+
+Never log member tokens, invite fragments, wrap secrets, epoch keys, or server
+keyring material while diagnosing.
+
+## Done When
+
+- the exact intended session and room are used;
+- cursor reads are contiguous and processed messages are acknowledged;
+- durable ids/outcomes are recorded in their owning system;
+- no secret or session-store material is exposed;
+- no watcher or destructive operation ran without explicit authorization;
+- guide or schema citations support any nontrivial raw invocation.