@cleocode/skills 2026.9.20 → 2026.9.22

package/skills/_shared/manifest-operations.md

@@ -15,7 +15,7 @@ The manifest system provides O(1) append operations and race-condition-free conc
 **Default Paths**:
 - Output directory: `.cleo/agent-outputs/` (configurable via `agentOutputs.directory`)
 - Manifest store: `pipeline_manifest` SQLite table (canonical per ADR-027)
-- CLI: `cleo manifest append <json>` — the only supported write path
+- CLI: `cleo manifest append --entry '<json>'` — the only supported write path
 
 **Design Principles**:
 - Append-only writes preserve audit trail
@@ -239,12 +239,9 @@ cleo research show jwt-auth-2026-02-07  # Check linked_tasks
 
 ---
 
-### cleo research unlink
+### research unlink (retired)
 
-> **Note**: Not currently implemented in the CLI. To disassociate research from a task, use
-> `cleo research update <id>` to change status, or remove the link manually from the task record.
-
----
+Retired. Link edits go through `cleo research link`; there is no unlink verb.
 
 ### cleo research links
 
@@ -322,19 +319,13 @@ cleo research archive --before-date 2026-01-01
 
 ---
 
-### cleo research archive-list
+### research archive-list (retired)
 
-> **Note**: Not currently implemented in the CLI. To list archived entries, use
-> `cleo research list --status archived` or query the archive file directly.
-
----
+Retired. List archived entries with `cleo manifest list --filter archived`.
 
-### cleo research status
+### research status (retired)
 
-> **Note**: Not currently implemented as a separate CLI command. Use `cleo research stats`
-> for manifest statistics.
-
----
+Retired. Use `cleo research stats` or `cleo manifest stats`.
 
 ### cleo research stats
 
@@ -369,33 +360,21 @@ cleo research stats
 
 ---
 
-### cleo research validate
-
-> **Note**: Not currently implemented in the CLI. Manifest validation occurs automatically
-> when entries are created via `cleo research add`.
-
----
-
-### cleo research compact
+### research validate (retired)
 
-> **Note**: Not currently implemented in the CLI. Use `cleo research archive` to manage
-> manifest size.
+Retired. Validate a subagent's output with `cleo orchestrate validate <taskId>` or `cleo check output`.
 
----
+### research compact (retired)
 
-### cleo research get
+Retired. The pipeline_manifest table needs no compaction (ADR-027).
 
-> **Note**: Not currently implemented as a separate CLI command. Use `cleo research show <id>`
-> for entry details.
+### research get (retired)
 
----
-
-### cleo research inject
+Retired. Use `cleo research show <id>` or `cleo manifest show <id>`.
 
-> **Note**: Not currently implemented in the CLI. The orchestrator generates fully-resolved
-> subagent prompts via `cleo orchestrator spawn <taskId>`.
+### research inject (retired)
 
----
+Retired. `cleo orchestrate spawn <taskId>` embeds the subagent protocol in the prompt it returns.
 
 ## Manifest Entry Schema
 
@@ -454,7 +433,7 @@ When present, the `audit` field provides operational metadata:
 | `{{EPIC_ID}}` | Parent epic identifier | `T3147` |
 | `{{DATE}}` | Current date | `2026-02-07` |
 | `{{TOPIC_SLUG}}` | URL-safe topic name | `jwt-authentication` |
-| `{{OUTPUT_DIR}}` | Output directory | `.cleo/agent-outputs` |
+| `{{OUTPUT_DIR}}` | Output directory | `.cleo/agent-outputs` (legacy token — do not write there; record output with `cleo docs add`) |
 
 
 ### Command Tokens (CLEO Defaults)
@@ -477,7 +456,7 @@ When present, the `audit` field provides operational metadata:
 ```markdown
 ## Output Requirements
 
-1. Write findings to `{{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md`
+1. Record findings with `cleo docs add {{TASK_ID}} --content - --type <kind> --slug {{TOPIC_SLUG}}`
 2. Create manifest entry:
 
 ```bash
@@ -526,7 +505,7 @@ echo '{"id": "test", "title": "Test"}' >> .cleo/agent-outputs/legacy-manifest.js
 
 **Solution**: Use `cleo manifest append`
 ```bash
-cleo manifest append '{"id":"test","task_id":"T###","type":"research","status":"complete","output":"path/to/output.md","summary":"brief","key_findings":["..."]}'
+cleo manifest append --entry '{"id":"test","task_id":"T###","type":"research","status":"complete","output":"path/to/output.md","summary":"brief","key_findings":["..."]}'
 ```
 
 ---
@@ -542,7 +521,7 @@ echo "$json" >> .cleo/agent-outputs/legacy-manifest.jsonl
 
 **Solution**: Use `cleo manifest append`
 ```bash
-cleo manifest append '{"id":"...","task_id":"T####","type":"...","status":"complete","output":"...","summary":"...","key_findings":["..."]}'
+cleo manifest append --entry '{"id":"...","task_id":"T####","type":"...","status":"complete","output":"...","summary":"...","key_findings":["..."]}'
 ```
 
 ---

package/skills/_shared/skill-chaining-patterns.md

@@ -41,7 +41,7 @@ The orchestrator delegates work to a subagent via `orchestrate.spawn` with skill
 
 ```bash
 # Generate fully-resolved spawn prompt
-cleo orchestrator spawn T1234 --json
+cleo orchestrate spawn T1234 --json
 
 # Provider adapter executes the prompt using its native mechanism
 #    - Claude Code: Task tool with cleo-subagent type
@@ -84,14 +84,10 @@ A skill invokes other skills to complete workflow phases. The loaded skill maint
 
 ```markdown
 # Via Skill tool (programmatic)
-Skill(skill="ct-docs-lookup")
-Skill(skill="ct-docs-write")
-Skill(skill="ct-docs-review")
+Skill(skill="ct-documentor")   # writing + review references
 
 # Via slash command (user-facing)
-/ct-docs-lookup
-/ct-docs-write
-/ct-docs-review
+/ct-documentor
 ```
 
 ### When to Use Skill Chaining
@@ -180,7 +176,7 @@ Subagent MUST NOT return output content in response.
 ### Rule 3: File-Based Details (MUST)
 
 Detailed findings go to output files, not manifest or response:
-- Full analysis → `{{OUTPUT_DIR}}/YYYY-MM-DD_topic.md`
+- Full analysis → `cleo docs add <taskId> --content - --type research --slug <topic>`
 - Summary only → pipeline_manifest key_findings (via `cleo manifest append`)
 
 ### Rule 4: Token Injection (SHOULD)
@@ -213,7 +209,7 @@ TOPIC_SLUG    # URL-safe topic name
 Before spawning subagent:
 - [ ] Identify appropriate skill for task type
 - [ ] Prepare token context (TASK_ID, DATE, TOPIC_SLUG)
-- [ ] `cleo orchestrator spawn <taskId> --json`
+- [ ] `cleo orchestrate spawn <taskId> --json`
 - [ ] Verify token resolution is complete (`tokenResolution.fullyResolved`)
 
 Before chaining to another skill:

package/skills/_shared/subagent-protocol-base.md

@@ -15,8 +15,8 @@ All subagents operating under an orchestrator MUST follow this protocol.
 
 | ID | Rule | Compliance |
 |----|------|------------|
-| OUT-001 | MUST write findings to `{{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md` | Required |
-| OUT-002 | MUST append ONE entry via `cleo manifest append <json>` (writes to pipeline_manifest table per ADR-027/T1093) | Required |
+| OUT-001 | MUST record findings with `cleo docs add {{TASK_ID}} --content - --type <kind> --slug {{TOPIC_SLUG}}` (never a raw file under `.cleo/agent-outputs/`) | Required |
+| OUT-002 | MUST append ONE entry via `cleo manifest append --entry '<json>'` (writes to pipeline_manifest table per ADR-027/T1093) | Required |
 | OUT-003 | MUST return ONLY: "[Type] complete. Manifest appended to pipeline_manifest." | Required |
 | OUT-004 | MUST NOT return output content in response | Required |
 
@@ -36,7 +36,7 @@ Valid return messages:
 
 ## Output File Format
 
-Write to `{{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md`:
+Record it with `cleo docs add {{TASK_ID}} --content - --type <kind> --slug {{TOPIC_SLUG}}`, using this body:
 
 ```markdown
 # {{TITLE}}
@@ -107,7 +107,7 @@ Reference: @skills/_shared/task-system-integration.md
 1. Read task:    {{TASK_SHOW_CMD}} {{TASK_ID}}
 2. Start task:   {{TASK_START_CMD}} {{TASK_ID}}
 3. Do work:      [skill-specific execution]
-4. Write output: {{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md
+4. Record output: `cleo docs add {{TASK_ID}} --content - --type <kind> --slug {{TOPIC_SLUG}}`
 5. Create manifest entry: cleo research add [flags]
 6. Complete:     {{TASK_COMPLETE_CMD}} {{TASK_ID}}
 7. Return:       "[Type] complete. Manifest appended to pipeline_manifest."
@@ -154,7 +154,7 @@ Reference: @skills/_shared/task-system-integration.md
 Before returning, verify:
 
 - [ ] Task started via `{{TASK_START_CMD}}`
-- [ ] Output file written to `{{OUTPUT_DIR}}/`
+- [ ] Output recorded with `cleo docs add` (slug in the return message)
 - [ ] Manifest entry created via `cleo research add`
 - [ ] Task completed via `{{TASK_COMPLETE_CMD}}`
 - [ ] Response is ONLY the summary message
@@ -177,7 +177,7 @@ Before returning, verify:
 |-------|---------|-------------|
 | `{{EPIC_ID}}` | `""` | Parent epic ID |
 | `{{SESSION_ID}}` | `""` | Session identifier |
-| `{{OUTPUT_DIR}}` | `.cleo/agent-outputs` | Output directory |
+| `{{OUTPUT_DIR}}` | `.cleo/agent-outputs` | Output directory (legacy token — do not write there; record output with `cleo docs add`) |
 
 ### Task System Tokens (CLEO defaults)
 

package/skills/_shared/task-system-integration.md

@@ -120,7 +120,7 @@ When the task system is CLEO, these additional commands are available:
 |---------|---------|
 | `cleo current` | Show current task |
 | `cleo session start` | Begin work session |
-| `cleo session end` | End work session |
+| `cleo session end` | End THIS terminal's session (elsewhere: `--session <id>`; unbound → `E_SESSION_UNBOUND`) |
 | `cleo analyze` | Task triage with scoring |
 | `cleo deps show {{TASK_ID}}` | Check task dependencies |
 | `cleo tree {{EPIC_ID}}` | Visualize hierarchy rooted at epic |
@@ -133,24 +133,24 @@ Sessions persist across Claude conversations and support long-running work.
 - Sessions receive timeout warning after **72 hours** of inactivity
 - Active sessions are auto-ended after **7 days** (configurable via `retention.autoEndActiveAfterDays`)
 - Ended/suspended sessions can be cleaned up with `cleo session gc`
-- Stale active sessions (72h+) cleaned with `cleo session gc --include-active`
+- Stale active sessions cleaned with `cleo session gc --max-age <days>`
 
 **Session Commands**:
 
 | Command | Purpose |
 |---------|---------|
-| `cleo session start --scope epic:{{EPIC_ID}}` | Begin scoped session |
+| `cleo session start --scope epic:{{EPIC_ID}} --name "..."` | Begin scoped session (`--name` is required) |
 | `cleo session end --note "summary"` | End session properly |
 | `cleo session list` | Check existing sessions |
 | `cleo session resume <id>` | Resume previous session |
 | `cleo session gc` | Clean up ended/suspended sessions |
-| `cleo session gc --include-active` | Also clean stale active sessions |
+| `cleo session gc --max-age <days>` | Also end active sessions older than N days |
 
 **Best Practices**:
 - **MUST** check `cleo session list` before starting new sessions
 - **SHOULD** end sessions properly with `cleo session end --note "summary"` to avoid accumulation
 - **SHOULD** use `cleo session gc` periodically to clean up old ended/suspended sessions
-- **MAY** use `cleo session gc --include-active` to clean stale active sessions (72h+ inactive)
+- **MAY** use `cleo session gc --max-age <days>` to end stale active sessions
 - Long-running sessions (multi-day work) are expected and supported
 
 ---
@@ -168,7 +168,7 @@ When tokens are not explicitly configured, assume CLEO defaults:
 | `{{TASK_LIST_CMD}}` | `cleo list` |
 | `{{TASK_FIND_CMD}}` | `cleo find` |
 | `{{TASK_ADD_CMD}}` | `cleo add` |
-| `{{OUTPUT_DIR}}` | `.cleo/agent-outputs` |
+| `{{OUTPUT_DIR}}` | `.cleo/agent-outputs` (legacy token — do not write there; record output with `cleo docs add`) |
 
 
 ---

package/skills/ct-adr-recorder/SKILL.md

@@ -2,10 +2,19 @@
 name: ct-adr-recorder
 description: "Records Architecture Decision Records from accepted consensus verdicts. Use when promoting a consensus outcome to a formal ADR: drafts the document in the proposed-then-accepted HITL lifecycle, links to the originating consensus manifest, persists the decision to the canonical SQLite decisions table, and triggers downstream invalidation when an accepted ADR is later superseded. Triggers on phrases like 'write ADR', 'record architecture decision', 'formalize this decision', 'lock in the choice', 'create ADR-XXX', or when a consensus task reaches completed status and needs formalization."
 protocol: architecture_decision
-loomStage: architecture_decision
 adrRefs:
   - ADR-053
   - ADR-070
+metadata:
+  version: 1.0.2
+  tier: on-demand
+  install: harness
+  covers:
+    - packages/core/src/validation/protocols/cant/architecture-decision.cant
+    - packages/core/src/validation/protocols/protocols-markdown/architecture-decision.md
+  loomStage: architecture_decision
+  lastReviewed: 2026-09-28
+  stability: stable
 ---
 
 # ADR Recorder
@@ -224,27 +233,24 @@ Validate every ADR manifest entry through `cleo check protocol`:
 
 ```bash
 # Draft reaches proposed: runs inside the skill, before HITL hand-off.
-cleo check protocol \
-  --protocolType architecture-decision \
-  --taskId T4798 \
+cleo check protocol architecture-decision \
+  --task-id T4798 \
   --status proposed \
-  --persistedInDb true \
-  --adrContent "$(cat docs/adr/ADR-0042.md)"
+  --persisted-in-db true \
+  --adr-content "$(cat docs/adr/ADR-0042.md)"
 
 # HITL accepts the ADR: rerun with the review flag.
-cleo check protocol \
-  --protocolType architecture-decision \
-  --taskId T4798 \
+cleo check protocol architecture-decision \
+  --task-id T4798 \
   --status accepted \
-  --hitlReviewed true \
-  --persistedInDb true
+  --hitl-reviewed true \
+  --persisted-in-db true
 
 # Later supersession: include the cascade flag.
-cleo check protocol \
-  --protocolType architecture-decision \
-  --taskId T4798 \
+cleo check protocol architecture-decision \
+  --task-id T4798 \
   --status superseded \
-  --downstreamFlagged true
+  --downstream-flagged true
 ```
 
 Exit code 0 = valid. Exit code 65 = `HANDOFF_REQUIRED`. Exit code 18 = `CASCADE_FAILED`. Exit code 84 = `PROVENANCE_REQUIRED` (attempted ADR without a linked consensus).
@@ -270,7 +276,7 @@ Exit code 0 = valid. Exit code 65 = `HANDOFF_REQUIRED`. Exit code 18 = `CASCADE_
 5. The manifest entry MUST set `agent_type: "decision"` and reference the output markdown file.
 6. Superseding an accepted ADR MUST trigger the downstream cascade over linked specs, decomps, and impls.
 7. Agents MUST NOT retry the HITL handoff on a loop; wait for the human reviewer.
-8. Always validate via `cleo check protocol --protocolType architecture-decision` before exiting.
+8. Always validate via `cleo check protocol architecture-decision` before exiting.
 
 ## See also / References
 

package/skills/ct-artifact-publisher/SKILL.md

@@ -1,6 +1,15 @@
 ---
 name: ct-artifact-publisher
 description: "Builds and publishes artifacts to registries (npm, PyPI, cargo, docker, GitHub releases, generic tarballs) following the validate, then dry-run, then build, then publish, then record-provenance pipeline. Invoked by ct-release-orchestrator as a sub-skill when a release has artifact config. Never stores credentials in output or manifest (ARTP-008), always dry-runs first (ARTP-002), halts and attempts rollback on failure (ARTP-009). Triggers when a release config has at least one enabled artifact handler."
+metadata:
+  version: 1.0.2
+  tier: on-demand
+  install: harness
+  covers:
+    - packages/core/src/validation/protocols/cant/artifact-publish.cant
+    - packages/core/src/validation/protocols/protocols-markdown/artifact-publish.md
+  lastReviewed: 2026-09-28
+  stability: stable
 ---
 
 # Artifact Publisher
@@ -109,11 +118,10 @@ Missing credentials exit 90 (`E_PROVENANCE_CONFIG_INVALID` bubbled from provenan
 Validate the sub-protocol entry through `cleo check protocol`:
 
 ```bash
-cleo check protocol \
-  --protocolType artifact-publish \
-  --taskId T4901 \
-  --artifactType npm-package \
-  --buildPassed true
+cleo check protocol artifact-publish \
+  --task-id T4901 \
+  --artifact-type npm-package \
+  --build-passed true
 ```
 
 Exit code 0 = artifact published successfully. Exit code 85 = unknown artifact type. Exit code 86 = validation failed. Exit code 87 = build failed. Exit code 88 = publish failed, rollback attempted. Exit code 89 = rollback failed, dirty state.
@@ -143,4 +151,4 @@ This skill always hands off to ct-provenance-keeper after publish, before writin
 5. SHA-256 checksums are mandatory for every build output.
 6. Provenance MUST be recorded via `record_release()` after publish, via ct-provenance-keeper.
 7. On first publish failure, halt and attempt rollback; exit 88 on clean rollback, 89 on dirty.
-8. Validate every run via `cleo check protocol --protocolType artifact-publish`.
+8. Validate every run via `cleo check protocol artifact-publish`.

package/skills/ct-cleo/SKILL.md

@@ -2,8 +2,14 @@
 name: ct-cleo
 description: CLEO task management protocol - session, task, and workflow guidance. Use when managing tasks, sessions, or multi-agent workflows with the CLEO CLI protocol.
 metadata:
-  version: 2.20.6
-  lastReviewed: 2026-09-24
+  version: 2.22.2
+  tier: core
+  install: harness
+  covers:
+    - packages/cleo/src/cli/commands/session.ts
+    - packages/cleo/src/cli/commands/focus.ts
+    - packages/cleo/src/cli/commands/sticky.ts
+  lastReviewed: 2026-09-28
   stability: stable
 ---
 
@@ -25,6 +31,43 @@ Provider reference delivery must be verified or embedded self-contained; static
 instruction checks do not establish live Codex, Claude, or Kimi behavior.
 
 
+## Asking the owner (HITL ask tool)
+
+Whenever you need the owner to answer, decide, approve or choose ANYTHING, use the
+ask tool (`AskUserQuestion` in Claude Code, or the provider equivalent listed in
+CAAMP's `PROVIDER_ASK_TOOLS`) with concrete, detailed, selectable options. Never
+ask inside a response, and never bury a question or decision in prose. Each option
+states what happens and its trade-offs; put the recommended option first. Do not
+send routine status chatter: report only when done or when a decision is needed.
+
+- **Subagents never ask the human.** Return the question with its options to your
+  orchestrator (`blocked` plus `{question, options[{label, description}], recommended}`
+  in the manifest); the orchestrator asks via its ask tool.
+- **No ask tool in the harness:** emit one LAFS `hitl.request` envelope
+  `{question, options[{label, description}], recommended}` and stop.
+
+## Project identity and moving between devices
+
+A project is identified by its portable `project_id` in `.cleo/project-id`
+(tracked, write-once; ADR-094). A path is only a per-device hint, so a moved or
+restored checkout keeps its identity. After a new device, restore or migration,
+or when a known repo reports "Not inside a CLEO project", registry paths are
+unreachable, or nexus hits `ENOENT` on an old path, run and report:
+
+1. `cleo doctor projects` — machine-wide: moved, missing, split and temp rows with
+   remedies. Dry-run by default; `--apply` rebinds only on nonce proof and writes a
+   receipt; `--rollback <id>` restores.
+2. `cleo doctor project-identity` — missing, conflicting or uncommitted id.
+3. `cleo doctor --all-projects` — unreachable registered projects.
+4. `cleo nexus projects clean --orphans --dry-run` — NEVER without `--dry-run`;
+   it deletes rows for projects that merely moved.
+5. `cleo doctor credentials` — credentials still keyed by an old path.
+6. `cleo doctor global-delivery` — `~/.cleo`, the global hub reference and every
+   harness CLEO skill install must resolve (a `~/.cleo` link carried by dotfiles from
+   Linux dangles on macOS and silences all of them). `--repair` relinks with a receipt.
+
+Never delete registry rows for projects that may have moved.
+
 ## Guarded knowledge repair
 
 Use `cleo doctor knowledge --dry-run` to inspect findings and sourced proposals.
@@ -60,13 +103,14 @@ applies reviewed input through the same lifecycle; `--fix --actor AGENT` handles
 confirmed stubs. `cleo doctor repair` retains its separate database-recovery semantics.
 
 <!-- thin-pointer: full protocol is in CLEO-INJECTION.md (T9148) -->
-Full protocol content lives in `~/.cleo/templates/CLEO-INJECTION.md`.
-Emit any section with: `cleo briefing inject --section <name>`
+The always-loaded core is `~/.cleo/templates/CLEO-INJECTION.md`; reference sections ship in the
+package's `CLEO-REFERENCE.md` (T12580). Emit any section with: `cleo briefing inject --section <name>`
 
-Supported sections: `session-start` · `work-loop` · `triggers` · `task-creation`
-· `task-discovery` · `task-relationships` · `session-commands` · `memory` · `nexus`
-· `orchestration` · `playbooks` · `documents` · `error-handling` · `pre-complete-gate`
-· `spawn-tiers` · `rules` · `memory-jit` · `escalation`
+Core: `session-start` · `work-loop` · `triggers` · `session-commands` · `output-contract`
+· `error-handling` · `pre-complete-gate` · `rules` · `escalation`. On demand: `task-creation`
+· `task-discovery` · `task-relationships` · `memory` · `memory-jit` · `data-location` · `nexus`
+· `orchestration` · `playbooks` · `documents` · `human-render` · `spawn-tiers` · `evidence`
+· `projection` · `knowledge-repair`
 
 Task find defaults to lexical query terms. Fuzzy character-subsequence matching requires `--fuzzy`; inspect per-row `match.kind` and `match.fields` before inferring related work. `--in` restricts the source field. Matching mode and fuzzy field explanations survive scalar/human output on stderr. Semantic retrieval remains separately identified.
 
@@ -78,11 +122,35 @@ Use `cleo backup inspect <snapshot> --record-id <id>` for read-only historical e
 
 Code-graph answers (`cleo nexus impact`, `context`, `full-context`, `why`, `search-code`, `task-symbols`, `clusters`, `flows`) carry `meta._nexus.freshness`: stale file count and sample, whether the queried symbol's own file is stale, and the refresh command with an estimated cost. A query refreshes up to 25 stale files inline within a 60 s budget (`nexus.autoRefresh.maxFiles`/`budgetMs`/`enabled`) and discloses it in `freshness.autoRefresh`; beyond that it answers from the stale index with `W_NEXUS_INDEX_STALE`. `unknown` freshness is never fresh. `cleo nexus analyze` re-parses only changed files, re-resolves every file, and reports `mode`, `reason` and per-phase cost; it falls back to a full parse (and says why) when there is no parse cache, the extractor build changed, or over 30% of files changed. `--full` forces a rebuild.
 
+## Sessions are terminal-bound (T12500)
+
+`cleo session start` binds the calling agent process (`CLAUDE_CODE_SESSION_ID`,
+`CODEX_THREAD_ID`, …), pane (`TMUX_PANE`, …) or tab (`TERM_SESSION_ID`, …). Session
+mutations from an unbound caller fail with `E_SESSION_UNBOUND` instead of
+guessing the newest session; bind with `cleo session start`, `cleo session resume
+<id>` or `CLEO_SESSION_ID=<id>`, or name the target with `--session <id>`. CI and
+multi-step scripts must export `CLEO_SESSION_ID`. Unattributed mutations warn on
+stderr; `session status` / `briefing` label a guessed session `unbound: true`.
+
+- A session a human started in a tab is adopted by Claude Code in that tab
+  (also after a Claude restart). An adopter works in it but cannot end it without
+  `--session <id>`, and starting its own session never takes over the tab. A
+  session Claude started can be ended from the tab.
+- Two Claude instances that each start a session stay isolated; a sibling tmux
+  pane never sees another pane's session.
+- Agent-tool subagents inherit the parent's `CLAUDE_CODE_SESSION_ID` and act in
+  the parent's session; `cleo orchestrate spawn` gives workers their own.
+
+## Typed decisions (`cleo decide`, T12491)
+
+`decide` answers typed questions (yes/no, choice, score) through a swappable Jev-wire provider and falls back to local heuristics when unconfigured or failing. It needs two settings, an API URL and a key: `printf %s "$KEY" | cleo decide config --url <u> --key-stdin` (optional `--model`; `--clear` removes them). The key is kept in a 0600 file and never printed. `cleo decide status` probes reachability and `cleo decide ask --state <text> --noul <q>` runs one debug question.
+
 ## Quick Reference
 
 | Need | Command |
 |------|---------|
 | Start session | `cleo session status` → `cleo briefing` |
+| End session (from another terminal) | `cleo session end --session <id>` |
 | Find work | `cleo next` → `cleo focus <id>` |
 | Search tasks | `cleo find "query"` |
 | Complete task | `cleo verify T### --gate ... --evidence "..."` → `cleo complete T###` |
@@ -161,7 +229,18 @@ This internal budget contract does not add a `--token-budget` flag to add/update
 
 ## Skill-Specific Extensions
 
-- Task hierarchy, Saga commands, add-batch decomposition, docs policy, and CLI output details live in CLEO-INJECTION.md; emit `task-creation`, `documents`, and `pre-complete-gate` when needed.
+### Reference files
+
+| File | Load it when you |
+|------|------------------|
+| `references/session-protocol.md` | start, resume or end sessions; pick skills |
+| `references/orchestrator-constraints.md` | spawn subagents from an orchestrator |
+| `references/loom-lifecycle.md` | move an epic through the LOOM stages |
+| `references/anti-patterns.md` | check a plan against known mistakes |
+| `references/memory.md` | recall or record BRAIN memory (progressive disclosure) |
+| `references/sticky-notes.md` | capture a thought before it is a task: `cleo sticky jot "..."`, then `cleo sticky convert <id> --to-task` |
+
+- Task hierarchy, Saga commands, add-batch decomposition, docs policy, and evidence detail live in the on-demand reference; emit `task-creation`, `documents`, and `evidence` when needed.
 - For add-batch input, The top-level JSON MUST be an array of task objects, not an object wrapper like `{ "tasks": [...] }`.
 - Dry-run count semantics: `/data/count` and `/data/wouldCreate` predict writes; `/data/insertedCount` must be `0` for dry-run.
 - Mutation output paths: use `/data/created/0`, `/data/updated/0`, and `/data/deleted/0`; never parse legacy full records. `--output id` emits affected IDs once in created/updated/deleted order from these canonical arrays.
@@ -326,11 +405,12 @@ and planning document generation (T10634):
 
 Example — dry-run a scaffold before applying:
 ```bash
-# Validate scaffold payload
-cleo workgraph validate --file scaffold.json --dry-run
+# Validate scaffold payload (read-only)
+cleo workgraph validate scaffold.json
 
-# Apply validated scaffold atomically
-cleo workgraph apply --file scaffold.json
+# Preview, then apply the validated scaffold atomically
+cleo workgraph apply scaffold.json --dry-run
+cleo workgraph apply scaffold.json
 ```
 
 ## Task Context (PM-Core V2 — T10629/T10630/T10631)
@@ -364,11 +444,11 @@ cite decisions by durable BRAIN decision IDs.
 
 | Need | Command |
 |------|---------|
-| Store a decision | `cleo memory store --type decision --content "..." --title "..."` |
+| Store a decision | `cleo memory decision-store --decision "..." --rationale "..."` |
 | Search decisions | `cleo memory decision-find --query <term>` |
 | Find by type | `cleo memory find <term> --type decision` |
 | Fetch full record | `cleo memory fetch <decisionId>` |
-| List by epic | `cleo memory decision-find --epic <epicId>` |
+| Find by epic | `cleo memory decision-find "<epicId>"` (no epic filter — query text, then verify `source_table`/`source_rowid`) |
 | Check status | `cleo memory fetch <id>` → check `confirmation_state` field |
 
 **Why BRAIN decisions over markdown ledgers:**
@@ -379,7 +459,8 @@ cite decisions by durable BRAIN decision IDs.
 
 **Migration rule:** When you encounter a decision ONLY in a markdown ledger
 (`.cleo/adrs/`, `.cleo/agent-outputs/`), store it in the BRAIN with
-`cleo memory store --type decision` and cite the BRAIN ID going forward.
+`cleo memory decision-store --decision "..." --rationale "..."` and cite the
+BRAIN ID going forward.
 
 ## Evidence must prove task criteria
 

package/skills/ct-cleo/__tests__/injection-content.test.ts

@@ -41,13 +41,55 @@ const injectionPath = resolve(
 /** Read once — all assertions operate on this string */
 const injectionContent = readFileSync(injectionPath, 'utf-8');
 
+/**
+ * T12580: CLEO-INJECTION.md is the always-loaded core; reference sections
+ * moved to CLEO-REFERENCE.md and are printed on demand with
+ * `cleo briefing inject --section <name>`. Content that moved is asserted
+ * where it now lives AND through the core's pointer table, so the test still
+ * proves an agent can reach it.
+ */
+const referenceContent = readFileSync(
+  resolve(thisDir, '../../../../core/templates/CLEO-REFERENCE.md'),
+  'utf-8',
+);
+
+/** Body of one on-demand section in the reference, or '' when absent. */
+function referenceSection(name: string): string {
+  const open = `<!-- CLEO-INJECTION:section=${name} -->`;
+  const start = referenceContent.indexOf(open);
+  if (start === -1) return '';
+  const end = referenceContent.indexOf(`<!-- /CLEO-INJECTION:section=${name} -->`, start);
+  return end === -1 ? '' : referenceContent.slice(start + open.length, end);
+}
+
+/** Section names the core's "On-demand reference" table points at (first column). */
+function corePointers(): Set<string> {
+  const table = injectionContent.slice(injectionContent.indexOf('## On-demand reference'));
+  const rows = table.slice(0, table.indexOf('\n## ', 5)).split('\n');
+  return new Set(
+    rows
+      .filter((line) => line.startsWith('| `'))
+      .flatMap((line) => [...(line.split('|')[1] ?? '').matchAll(/`([a-z][a-z0-9-]+)`/g)])
+      .map((m) => m[1] as string),
+  );
+}
+
+/** Assert `name` is pointed at by the core AND declared in the reference; return its body. */
+function onDemand(name: string): string {
+  expect(injectionContent).toContain('cleo briefing inject --section <name>');
+  expect(corePointers()).toContain(name);
+  const body = referenceSection(name);
+  expect(body, `reference section ${name}`).not.toBe('');
+  return body;
+}
+
 // ---------------------------------------------------------------------------
 // Required section markers
 // ---------------------------------------------------------------------------
 
 describe('CLEO-INJECTION.md — required section markers', () => {
-  it('contains "Memory Protocol (JIT)" H2 section', () => {
-    expect(injectionContent).toMatch(/^## Memory Protocol \(JIT\)/m);
+  it('delivers "Memory Protocol (JIT)" on demand (core pointer → reference section)', () => {
+    expect(onDemand('memory-jit')).toMatch(/^## Memory Protocol \(JIT\)/m);
   });
 
   it('contains "Escalation" H2 section', () => {
@@ -63,8 +105,10 @@ describe('CLEO-INJECTION.md — required section markers', () => {
     expect(injectionContent).toMatch(/^## Work Loop/m);
   });
 
-  it('contains "Task Discovery" H2 section', () => {
-    expect(injectionContent).toMatch(/^## Task Discovery/m);
+  it('delivers "Task Discovery" on demand, with the discovery quick form in the core', () => {
+    expect(onDemand('task-discovery')).toMatch(/^## Task Discovery/m);
+    expect(injectionContent).toContain('cleo find "query"');
+    expect(injectionContent).toContain('cleo list --parent <id>');
   });
 });
 
@@ -111,17 +155,22 @@ describe('CLEO-INJECTION.md — command correctness', () => {
     expect(injectionContent).toContain('cleo find');
   });
 
-  it('documents add-batch array input and dry-run count fields', () => {
-    expect(injectionContent).toContain('top-level JSON array of task objects');
-    expect(injectionContent).toContain('/data/wouldCreate');
-    expect(injectionContent).toContain('/data/insertedCount');
+  it('documents add-batch array input and dry-run count fields (task-creation, on demand)', () => {
+    const section = onDemand('task-creation');
+    expect(section).toContain('top-level JSON array of task objects');
+    expect(section).toContain('/data/wouldCreate');
+    expect(section).toContain('/data/insertedCount');
   });
 
-  it('documents docs path policy, strict preflight, and runtime doc kinds', () => {
-    expect(injectionContent).toContain('repo-relative paths');
-    expect(injectionContent).toContain('arbitrary external absolute paths');
-    expect(injectionContent).toContain('cleo docs list-types');
-    expect(injectionContent).toContain('DocKindRegistry');
+  it('documents docs path policy, strict preflight, and runtime doc kinds (documents, on demand)', () => {
+    const section = onDemand('documents');
+    expect(section).toContain('repo-relative paths');
+    expect(section).toContain('arbitrary external absolute paths');
+    expect(section).toContain('cleo docs list-types');
+    expect(section).toContain('DocKindRegistry');
+    // The canonical-doc write/read triggers stay in the core.
+    expect(injectionContent).toContain('cleo docs add --type <kind> --slug <kebab-handle>');
+    expect(injectionContent).toContain('cleo docs fetch <slug>');
   });
 
   it('uses contract-backed mutate field paths', () => {