@mindfoldhq/trellis 0.6.0-rc.0 → 0.6.0

package/dist/migrations/manifests/0.6.0.json

@@ -0,0 +1 @@
+{"version": "0.6.0", "description": "v0.6.0 stable — multi-agent channel runtime, `trellis mem`, `@mindfoldhq/trellis-core` SDK extraction, 15-platform coverage (incl. Reasonix + Pi). Stable promotion of rc.0 with no new src/ changes.", "breaking": false, "recommendMigrate": true, "changelog": "**v0.6.0 stable.** Stable promotion of rc.0 — no new src/ changes since rc.0.\n\n**Heads-up:** Trellis now ships a multi-agent channel runtime (`trellis channel`) and a memory subsystem (`trellis mem`). Both are auto-discovered via bundled skills; the single-agent workflow from 0.5 still works unchanged.\n\nCycle headlines since 0.5.0:\n\n**Channel runtime**\n- `trellis channel`: durable thread / forum channels, project/global scope, linked context, idempotent writes (`idempotencyKey`).\n- Worker lifecycle: `spawn` / `kill` / `prune` / `wait` / `run` with turn-event recording.\n- OOM guard ON by default: `idle_timeout 5m`, `max_live_workers 6` per scope; tunable via `.trellis/config.yaml` or `--idle-timeout` / `--max-live-workers`.\n- Bundled `.trellis/agents/{check,implement}.md` ship at `init` / `update` so `channel spawn --agent` works out of the box (#323).\n\n**Memory**\n- `trellis mem` reads local Claude Code / Codex sessions. Five subcommands: `projects` / `list` / `search` / `context` / `extract`.\n- `--phase brainstorm|implement|all` slices at `task.py create` / `task.py start` boundaries.\n- Library API: `@mindfoldhq/trellis-core/mem`. OpenCode 1.2+ reader degraded (see notes).\n\n**SDK extraction**\n- `@mindfoldhq/trellis-core` is now its own npm package, published in lockstep with the CLI. Subpath exports: `/channel`, `/task`, `/testing`, `/mem`.\n- v0.6.0 is the first GA shipping both packages simultaneously; `bump-versions.js` rewrites `workspace:*` → exact version at release.\n\n**Platform coverage**\n- 15 platforms total. **New: Reasonix** (DeepSeek-Reasonix) and **matured Pi Agent** native extension with `trellis_subagent` tool + project-level override.\n- Codex dispatch defaults to `inline` (was `sub-agent`); no longer writes `[features.multi_agent_v2]` to `.codex/config.toml` (fixes config-load abort on Codex CLI ≤ 0.130).\n- OpenCode `TRELLIS_CONTEXT_ID` picks shell dialect (PowerShell / Git Bash / POSIX).\n- Cursor `sessionStart` emits `additional_context` per Cursor schema; GitHub Copilot SessionStart uses `hookSpecificOutput.additionalContext`.\n\n**Workflow + planning**\n- Task triage consent: no-task turns classify the request and ask before creating a task.\n- Three planning artifacts: `prd.md` / `design.md` / `implement.md`. Parent / child task trees supported.\n- Workflow templates via `trellis init --workflow` and `trellis workflow`. Built-ins: `native`, `tdd`, `channel-driven-subagent-dispatch`.\n\n**Updater**\n- `trellis upgrade` first-class command: channel-aware defaults, `--tag`, `--dry-run`; hardened for Windows.\n- `trellis update` refreshes registry-backed `.trellis/spec` (supports direct + marketplace registries, SSH, self-hosted Git; #324).\n- Configurable hooks via `.trellis/config.yaml`: session commit / journal limits, `hooks.after_*`, `channel.worker_guard.*`, `codex.dispatch_mode`.\n\n**Bundled skills**\n- `trellis-spec-bootstrap` (renamed from typoed `trellis-spec-bootstarp`, #296): bootstraps `.trellis/spec/` from the real codebase.\n- `trellis-session-insight` (new): when to reach for `trellis mem` for cross-session recall.\n- `trellis-channel` (new in GA cycle): when to reach for `trellis channel` for multi-agent collaboration, forum/thread boards, dispatcher-wait patterns.\n- `trellis-meta` (refreshed for v0.6): SKILL.md preamble + new references (`multi-agent-channel.md`, `bundled-skills.md`) cover channel runtime, mem, dual-package SDK, parent/child tasks, workflow templates, registry-backed spec, configurable hooks, Reasonix + Pi platforms, bundled-skill auto-dispatch flow.\n\n**Migration & update flow**\n- `0.6.0-beta.0` is the load-bearing breaking manifest for 0.5.x → 0.6.0 (rename / delete chain documented in its own `migrationGuide`).\n- `0.6.0-beta.23` ships a `rename-dir` migration: `trellis-spec-bootstarp/` → `trellis-spec-bootstrap/` across 13 platform skill roots. Missing roots silently skip.\n- This `0.6.0.json` carries `migrations: []` (GA = rc.0). `recommendMigrate: true` still fires the `--migrate` guidance for users coming directly from 0.5.x.\n\n**Bug fixes (cut window)**\n- fix(agents): drop explicit `mcp__exa__*` tools from bundled `trellis-implement` / `trellis-check` defs. Claude Code silently skipped agent registration when an explicit MCP tool failed to resolve; users without Exa MCP installed lost every Trellis sub-agent. `trellis-research` keeps external search via `mcp__*` wildcard. OpenCode files unchanged (different permission syntax). (#302, rc.0)\n- Earlier 0.6 beta-line bug fixes are documented in their per-beta changelogs.\n\n**Out of scope at GA**\n- OpenCode 1.2+ `trellis mem` reader remains degraded; permanent rework deferred past 0.6.0.\n- Open feature requests (#193, #318, #320, #325, #326) deferred to 0.7+.", "migrations": [], "notes": "**Stable release.** Promoted from 0.6.0-rc.0 with no new src/ changes since.\n\n**Users on 0.5.x** (e.g. `0.5.19`, the last 0.5 stable): run `trellis update --migrate`. The `--migrate` flag is REQUIRED — the breaking-change gate from `0.6.0-beta.0` fires when traversing the migration chain, and a separate `rename-dir` migration from `0.6.0-beta.23` renames the bundled `trellis-spec-bootstarp/` skill directory to `trellis-spec-bootstrap/` across every configured platform skill root (missing roots silently skip).\n\n**Users on any 0.6.0 prerelease** (`beta.X` / `rc.0`): plain `trellis update` is a clean version bump — no `--migrate` needed because you already absorbed the breaking manifest when you adopted the beta line.\n\n**Codex users**: the v0.6 cycle flipped `codex.dispatch_mode` default from `sub-agent` to `inline`. If you previously uncommented `dispatch_mode: sub-agent` in `.trellis/config.yaml`, that opt-in still routes to the legacy sub-agent dispatch flow; if you left the line commented (the default), behavior is now inline. `trellis init` / `update` no longer write a `[features.multi_agent_v2]` block to `.codex/config.toml`, so Codex CLI ≤ 0.130 (including the desktop app's bundled CLI) no longer aborts on config load.\n\n**Channel runtime is opt-in.** The single-agent workflow you know from 0.5 still works unchanged. `trellis channel` and the bundled `trellis-session-insight` skill are auto-discovered but only fire when the AI decides the task calls for them.\n\n**OpenCode users**: `trellis mem` returns empty on OpenCode 1.2+ in this build — the SQLite reader was reverted at `0.6.0-beta.4` due to native-dependency install failures on Windows. A re-enable is planned post-0.6.0.\n\nInstall: `npm install -g @mindfoldhq/trellis`"}

package/dist/templates/common/bundled-skills/trellis-channel/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: trellis-channel
+description: Use Trellis channel for live multi-agent collaboration, spawned workers, cross-agent review, progress inspection, forum channels, and channel log debugging.
+---
+
+# trellis-channel
+
+`trellis channel` is the local multi-agent collaboration runtime. Reach for it when agents need to talk through a durable event log, when a worker should be spawned as a peer process, when an in-flight worker needs interrupt / debugging, or when feedback should be recorded on a durable `--type forum` channel.
+
+Typical user signals: "和 codex/claude 讨论", "brainstorm with another agent", "spawn an implement/check worker", "let agent review", "open an issue board / changelog forum", "look at this thread", "channel is stuck / no output", "progress was truncated", "how do I write that channel command".
+
+This skill is an index. Load only the reference file for the current job — do not preload all of them.
+
+## First Commands
+
+```bash
+trellis --version
+trellis channel --help
+trellis channel list --all
+trellis channel list --scope global --all
+```
+
+If the user names a channel or thread, inspect it before asking for background:
+
+```bash
+trellis channel forum <board> --scope global
+trellis channel thread <board> <thread> --scope global
+trellis channel context list <board> --scope global --thread <thread>
+```
+
+## Route By User Intent
+
+| User intent | Read |
+|---|---|
+| "和 codex/claude 讨论一下", "brainstorm with another agent" | `references/workflows.md` |
+| "派一个 implement/check agent", "让 agent review", "spawn a worker" | `references/workflows.md`, then `references/workers.md` |
+| "开 issue 区 / topic 群 / changelog / board", "make a forum" | `references/forum.md` |
+| "看看这个 thread / linked context", "inspect a thread" | `references/forum.md` |
+| "channel 卡住了 / 没输出 / progress 被截断", "worker stalled" | `references/progress-debugging.md` |
+| "具体命令怎么写", "what flags does X take" | `references/command-reference.md` |
+
+## Core Rules
+
+- New forum channels use `--type forum`. A `thread` is one item inside a forum channel.
+- Use `--context-file` / `--context-raw` and `trellis channel context add/delete/list`. `--linked-context-*` is deprecated terminology.
+- Use `--stdin` or `--text-file` for long messages. Do not put long mixed Chinese/English text in the positional shell argument.
+- Pretty `messages` output is an operator dashboard and may truncate progress. Use `--raw` for audit.
+- `--as` is the speaker or worker handle, depending on the command. Use explicit, stable names when multiple agents or sessions are involved.
+- `--scope project` (default) operates on the current cwd's project bucket; `--scope global` operates on the shared `__global__` bucket. Pick scope deliberately — a global board is invisible from project listings unless `--scope global` is passed.
+- For brainstorm, do multiple pressure-test rounds. One answer plus one confirmation is review, not brainstorm.
+- **Dispatcher wait pattern**: use `--kind done` / `--kind turn_finished` (trellis-emitted system events), NOT a user `--tag` as the completion signal. CLI help lists `phase_done` / `question` as `--tag` examples but only `interrupt` is a reserved tag with hardcoded trellis behavior; the others are opaque user labels. Relying on a worker to run `send --tag <my_signal>` is unreliable — LLM workers commonly write the tag string into prose instead of running the actual CLI command. See `references/command-reference.md` "tag vs kind".
+- Forum channels are event-sourced. Do not parse `events.jsonl` first; use `forum`, `thread`, `messages --thread`, and `context list`.
+- `@mindfoldhq/trellis-core` owns reusable channel/thread state, event append, seq allocation, context/title projection, reducers, and task helpers. The CLI owns flags, terminal rendering, prompts, worker lifecycle, and process exits.
+
+## Reference Files
+
+- `references/workflows.md` — canonical collaboration patterns A–F (peer brainstorm, spawned review, dispatch-and-wait, forum issue capture, interrupt-and-redirect, one-shot run).
+- `references/forum.md` — forum channels, context, title, rename, changelog forums, thread filtering.
+- `references/workers.md` — spawn, agent cards, context injection (`--file` / `--jsonl`), interrupts, kill semantics.
+- `references/progress-debugging.md` — progress/raw inspection, stalled worker diagnosis, OOM guard, exit codes.
+- `references/command-reference.md` — current CLI command reference (every subcommand, every flag, output conventions, scope/type model).
+
+## Not For
+
+- One static review where a markdown file and prompt are enough.
+- Replacing normal tool calls with self-logging.
+- Long-term memory retrieval. Use durable forum channels for actionable issues, and `trellis mem` (the `trellis-session-insight` skill) for session/history search.

package/dist/templates/common/bundled-skills/trellis-channel/references/command-reference.md

@@ -0,0 +1,480 @@
+# Command Reference
+
+Authoritative current command reference for `trellis channel` subcommands,
+validated against the source in `packages/cli/src/commands/channel/`
+(`index.ts` Commander wiring and each subcommand handler).
+
+Every subcommand accepts `--scope <project|global>` unless noted; `project`
+is the default and resolves against the current cwd's project bucket.
+
+## Top-level
+
+```
+trellis channel <subcommand>
+```
+
+> Multi-agent collaboration runtime — spawn / coordinate / interrupt worker
+> agents through a shared event log.
+
+---
+
+## Create / List
+
+### `create <name>`
+
+```bash
+trellis channel create <name>
+  [--scope project|global]                # default: project
+  [--type chat|forum]                     # default: chat
+  [--task <path>]                         # associated Trellis task dir
+  [--project <slug>]
+  [--labels a,b,c]
+  [--description <text>]                  # stable channel description
+  [--context-file <abs-path>] ...         # repeatable
+  [--context-raw  <text>]      ...        # repeatable
+  [--linked-context-file <abs-path>]      # [deprecated alias]
+  [--linked-context-raw  <text>]          # [deprecated alias]
+  [--cwd <path>]                          # recorded in create event
+  [--by <agent>]                          # default: main
+  [--force]                               # overwrite existing channel
+  [--ephemeral]                           # hide from default list, prunable
+```
+
+Behavior:
+- Appends a `create` event; immutable `type` (cannot mutate forum↔chat after).
+- `--ephemeral` channels are hidden from `channel list` by default and are
+  the sweep target for `channel prune --ephemeral`.
+- `--linked-context-*` are folded into `--context-*`; emit a deprecation
+  notice when used.
+
+### `list`
+
+```bash
+trellis channel list
+  [--scope project|global]
+  [--json]
+  [--project <slug>]                      # substring match on task field
+  [--all]                                 # include ephemeral (suffix '*')
+  [--all-projects]                        # scan every project bucket
+```
+
+Behavior:
+- Default scope: current cwd's project. `--all-projects` scans every bucket.
+- Pretty mode prints `NAME WORKERS EVENTS LAST KIND TYPE TASK`, sorted by
+  recency, with a footer noting hidden ephemeral count.
+- `--json` switches to a JSON array.
+
+---
+
+## Chat Messages
+
+### `send <name> [text]`
+
+```bash
+trellis channel send <name> [text]
+  --as <agent>                            # REQUIRED — author
+  [--scope project|global]
+  [--to <agents,csv>]                     # default: broadcast
+  [--stdin | --text-file <path>]          # body from stdin or file
+  [--delivery-mode appendOnly|requireKnownWorker|requireRunningWorker]
+```
+
+Behavior:
+- Body precedence: positional `[text]` → `--stdin` → `--text-file`.
+- `--to` with one entry stores a string; multiple stores an array; omitted
+  means broadcast.
+- `--delivery-mode` selects targeted-delivery validation:
+  - `appendOnly` (default-ish — just record),
+  - `requireKnownWorker` (the named target must have a `spawned` event),
+  - `requireRunningWorker` (the worker must currently be live).
+- Prints the appended event as one JSON line on stdout.
+
+> **Note:** `send` has **no** `--tag` and **no** `--kind` flag. See
+> [`tag-vs-kind`](#tag-vs-kind--how-event-shape-is-actually-controlled) below.
+
+### `messages <name>`
+
+```bash
+trellis channel messages <name>
+  [--scope project|global]
+  [--raw]                                 # one JSON event per line
+  [--follow]                              # stream new events
+  [--last <N>]                            # last N matching events
+  [--since <seq>]                         # seq > N
+  [--kind <kind>]                         # one of CHANNEL_EVENT_KINDS
+  [--from <csv>]                          # author filter
+  [--to <target>]                         # routing target filter
+  [--thread <key>]                        # forum-only
+  [--action <thread-action>]              # forum-only
+  [--no-progress]                         # hide progress events
+```
+
+Behavior:
+- Auto-detects forum channels: with no filters it renders the thread board
+  instead of the event stream. `--thread` / `--action` are forum-only and
+  error against chat channels.
+- `--kind` is validated against `CHANNEL_EVENT_KINDS` (single value, not
+  CSV — that's the `wait` side).
+
+### `wait <name>`
+
+```bash
+trellis channel wait <name>
+  --as <agent>                            # REQUIRED — self for filter ctx
+  [--scope project|global]
+  [--timeout <Ns|Nm|Nh|Nms>]              # parsed by parseDuration
+  [--from <a,b>]                          # author CSV
+  [--kind <k1,k2>]                        # CSV, OR semantics
+  [--thread <key>]                        # forum filter
+  [--action <thread-action>]              # forum filter
+  [--to <target>]                         # default: own agent (broadcast + me)
+  [--include-progress]                    # also wake on progress events
+  [--all]                                 # require every --from to match
+```
+
+Behavior:
+- Streams matching events as JSON, one per line.
+- Default `--to` filter is the caller's own agent (broadcast events still
+  match — broadcast + explicit-to-me).
+- `--all` requires `--from` and blocks until every listed agent has produced
+  a matching event.
+- **Timeout exits 124** and prints `timeout: still waiting on ...` to stderr
+  when `--all` was in play.
+
+---
+
+## tag-vs-kind — how event shape is actually controlled
+
+There is **no `--tag` flag** anywhere in the v0.6.0 channel CLI; `--kind` is
+not a legacy alias for any `--tag` flag.
+
+Concrete model in the current source:
+
+- `--kind` is the only event-type filter, and it is constrained to the
+  trellis-emitted whitelist (`CHANNEL_EVENT_KINDS` in
+  `packages/core/src/channel/internal/store/events.ts`):
+  - `create`, `join`, `leave`, `message`, `thread`, `context`, `channel`,
+    `spawned`, `killed`, `respawned`, `progress`, `done`, `error`,
+    `waiting`, `awake`, `undeliverable`, `interrupt_requested`,
+    `turn_started`, `turn_finished`, `interrupted`, `supervisor_warning`
+  - Passing anything else throws
+    `Invalid --kind '<x>'. Must be one of: …`.
+- `--kind` lives on `wait` (CSV, OR semantics) and `messages` (single
+  value). `send` and `run` cannot emit a custom kind — every `send` writes
+  a `message` event.
+- Mid-turn worker abort is **not** a tag. It is the dedicated
+  `channel interrupt` command, which appends an `interrupt_requested` /
+  `interrupted` pair and provider-level interrupts the worker.
+
+Practical rule for dispatchers waiting on workers:
+
+- Use `--kind done,turn_finished` for "worker finished a turn" — these are
+  system events that the supervisor fires automatically. Do not depend on
+  the worker LLM remembering to emit any custom signal.
+- Use `trellis channel interrupt` (the command) only when you actually want
+  mid-turn abort behavior.
+- Do **not** invent user-side tags as completion signals. There is no
+  `--tag` filter; a worker writing a custom string into its final message
+  is just text inside a `message` event and cannot be matched by `wait`.
+
+Long bodies always go through stdin or a file:
+
+```bash
+trellis channel send T --as A --stdin < /tmp/message.md
+trellis channel send T --as A --text-file /tmp/message.md
+```
+
+---
+
+## Interrupt
+
+### `interrupt <name> [text]`
+
+```bash
+trellis channel interrupt <name> [text]
+  --as <agent>                            # REQUIRED — caller
+  --to <agent>                            # REQUIRED — target worker
+  [--scope project|global]
+  [--stdin | --text-file <path>]
+```
+
+Behavior:
+- Appends an `interrupt` event with `reason: "user"` and a replacement
+  instruction body; supervisor performs provider-level interrupt where
+  supported (Claude `/interrupt`, Codex turn cancel).
+- Prints the appended event JSON on stdout.
+
+---
+
+## Workers
+
+### `spawn <name>`
+
+```bash
+trellis channel spawn <name>
+  [--scope project|global]
+  [--agent <agent-name>]                  # loads .trellis/agents/<name>.md
+  [--provider claude|codex]               # overrides agent file
+  [--as <worker-name>]                    # default: agent name
+  [--cwd <path>]
+  [--model <id>]
+  [--resume <id>]                         # session/thread id resume
+  [--timeout <Ns|Nm|Nh>]                  # auto-kill after duration
+  [--warn-before <Ns|Nm|Nh>]              # supervisor_warning lead time
+                                          # default 5m, 0ms disables
+  [--file <path>] ...                     # glob, repeatable; inject content
+  [--jsonl <path>] ...                    # Trellis manifest, repeatable
+  [--by <agent>]                          # spawn-event author
+                                          # default: TRELLIS_CHANNEL_AS env or 'main'
+  [--inbox-policy explicitOnly|broadcastAndExplicit]
+                                          # default explicitOnly
+  [--idle-timeout <Ns|Nm|Nh>]             # OOM-guard idle TTL
+                                          # default 5m, 0 disables
+  [--max-live-workers <n>]                # spawn-time live-worker budget
+                                          # default 6, 0 disables
+```
+
+Behavior:
+- Provider is validated against the adapter registry
+  (`packages/cli/src/commands/channel/adapters/`); current: `claude`,
+  `codex`.
+- Worker stays inbox-idle until the first `send --to <worker>`.
+- Records a `spawned` event with `pid`, `provider`, `agent`, `files`,
+  `manifests`.
+- OOM-guard precedence: CLI flag → env var
+  (`TRELLIS_CHANNEL_WORKER_IDLE_TIMEOUT`,
+  `TRELLIS_CHANNEL_MAX_LIVE_WORKERS`) →
+  `.trellis/config.yaml#channel.worker_guard` → built-in defaults.
+
+### `run [name]`
+
+```bash
+trellis channel run [name?]
+  [--agent <name>]
+  [--provider claude|codex]
+  [--as <worker-name>]
+  [--cwd <path>]
+  [--model <id>]
+  [--file <path>] ...                     # repeatable, glob
+  [--jsonl <path>] ...                    # repeatable
+  [--message <text> | --message-file <path> | --stdin]
+  [--timeout <Ns|Nm|Nh>]                  # default 5m
+```
+
+Behavior:
+- One-shot. Auto-generates `run-<hex>` if `name` omitted.
+- Creates an ephemeral channel (`createMode=run`), spawns a single worker,
+  sends the prompt, waits for `done`, prints the final assistant text to
+  stdout, then removes the channel on success. On failure the channel is
+  kept for inspection and exit code is 1.
+
+> `run` has **no** `--tag` flag. Completion is detected via the `done`
+> event the supervisor emits.
+
+### `kill <name>`
+
+```bash
+trellis channel kill <name>
+  --as <agent>                            # REQUIRED — worker agent name
+  [--scope project|global]
+  [--force]                               # SIGKILL immediately
+```
+
+Behavior:
+- Default path: SIGTERM → 8 s grace → SIGKILL escalation; the CLI writes a
+  `killed` event when SIGKILL was needed so the log stays truthful.
+- Cleans `pid`, `worker-pid`, `config`, `spawnlock` sidecar files; keeps
+  `log`, `session-id`, `thread-id` for forensics / resume.
+
+### `rm <name>`
+
+```bash
+trellis channel rm <name>
+  [--scope project|global]
+```
+
+Behavior:
+- Kills any live workers, then deletes the entire channel directory.
+- Prints `Removed channel '<name>'`.
+
+### `prune`
+
+```bash
+trellis channel prune
+  [--scope project|global]                # omitted: scan every project
+  [--all | --empty | --idle <Ns|Nm|Nh|Nd> | --ephemeral]   # mutually exclusive
+  [--yes]                                 # actually delete (default: dry-run)
+  [--dry-run]                             # default true; redundant with default
+  [--keep <names,csv>]                    # exclusion list
+```
+
+Behavior:
+- Filter flags are mutually exclusive — error otherwise.
+- Default is dry-run; `--yes` flips to real delete.
+- Without `--scope`, scans **every** project bucket (intentional, repo-wide
+  cleanup); with `--scope project|global`, limited to that bucket.
+- Live-worker channels are always skipped regardless of filter.
+- Output: per-candidate line `name  last-ts  (reason)` plus a final summary.
+
+---
+
+## Forum Channels
+
+### `post <name> <action>`
+
+```bash
+trellis channel post <name> <action>
+  --as <agent>                            # REQUIRED
+  [--scope project|global]
+  [--thread <key>]                        # required except action=opened
+  [--title <text>]
+  [--text <text> | --stdin | --text-file <path>]
+  [--description <text>]                  # stable thread description
+  [--status <status>]
+  [--labels a,b]                          # REPLACES thread labels
+  [--assignees a,b]                       # REPLACES assignees
+  [--summary <text>]
+  [--context-file <abs-path>] ...
+  [--context-raw  <text>]      ...
+  [--linked-context-file <abs-path>]      # [deprecated alias]
+  [--linked-context-raw  <text>]          # [deprecated alias]
+```
+
+Behavior:
+- `<action>` is free-form on the CLI surface; conventional values include
+  `opened`, `comment`, `status`, `labels`, `assignees`, `summary`,
+  `processed`.
+- `action=rename` is rejected — use `thread rename` instead.
+- `--labels` / `--assignees` are replace-semantics, not append.
+- Output: appended event JSON on stdout.
+
+### `forum <name>`
+
+```bash
+trellis channel forum <name>
+  [--scope project|global]
+  [--status <status>]
+  [--raw]
+```
+
+Behavior:
+- Lists threads (reduced state). `--status` filters by current thread
+  status. `--raw` prints one JSON per thread.
+
+### `thread <name> <thread>` / `thread rename`
+
+```bash
+trellis channel thread <name> <thread-key>
+  [--scope project|global]
+  [--raw]
+
+trellis channel thread rename <name> <old-thread> <new-thread>
+  --as <agent>                            # REQUIRED
+  [--scope project|global]
+```
+
+Behavior:
+- `thread <name> <key>` shows one thread's timeline:
+  header `<thread> [<status>] <title>`, then description / labels /
+  assignees / summary / timeline lines. `--raw` switches to raw events.
+- `thread rename` is the only mutation; `post --action rename` is rejected.
+
+---
+
+## Context / Title
+
+### `context add` / `context delete` / `context list`
+
+```bash
+trellis channel context add <name>
+  [--as <agent>]                          # default: main
+  [--scope project|global]
+  [--thread <key>]                        # thread-level instead of channel-level
+  [--file <abs-path>] ...                 # repeatable
+  [--raw <text>]      ...                 # repeatable
+                                          # at least one of --file or --raw
+
+trellis channel context delete <name>
+  [--as <agent>]                          # default: main
+  [--scope project|global]
+  [--thread <key>]
+  [--file <abs-path>] ...
+  [--raw <text>]      ...
+
+trellis channel context list <name>
+  [--scope project|global]
+  [--thread <key>]
+  [--raw]                                 # one JSON entry per line
+```
+
+Behavior:
+- `add` / `delete` append a `context` event and print the event JSON.
+- `list` projects current context entries; pretty output is
+  `file <path>` / `raw <truncated text>` lines, `(no context)` when empty.
+
+### `title set <name>` / `title clear <name>`
+
+```bash
+trellis channel title set <name>
+  --title <text>                          # REQUIRED
+  [--as <agent>]                          # default: main
+  [--scope project|global]
+
+trellis channel title clear <name>
+  [--as <agent>]                          # default: main
+  [--scope project|global]
+```
+
+Behavior:
+- Appends a `title` event projecting a stable display title onto the
+  channel. Output: event JSON.
+
+---
+
+## Hidden / Internal
+
+| Command | Purpose |
+|---|---|
+| `channel __supervisor <channel> <worker> <config>` | Forked entry point invoked by `spawn`. Do not invoke directly. |
+| `channel __parse-trace <adapter> <file>` | Dev helper — replays a recorded stream-json / wire trace through the matching adapter and prints the resulting channel events. Adapter is validated against the provider registry. |
+
+---
+
+## Event Model
+
+`CHANNEL_EVENT_KINDS` (whitelist enforced by `parseChannelKind`):
+
+`create`, `join`, `leave`, `message`, `thread`, `context`, `channel`,
+`spawned`, `killed`, `respawned`, `progress`, `done`, `error`, `waiting`,
+`awake`, `undeliverable`, `interrupt_requested`, `turn_started`,
+`turn_finished`, `interrupted`, `supervisor_warning`.
+
+`MEANINGFUL_EVENT_KINDS` (default-visible subset used by `wait` /
+`messages` when no explicit `--kind` is given):
+
+`create`, `join`, `leave`, `message`, `thread`, `context`, `channel`,
+`spawned`, `killed`, `respawned`, `done`, `error`.
+
+Non-meaningful kinds (e.g. `progress`, `waiting`, `awake`,
+`supervisor_warning`, the `turn_*` / `interrupt*` set) still flow through
+the store; opt in via `--kind` or `--include-progress`.
+
+Forum channels are event-sourced; use the CLI reducers
+(`forum`, `thread`, `context list`) for state projection.
+
+---
+
+## Output Conventions
+
+- **Mutations** (`send`, `interrupt`, `post`, `context add/delete`,
+  `title set/clear`, `thread rename`) print the appended event as one JSON
+  line on **stdout**.
+- **Streaming reads** (`wait`, `messages --follow`) print one JSON event
+  per line on stdout.
+- **Pretty reads** (`list`, `messages`, `forum`, `thread`, `context list`)
+  print colored, padded tables / timelines.
+- **`run`** prints only the final assistant text on stdout (so callers can
+  pipe); diagnostic notes go to stderr.
+- **Errors** go through `chalk.red("Error:")` to stderr and `exit 1`.
+- **`wait` timeout** specifically exits **124**.
+