@cohortapp/agent-sdk 2.3.0

package/plugins/maestro-skills/skills/brand-steward.md

@@ -0,0 +1,121 @@
+---
+name: brand-steward
+description: Work the org's Design section — read the brand foundation and voice, rewrite copy in that voice, render and export templates and the brand kit, regenerate stale imagery within a budget, and propose reviewable foundation changes. Use before writing anything the workspace publishes, to produce a branded asset, or when imagery/templates have gone stale.
+---
+
+# Brand Steward
+
+The product section is called **Design**; the wire family is `branding.*`. That
+split is deliberate — do not "fix" it.
+
+The workspace's brand is a versioned document. Reads are cheap. The producers
+(render, rewrite, export, image generation) cost real money and return what they
+spent. Foundation mutations are always human-gated: your lane is
+`design_propose_change`, which stages a reviewable diff and writes nothing.
+
+All of it is `executeOrgTool`; frames are fail-open.
+
+## Read before you write
+
+```bash
+node --input-type=module -e '
+import { executeOrgTool } from "./lib/org/tool-surface.mjs";
+const v = await executeOrgTool("design_voice", {});
+console.log(v.ok ? JSON.stringify(v.result, null, 2) : v.error);
+'
+```
+
+- `design_voice` — the voice statement, the trait pills that are ON, the
+  SAY/AVOID lexicon, and worked in-practice examples. **Read this before drafting
+  anything the workspace publishes.** It composes with
+  `policies/communication-style.md`, which still governs the mechanics of your
+  prose; voice tells you the register, the style policy tells you what is banned.
+- `design_foundation` — typography, colour, scale, archetype, principles, plus
+  the version-history head. `historyLimit: 0` suppresses the history block;
+  `versionId` reads a historical snapshot.
+- `design_list_templates` — the gallery with each template's status chip. `STALE`
+  means the foundation moved underneath it.
+
+## Producing things (these cost money)
+
+Every producer takes `budgetCents`, clamped server-side to a hard per-run
+ceiling, and returns what it actually spent. Report the spend, every time.
+
+- `design_rewrite_in_voice` — rewrite one sentence in the brand voice. It
+  produces copy; it sends nothing. Whatever you do with the result is screened at
+  the send verb, as normal.
+- `design_render_template` — HTML for any template, PNG for `GENERATED` ones.
+- `design_export_kit` — tokens (`px` | `rem` | `em`), voice, and the mark bytes
+  unless `includeMarks: false`.
+- `design_generate_image` — regenerate canonical image slots.
+
+**Quote before you spend.** `budgetCents: 0` on `design_generate_image` is the
+QUOTE call: it generates nothing, spends nothing, and still returns every slot's
+price and staleness. Omitting `slots` regenerates every STALE slot — never a
+silent full re-run, but still the expensive path. Quote, report the number, then
+spend.
+
+```bash
+node --input-type=module -e '
+import { executeOrgTool } from "./lib/org/tool-surface.mjs";
+const quote = await executeOrgTool("design_generate_image", { budgetCents: 0 });
+if (!quote.ok) { console.log(quote.error); process.exit(0); }
+const stale = (quote.result.slots ?? []).filter((s) => s.stale);
+console.log(`${stale.length} stale slot(s), ${stale.reduce((n, s) => n + (s.priceCents ?? 0), 0)}c to refresh`);
+'
+```
+
+## Proposing a foundation change
+
+```bash
+node --input-type=module -e '
+import { executeOrgTool } from "./lib/org/tool-surface.mjs";
+const head = await executeOrgTool("design_foundation", { historyLimit: 1 });
+const res = await executeOrgTool("design_propose_change", {
+  patch: { fonts: { display: "Söhne", body: "Söhne", mono: "Söhne Mono" } },
+  note: "Unify the display and body face",
+  rationale: "Two faces at the same optical size read as an accident on the pricing page.",
+  expectedVersionId: head.ok ? head.result.headVersionId : undefined,
+});
+console.log(res.ok ? res.result : res.error);
+'
+```
+
+Two things will bite you:
+
+1. **Blocks are replaced wholesale.** Send the *complete* block — the whole
+   `fonts` object, the whole `colors` array. A partial block is a silent
+   half-write that drops every key you left out.
+2. **Pass `expectedVersionId`** from `design_foundation`. A proposal computed
+   against a head that has since moved is refused rather than staged against
+   stale ground.
+
+The proposal writes nothing. A human applies it, and their note becomes the
+version label.
+
+## Human-only, by design
+
+`branding.saveFoundation` and `branding.restoreFoundation` are `admin` scope — an
+ordinary agent seat cannot reach them, and that is the point. When the foundation
+genuinely needs to move, stage the diff and put it in front of the human with the
+rationale you would give in review.
+
+## The long tail via `org_rpc`
+
+`branding.listVersions` and `branding.exportTemplate` (both `org.read`), plus the
+admin Brand Studio surface: `branding.regenerate`, `branding.regenerateTemplates`,
+`branding.regenerateTemplate`, `branding.regenerateImages`, `branding.uploadImage`,
+`branding.amendArtifact`, `branding.amendTemplate`, `branding.cloneTemplate`,
+`branding.deleteTemplate`, `branding.restoreVersion`, `branding.undo`,
+`branding.redo`.
+
+## Rules of the desk
+
+- Voice first. Never draft published copy before reading `design_voice`;
+  `policies/communication-style.md` still governs the prose mechanics on top.
+- Quote, then spend, then report the cost in cents. An unreported spend is a
+  surprise on someone's invoice.
+- Stale is a fact, not a verdict — say which slots and templates are stale and
+  what refreshing them costs; let the human choose.
+- Propose foundation changes with a rationale a reviewer can act on. "Looks
+  better" is not one.

package/plugins/maestro-skills/skills/calendar-plan.md

@@ -0,0 +1,57 @@
+---
+name: calendar-plan
+description: Plan and manage workspace calendar events — scan attendees' calendars for a free slot deterministically, create typed events with real invites, answer your own invites, and reschedule with everyone notified. Use when asked to find a time, set up a meeting or focus block, respond to an invite, or move an event.
+---
+
+# Calendar Planning
+
+The workspace calendar is a governed surface: events are typed
+(`MEETING / REVIEW / FOCUS / AGENT_BLOCK / ALL_HANDS / HOLD`), invites queue REAL
+emails, an optional `channelId` posts the invite note as a real channel message, and
+guardian reshapes are logged. Agent seats answer their own invites and COMMIT.
+
+All of it is `executeOrgTool` over the calendar-desk tools; fail-open frames.
+
+## Find a time first
+
+`calendar_find_a_time` is a deterministic free-slot scan across the attendees'
+calendars — agent blocks included, nothing persisted, no model involved:
+
+```bash
+node --input-type=module -e '
+import { executeOrgTool } from "./lib/org/tool-surface.mjs";
+const res = await executeOrgTool("calendar_find_a_time", {
+  attendeeMemberIds: ["m_alex", "m_robin"], durationMinutes: 45, fromDay: "2026-07-28",
+});
+console.log(JSON.stringify(res, null, 2));
+'
+```
+
+Propose from its slots — never invent availability.
+
+## Create, answer, move
+
+- `calendar_create` — typed event with attendees; `channelId` (optional) posts the
+  invite note into that channel; invite emails queue for real. Idempotent — a
+  replayed create does not double-book.
+- `calendar_rsvp` — the acting seat answers its OWN invite (`ACCEPTED` /
+  `DECLINED` / `TENTATIVE`). Agents commit; do not leave invites hanging.
+- `calendar_list` `{fromDay, toDay, viewpoint?}` / `calendar_get` `{eventId}` —
+  the window read and the single-event read (attendee rows + linked records).
+- Long tail via `org_rpc`: `calendar.update` (fields/attendees),
+  `calendar.reschedule` (move; invites update, guardian reshapes logged),
+  `calendar.delete` (release the slot; attendees notified).
+
+## Meetings → the knowledge plane
+
+After a held meeting, `meetings_recap_file` files the recap + transcript into the
+workspace drive — two DOC files plus a MeetingRecord with links back to the event.
+Use it as the notetaker's landing verb; `org_rpc` `meetings.record` records a
+meeting into the org's knowledge plane directly.
+
+## Rules of the desk
+
+- Scan before you book; state whose calendars you scanned.
+- One event per intent — rely on create's idempotency instead of re-firing blind.
+- When you move someone else's meeting, say why in the update — the reshape is
+  logged either way.

package/plugins/maestro-skills/skills/call-working-sessions.md

@@ -0,0 +1,124 @@
+---
+name: call-working-sessions
+description: Turn a Cohort call into a working session — present a doc/sheet/channel/board/charter on the call stage, step through it (scroll/highlight/type), live-edit docs while talking, read what participants see on screen, and watch reactions and raised hands. Use when you are a participant in a live Cohort call and want to show rather than tell, walk people through a document, or ground "this chart / that number" talk in what is actually on screen.
+---
+
+# Call working sessions
+
+When you're in a Cohort call, you can do more than talk: you can PRESENT a
+workspace surface on the call stage like a screen share, drive it with steps
+every participant sees, and read back the room — what's on screen, who reacted,
+whose hand is up.
+
+All of it rides the calls-desk org tools (`executeOrgTool`, fail-open frames,
+never a throw) or the equivalent `calling*` wrappers in `lib/org/client.mjs`.
+You must be a participant in the (still-live) call for every verb below.
+
+## Presenting a surface
+
+`org_call_share_start` puts a surface on the stage. Surface kinds and refs:
+`doc` / `sheet` (a drive fileId), `channel` (channelId), `board` (`"org"`),
+`charter` (charter slug).
+
+```bash
+node --input-type=module -e '
+import { callingAppShareStart } from "./lib/org/client.mjs";
+import { resolveOrgToolConfig } from "./lib/org/tool-surface.mjs";
+const { base, orgId, token } = resolveOrgToolConfig();
+const res = await callingAppShareStart(
+  { callId: "CALL_ID", surface: { kind: "doc", ref: "FILE_ID", title: "Q3 plan" } },
+  { base, token, orgId },
+);
+console.log(JSON.stringify(res));   // {ok:true, result:{sessionId}} — keep the sessionId
+'
+```
+
+One active session per call: starting again supersedes your own session; a
+`CONFLICT` frame means another member is presenting — wait or ask, never fight
+for the stage. And always narrate verbally what you're showing: the tile is a
+visual aid, the meeting is still a conversation.
+
+## Stepping through it
+
+`org_call_share_step` sends a batch (≤20) of choreography steps the tiles
+animate:
+
+- `{k:"cursor", x, y}` — move your pointer (normalized 0..1).
+- `{k:"scroll", anchor}` — bring an anchor into view.
+- `{k:"highlight", anchor, note?}` — ring it, with an optional ≤200-char note.
+- `{k:"type", anchor, text}` — a visual typing preview (≤2000 chars). This is
+  NOT a real edit — see live-editing below.
+- `{k:"refresh"}` — every tile refetches the surface content.
+
+Anchors: `block:3` (doc block), `msg:<id>` (channel message), `cell:B4`
+(sheet), `task:<id>` (board), `section:<idx>` (charter), `top` / `bottom`.
+
+```bash
+node --input-type=module -e '
+import { callingAppShareAct } from "./lib/org/client.mjs";
+import { resolveOrgToolConfig } from "./lib/org/tool-surface.mjs";
+const { base, orgId, token } = resolveOrgToolConfig();
+const res = await callingAppShareAct(
+  { callId: "CALL_ID", sessionId: "SESSION_ID", steps: [
+    { k: "scroll", anchor: "block:3" },
+    { k: "highlight", anchor: "block:3", note: "the revenue line we discussed" },
+  ] },
+  { base, token, orgId },
+);
+console.log(JSON.stringify(res));   // {ok:true, result:{seq}}
+'
+```
+
+Highlight notes and typed text are read by every human on the call, so the
+send-gate screens them locally before dispatch — same as a channel message.
+
+## Live-editing a doc while talking
+
+Real edits ride the files desk, not the share lane. The pattern:
+
+1. `files_doc_write` (or `org_rpc files.sheetWriteCells`) — the REAL revision.
+2. A share step batch: `{k:"type", ...}` to animate the change being written,
+   then `{k:"refresh"}` so every tile settles on the canonical new content.
+
+The room sees the edit happen; the drive records a real DocRevision.
+
+## Reading the room
+
+- `org_call_visual_context` — the narrated visual stream: `{kind: screen|
+  camera|appshare, sourceMemberId, summary, at}` rows distilled from sampled
+  frames (narration text only — frames are never persisted). Use it before
+  answering "this chart" / "that number" talk so you speak to what's actually
+  on screen.
+- `org_call_events` — recent non-speech events: reactions, raised/lowered
+  hands, joins, share lifecycle. A raised hand you can see is an invitation to
+  bring someone in.
+
+```bash
+node --input-type=module -e '
+import { callingGetVisualContext, callingGetCallEvents } from "./lib/org/client.mjs";
+import { resolveOrgToolConfig } from "./lib/org/tool-surface.mjs";
+const { base, orgId, token } = resolveOrgToolConfig();
+console.log(JSON.stringify(await callingGetVisualContext({ callId: "CALL_ID", limit: 20 }, { base, token, orgId })));
+console.log(JSON.stringify(await callingGetCallEvents({ callId: "CALL_ID", limit: 30 }, { base, token, orgId })));
+'
+```
+
+`callingGetAppShare({ callId })` returns the active session (or `null`) —
+check it before starting your own.
+
+## Ending
+
+`org_call_share_end` (`callingAppShareEnd({ callId, sessionId })`) clears the
+stage; the sharer or the call host may end a session. End your share when the
+walkthrough is done — don't squat on the stage.
+
+## Rules of the desk
+
+- Participant-gated: every verb refuses when you're not in the call, or the
+  call has ended (`CONFLICT`) — surface it, don't retry blindly.
+- The chain is redacted: share events record ids/counts only; your step text
+  reaches call participants' screens, never the org event chain.
+- Step text is human-visible — write it like something you'd say out loud, and
+  keep the policies/communication-style.md register.
+- Show AND tell: pair every share step with spoken narration; a silent moving
+  cursor is confusing, not helpful.

package/plugins/maestro-skills/skills/ccxray-diagnostics.md

@@ -0,0 +1,91 @@
+---
+name: ccxray-diagnostics
+description: Run token/cost X-ray diagnostics on Claude API sessions — per-turn breakdown, context window heatmaps, system prompt diffs. Use for debugging expensive sessions or comparing sub-agent efficiency.
+---
+
+# Token/Cost X-Ray Diagnostics (ccxray)
+
+You are a Maestro agent. Use ccxray to diagnose token usage, cost, and context window utilization across agent sessions.
+
+## When to Invoke
+
+- **Debugging expensive sessions** — a backlog cycle consumed unexpectedly high tokens
+- **Sub-agent efficiency comparison** — comparing token cost across parallel agents doing similar work
+- **Context window analysis** — investigating whether agents are hitting context limits or carrying stale context
+- **System prompt auditing** — diffing system prompts across agents to find bloat
+- **Post-incident analysis** — understanding what went wrong in a failed or degraded session
+
+## Background
+
+ccxray is a transparent HTTP proxy that intercepts all Claude API calls and provides a live dashboard with per-turn token/cost breakdowns. It is an on-demand diagnostic tool, not always-on infrastructure.
+
+- Proxy + dashboard: `npx ccxray claude`
+- Logs stored at: `~/.ccxray/logs/`
+- Dashboard shows live data during the session
+
+## Steps
+
+1. **Launch a diagnostic session** — run the target agent through ccxray:
+   ```bash
+   npx ccxray claude
+   ```
+   This wraps the Claude Code session in the ccxray proxy. All API calls are intercepted and logged.
+
+2. **Open the dashboard** — ccxray serves a local dashboard showing:
+   - Per-turn input/output token counts
+   - Cumulative cost tracking
+   - Context window heatmap (what is filling the window)
+   - System prompt content and diffs between turns
+
+3. **Analyze token distribution** — identify where tokens are being spent:
+   - Large system prompts eating context budget
+   - Repeated tool outputs inflating input tokens
+   - Verbose agent responses consuming output tokens
+   - Context window near capacity causing cache misses
+
+4. **Compare sub-agents** — if multiple agents ran in parallel, compare their ccxray logs:
+   - Which agent consumed the most tokens per unit of work?
+   - Are any agents carrying unnecessary context?
+   - Are system prompts appropriately sized for each agent's role?
+
+5. **Review historical logs** — check `~/.ccxray/logs/` for past session data:
+   ```bash
+   ls -lt ~/.ccxray/logs/
+   ```
+
+6. **Produce findings** — summarize token/cost insights and recommend optimizations.
+
+## Output
+
+Report the following:
+
+```
+## Token/Cost X-Ray Report
+
+### Session Summary
+- Total input tokens: [N]
+- Total output tokens: [N]
+- Estimated cost: $[X.XX]
+- Turns: [N]
+- Context window peak: [N]% utilization
+
+### Top Token Consumers
+1. [Turn/phase] — [N] tokens ([reason])
+2. [Turn/phase] — [N] tokens ([reason])
+
+### Optimization Recommendations
+- [Specific recommendation, e.g., "Reduce system prompt by removing unused policy sections"]
+- [Specific recommendation, e.g., "Cache tool outputs instead of re-reading files"]
+
+### Sub-Agent Comparison (if applicable)
+| Agent | Input Tokens | Output Tokens | Cost | Efficiency |
+|---|---|---|---|---|
+| [name] | [N] | [N] | $[X] | [notes] |
+```
+
+## Integration Notes
+
+- This is an on-demand tool — do NOT run ccxray on every session, only when diagnosing issues
+- ccxray adds minimal overhead (~5ms per request) but writes logs to disk
+- Use for periodic token budget audits per backlog cycle (e.g., weekly)
+- Pair with claude-pace to correlate token usage with quota consumption

package/plugins/maestro-skills/skills/claude-pace.md

@@ -0,0 +1,61 @@
+---
+name: claude-pace
+description: Check Claude API rate limit quota — 5-hour/7-day usage, reset countdowns, pace delta. Use before heavy backlog cycles, when quota warnings appear, or to decide whether to defer non-urgent work.
+---
+
+# Rate Limit Monitoring (claude-pace)
+
+You are a Maestro agent. Use the claude-pace status line plugin to monitor API quota and make informed scheduling decisions.
+
+## When to Invoke
+
+- **Before heavy backlog cycles** — check headroom before spawning parallel agents
+- **When quota warnings appear** — "hit your limit" or rate-limit errors in logs
+- **Capacity planning** — deciding whether to defer improvement-backlog or non-urgent items
+- **Post-incident** — confirming quota has recovered after a rate-limit outage
+
+## Background
+
+claude-pace is a Claude Code status line plugin (Bash + jq, ~10ms latency). It is auto-installed by `init-agent.sh` via `claude plugin marketplace add Astro-Han/claude-pace`. It displays real-time quota data in the Claude Code status bar.
+
+The key signal is **pace delta**:
+- **Green** — headroom available, safe to proceed with full parallelism
+- **Yellow** — approaching limits, reduce parallel agent count
+- **Red** — near or at limit, defer all non-urgent work immediately
+
+## Steps
+
+1. **Read the status line** — claude-pace displays 5-hour window usage, 7-day rolling usage, and time until next reset directly in the Claude Code status bar.
+
+2. **Evaluate pace delta** — determine current capacity:
+   - **Green (>40% remaining)**: Proceed normally. Full parallel agent spawning is safe.
+   - **Yellow (15-40% remaining)**: Reduce to 2 parallel agents max. Defer improvement-backlog items.
+   - **Red (<15% remaining)**: Critical items only. No parallel spawning. Defer all non-urgent work.
+
+3. **Check reset countdown** — if quota is constrained, note when the 5-hour window resets. Schedule deferred work for after reset.
+
+4. **Adjust execution plan** based on findings:
+   - Prioritize critical/high-priority queue items only when constrained
+   - Move improvement-backlog and low-priority items to next cycle
+   - Reduce `parallel_with` fan-out in workflow steps
+   - Log the capacity decision in the session audit
+
+5. **If rate-limit outage is suspected**, check workflow logs for the pattern: `"started"` entry without a matching `"completed"` entry, and inspect `.log` files for `"hit your limit"` strings.
+
+## Output
+
+Report the following to the calling agent or session:
+
+```
+## Quota Status
+- 5-hour window: [X]% used — resets in [T]
+- 7-day rolling: [X]% used
+- Pace delta: [green/yellow/red]
+- Recommendation: [proceed normally / reduce parallelism / critical-only mode]
+```
+
+## Integration Notes
+
+- Complements Maestro's reactive rate-limit detection (checking logs post-facto) with proactive visibility
+- Does NOT require launching a separate process — data is in the status bar
+- When pace delta is red, the backlog executor should automatically shrink its batch size from 3-5 items to 1-2

package/plugins/maestro-skills/skills/code-review-graph.md

@@ -0,0 +1,99 @@
+---
+name: code-review-graph
+description: Structural code analysis via tree-sitter knowledge graph — blast radius, review context, architecture overview, semantic search. Use for PR reviews, refactoring, and engineering health checks.
+---
+
+# Structural Code Analysis (code-review-graph)
+
+You are a Maestro agent. Use code-review-graph to build and query a tree-sitter-based knowledge graph of any codebase for structural analysis.
+
+## When to Invoke
+
+- **PR reviews** — assess blast radius of changes before approving
+- **Refactoring** — understand call chains, import graphs, and dependencies before making changes
+- **Engineering health checks** — generate architecture overviews for repos in the portfolio
+- **Pre-change analysis** — determine what will break if a function/class is modified
+- **Semantic code search** — find functions, patterns, or relationships across a codebase
+
+## Background
+
+code-review-graph uses tree-sitter to parse source code and build a knowledge graph mapping functions, classes, imports, and call relationships. It provides both CLI tools and an MCP server with specialized analysis tools.
+
+## Steps
+
+### One-Time Setup
+
+1. **Index the target repository**:
+   ```bash
+   npx code-review-graph index /path/to/repo
+   ```
+   This parses all source files and builds the knowledge graph. Re-run after significant changes.
+
+2. **Configure as MCP server** (optional, for persistent access):
+   Add to `.claude/settings.json` under `mcpServers`:
+   ```json
+   {
+     "code-review-graph": {
+       "command": "npx",
+       "args": ["code-review-graph", "serve", "--port", "3848"]
+     }
+   }
+   ```
+
+### Analysis Workflows
+
+3. **Blast radius analysis** — before approving a PR or making a change:
+   - Query which functions/modules depend on the changed code
+   - Identify downstream consumers that may break
+   - Map the full call chain from changed function to entry points
+   - Tool: `blast_radius` (via MCP) or CLI equivalent
+
+4. **Review context** — when reviewing a PR:
+   - Pull structural context for changed files (what calls them, what they call)
+   - Identify if changes touch hot paths or critical modules
+   - Surface related functions that should have been changed but were not
+   - Tool: `review_context` (via MCP)
+
+5. **Architecture overview** — for engineering health checks:
+   - Generate module dependency graph
+   - Identify circular dependencies
+   - Map public API surface vs internal implementation
+   - Surface orphaned code (defined but never called)
+   - Tool: `architecture_overview` (via MCP)
+
+6. **Semantic search** — finding code by intent:
+   - Search for functions matching a description or pattern
+   - Find all implementations of a given interface
+   - Locate similar code patterns across the codebase
+   - Tool: `semantic_search` (via MCP)
+
+## Output
+
+Report findings appropriate to the workflow:
+
+**For blast radius:**
+```
+## Blast Radius: [function/file]
+- Direct dependents: [N] functions in [N] files
+- Transitive impact: [N] modules
+- Risk level: [low/medium/high]
+- Affected entry points: [list]
+```
+
+**For architecture overview:**
+```
+## Architecture: [repo]
+- Modules: [N]
+- Key dependency chains: [list top 3]
+- Circular dependencies: [list or "none"]
+- Orphaned exports: [count]
+- Hottest module (most dependents): [name]
+```
+
+## Integration Notes
+
+- Recommended for coding-oriented agents (engineering, platform, product)
+- Optional for operational agents (comms, hiring, strategy) — they rarely need code-level analysis
+- Re-index after merging significant PRs to keep the graph current
+- The MCP server runs on port 3848 by default — ensure no conflicts
+- Graph build time scales with repo size; large monorepos may take 30-60 seconds

package/plugins/maestro-skills/skills/crm-pipeline.md

@@ -0,0 +1,65 @@
+---
+name: crm-pipeline
+description: Work the org's CRM desk — pipeline and deal reads, stage moves, attributed interaction logging, next-best-action inside playbook lines, and the escalation lane where humans sign held work. Use when asked about pipeline state, to progress or hand over a deal, to log a touch, or to run the next step on a deal.
+---
+
+# CRM Pipeline
+
+The CRM desk is playbook-governed: agents run inside compiled playbook lines,
+manual holds gate the next outbound step, and the verbs that commit the org —
+signing held work, setting the quarter's target — are HUMAN-ONLY in the domain
+layer. An agent call to those fails exactly as the UI would never allow it; that
+refusal is correct behaviour, not an error to work around. Money is integer cents
+everywhere.
+
+All of it is `executeOrgTool` over the crm-desk tools; fail-open frames.
+
+## Reading the pipeline
+
+```bash
+node --input-type=module -e '
+import { executeOrgTool } from "./lib/org/tool-surface.mjs";
+const res = await executeOrgTool("crm_list_deals", { openOnly: true });
+for (const d of res.ok ? res.result.deals ?? res.result : []) console.log(d.id, d.stage, d.name, d.valueCents);
+'
+```
+
+- `crm_get_deal` — one deal + its attributed trail.
+- `crm_list_escalations` — deals holding for a human signature (the guardian
+  queue). Surface these; never "resolve" them yourself.
+- Long-tail reads via `org_rpc`: `crm.listAccounts` (health + ARR),
+  `crm.listContacts`, `crm.listInteractions`, `crm.listPlaybooks`,
+  `crm.getTargets` (target + live committed/best-case), `crm.compilePlaybook`
+  (PURE preview, nothing persisted).
+
+## Progressing a deal
+
+- `crm_create_deal` — open at INBOUND.
+- `crm_move_stage` — stage/board move, logged.
+- `crm_log_interaction` — an attributed touch on the deal/contact trail. Log every
+  real touch; the trail is the deal's story.
+- `crm_next_best_action` — start the playbook's proposed step. Holds gate NBA: a
+  deal holding for signature will not run — report the hold.
+- Long tail via `org_rpc`: `crm.updateDeal` (term edits re-evaluate playbooks),
+  `crm.closeDeal` (won → a REAL Books draft invoice), `crm.delegate` (owner
+  reassign + a real handover board task), `crm.taskFollowThrough` (a real
+  work-board task), `crm.shareDeal` (people grants; a channelId posts a real
+  system line), `crm.linkContact` / `crm.linkFiles`, `crm.holdNextStep` (manual
+  signature gate), `crm.returnEscalation` (return held work with a posture note),
+  `crm.updateHeldTerms` (re-price held terms), `crm.logDealDecision` (a real
+  Decision row in the registry), `crm.pinNote`, `crm.redactInteraction` (SOFT —
+  the ledger record remains), accounts/contacts CRUD, playbook save/toggle/delete
+  (locked playbooks refuse), `crm.setTarget`.
+
+## Human-only, by design
+
+`crm.signEscalation` and `crm.setTarget`'s `targetCents` refuse non-human actors in
+the domain. When a deal needs a signature: put it in front of the human
+(`crm.listEscalations` + a channel note), do not attempt the sign.
+
+## Rules of the desk
+
+- Attribute everything — an unlogged touch did not happen.
+- Report holds and escalations verbatim (stage, amount in cents, what tripped).
+- Won deals hand off to Books automatically; check `books_invoices` before
+  drafting a duplicate.