@blulotus/trellis 0.7.0

package/dist/templates/codex/index.js

@@ -0,0 +1,67 @@
+/**
+ * Codex templates
+ *
+ * These are GENERIC templates for user projects.
+ * Do NOT use Trellis project's own .agents/skills or .codex directories
+ * (which may be customized).
+ *
+ * Workflow skills are NOT stored here. They come from templates/common/ and are
+ * written to .agents/skills/ as trellis-*, which Codex reads alongside
+ * .codex/skills/ (see configurators/codex.ts).
+ *
+ * Directory structure:
+ *   codex/
+ *   ├── agents/         # Project-scoped Codex custom agents (.toml)
+ *   ├── hooks/          # Codex hook scripts → .codex/hooks/
+ *   ├── hooks.json      # Codex hook wiring → .codex/hooks.json
+ *   └── config.toml     # Project-scoped Codex config
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+function readTemplate(relativePath) {
+    return readFileSync(join(__dirname, relativePath), "utf-8");
+}
+function listFiles(dir) {
+    try {
+        return readdirSync(join(__dirname, dir)).sort();
+    }
+    catch {
+        return [];
+    }
+}
+// Shared skills are now sourced from common/ templates (see templates/common/index.ts)
+export function getAllAgents() {
+    const agents = [];
+    for (const file of listFiles("agents")) {
+        if (!file.endsWith(".toml")) {
+            continue;
+        }
+        const name = file.replace(".toml", "");
+        const content = readTemplate(`agents/${file}`);
+        agents.push({ name, content });
+    }
+    return agents;
+}
+export function getAllHooks() {
+    const hooks = [];
+    for (const file of listFiles("hooks")) {
+        if (!file.endsWith(".py")) {
+            continue;
+        }
+        hooks.push({ name: file, content: readTemplate(`hooks/${file}`) });
+    }
+    return hooks;
+}
+export function getHooksConfig() {
+    return readTemplate("hooks.json");
+}
+export function getConfigTemplate() {
+    return {
+        targetPath: "config.toml",
+        content: readTemplate("config.toml"),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/templates/codex/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/codex/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEtC,SAAS,YAAY,CAAC,YAAoB;IACxC,OAAO,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC;AAC9D,CAAC;AAED,SAAS,SAAS,CAAC,GAAW;IAC5B,IAAI,CAAC;QACH,OAAO,WAAW,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAYD,uFAAuF;AAEvF,MAAM,UAAU,YAAY;IAC1B,MAAM,MAAM,GAAoB,EAAE,CAAC;IAEnC,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;QACvC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5B,SAAS;QACX,CAAC;QAED,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACvC,MAAM,OAAO,GAAG,YAAY,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;QAC/C,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IACjC,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAOD,MAAM,UAAU,WAAW;IACzB,MAAM,KAAK,GAAmB,EAAE,CAAC;IAEjC,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;QACtC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,SAAS;QACX,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,CAAC,SAAS,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,OAAO,YAAY,CAAC,YAAY,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,OAAO;QACL,UAAU,EAAE,aAAa;QACzB,OAAO,EAAE,YAAY,CAAC,aAAa,CAAC;KACrC,CAAC;AACJ,CAAC"}

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`.
+- `@blulotus/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**.
+