@crouton-kit/crouter 0.3.13 → 0.3.15

package/dist/commands/pkg/market-inspect.js

@@ -8,6 +8,8 @@ import { resolveScopeArg, projectScopeRoot } from '../../core/scope.js';
 // ---------------------------------------------------------------------------
 const marketList = defineLeaf({
     name: 'list',
+    description: 'list registered marketplaces',
+    whenToUse: 'listing which marketplaces are registered, with their git URL, ref, and scope',
     help: {
         name: 'pkg market inspect list',
         summary: 'list registered marketplaces',
@@ -76,6 +78,8 @@ const marketList = defineLeaf({
 // ---------------------------------------------------------------------------
 const marketBrowse = defineLeaf({
     name: 'browse',
+    description: 'list plugins available in a marketplace',
+    whenToUse: 'exploring what a marketplace offers so you can decide before installing — lists every plugin in a marketplace index with its description, keywords, version, and whether it is already installed. Reach for this to pick which plugin to pull, then install it by name with `pkg market manage install`',
     help: {
         name: 'pkg market inspect browse',
         summary: 'list plugins available in a marketplace',
@@ -145,13 +149,11 @@ const marketBrowse = defineLeaf({
 });
 export const marketInspectBranch = defineBranch({
     name: 'inspect',
+    description: 'list or browse marketplaces',
+    whenToUse: 'reading marketplace metadata to decide before you install — list registered marketplaces, or browse the plugins available in one marketplace. Read-only; switch to `pkg market manage` to add a marketplace or install a plugin from it',
     help: {
         name: 'pkg market inspect',
         summary: 'read marketplace metadata without modifying state',
-        children: [
-            { name: 'list', desc: 'list registered marketplaces', useWhen: 'seeing which marketplaces are configured' },
-            { name: 'browse', desc: 'list plugins available in a marketplace', useWhen: 'exploring what a marketplace offers before installing' },
-        ],
     },
     children: [marketList, marketBrowse],
 });

package/dist/commands/pkg/market-manage.js

@@ -14,6 +14,8 @@ import { resolveInstallScope } from './shared.js';
 // ---------------------------------------------------------------------------
 const marketAdd = defineLeaf({
     name: 'add',
+    description: 'add a marketplace by git URL',
+    whenToUse: 'registering a new marketplace by git URL so its plugins become installable by name',
     help: {
         name: 'pkg market manage add',
         summary: 'add a marketplace by git URL',
@@ -74,6 +76,8 @@ const marketAdd = defineLeaf({
 // ---------------------------------------------------------------------------
 const marketRemove = defineLeaf({
     name: 'remove',
+    description: 'remove a marketplace',
+    whenToUse: 'unregistering a marketplace: deletes it and any plugins installed from it',
     help: {
         name: 'pkg market manage remove',
         summary: 'remove a marketplace and its directory',
@@ -148,6 +152,8 @@ const marketRemove = defineLeaf({
 // ---------------------------------------------------------------------------
 const marketUpdate = defineLeaf({
     name: 'update',
+    description: 'pull latest marketplace index',
+    whenToUse: 'refreshing the plugin index of one named marketplace from git, or of all registered marketplaces when no name is given',
     help: {
         name: 'pkg market manage update',
         summary: 'git pull updates for one or all registered marketplaces',
@@ -234,6 +240,8 @@ const marketUpdate = defineLeaf({
 // ---------------------------------------------------------------------------
 const marketInstall = defineLeaf({
     name: 'install',
+    description: 'install a plugin from a marketplace',
+    whenToUse: 'installing a plugin by name from an already-registered marketplace, e.g. `pkg market manage install --marketplace <m> --plugin <p>`',
     help: {
         name: 'pkg market manage install',
         summary: 'install a plugin from an added marketplace by plugin name',
@@ -302,15 +310,11 @@ const marketInstall = defineLeaf({
 });
 export const marketManageBranch = defineBranch({
     name: 'manage',
+    description: 'add, remove, update, install',
+    whenToUse: 'changing marketplace state: add or remove a marketplace, refresh its index, or install a plugin from it',
     help: {
         name: 'pkg market manage',
         summary: 'add, remove, update, or install from marketplaces',
-        children: [
-            { name: 'add', desc: 'add a marketplace by git URL', useWhen: 'registering a new marketplace source' },
-            { name: 'remove', desc: 'remove a marketplace', useWhen: 'unregistering a marketplace' },
-            { name: 'update', desc: 'pull latest marketplace index', useWhen: 'refreshing the marketplace plugin list' },
-            { name: 'install', desc: 'install a plugin from a marketplace', useWhen: 'adding a plugin sourced from a registered marketplace' },
-        ],
     },
     children: [marketAdd, marketRemove, marketUpdate, marketInstall],
 });

package/dist/commands/pkg/market.js

@@ -3,14 +3,12 @@ import { marketManageBranch } from './market-manage.js';
 import { marketInspectBranch } from './market-inspect.js';
 export const marketBranch = defineBranch({
     name: 'market',
+    description: 'manage marketplace sources and install from them',
+    whenToUse: 'using curated plugin collections instead of raw git URLs — register a marketplace, browse its index of plugins, then install them by name. Use `pkg plugin` instead when you already have a specific git URL or local plugin to install directly, or when inspecting and toggling plugins that are already installed',
     help: {
         name: 'pkg market',
         summary: 'manage and browse plugin marketplaces',
         model: 'Marketplaces are git repos containing a .crouter-marketplace/marketplace.json index of plugins.',
-        children: [
-            { name: 'manage', desc: 'add, remove, update, install', useWhen: 'changing marketplace or marketplace-sourced plugin state' },
-            { name: 'inspect', desc: 'list or browse marketplaces', useWhen: 'reading marketplace metadata' },
-        ],
     },
     children: [marketManageBranch, marketInspectBranch],
 });

package/dist/commands/pkg/plugin-inspect.js

@@ -8,6 +8,8 @@ import { resolveScopeArg, projectScopeRoot } from '../../core/scope.js';
 // ---------------------------------------------------------------------------
 const pluginList = defineLeaf({
     name: 'list',
+    description: 'paginated list of installed plugins',
+    whenToUse: 'enumerating which plugins are installed across user and project scope, optionally including disabled ones',
     help: {
         name: 'pkg plugin inspect list',
         summary: 'paginated list of installed plugins',
@@ -76,6 +78,8 @@ const pluginList = defineLeaf({
 // ---------------------------------------------------------------------------
 const pluginShow = defineLeaf({
     name: 'show',
+    description: 'read plugin manifest and skill inventory',
+    whenToUse: 'reading one installed plugin in detail to decide before you enable, disable, or remove it — returns the full manifest, the skills it provides, its scope, and whether it is currently enabled. Use `pkg plugin inspect list` instead to enumerate plugins rather than drill into one',
     help: {
         name: 'pkg plugin inspect show',
         summary: 'read plugin manifest and metadata by name',
@@ -130,13 +134,11 @@ const pluginShow = defineLeaf({
 });
 export const pluginInspectBranch = defineBranch({
     name: 'inspect',
+    description: 'list or show installed plugins',
+    whenToUse: 'reading installed plugin metadata to decide before you change anything — list what is installed, or show the manifest and skills of one plugin. Read-only; switch to `pkg plugin manage` to actually install, enable, disable, or remove',
     help: {
         name: 'pkg plugin inspect',
         summary: 'read plugin metadata without modifying state',
-        children: [
-            { name: 'list', desc: 'paginated list of installed plugins', useWhen: 'enumerating what plugins are installed' },
-            { name: 'show', desc: 'read plugin manifest and skill inventory', useWhen: 'inspecting a specific plugin\'s details' },
-        ],
     },
     children: [pluginList, pluginShow],
 });

package/dist/commands/pkg/plugin-manage.js

@@ -14,6 +14,8 @@ import { isGitUrl, setPluginEnabled, resolveInstallScope } from './shared.js';
 // ---------------------------------------------------------------------------
 const pluginInstall = defineLeaf({
     name: 'install',
+    description: 'install from a git URL',
+    whenToUse: 'installing a plugin directly from a git URL into a scope, e.g. `pkg plugin manage install https://github.com/org/repo`',
     help: {
         name: 'pkg plugin manage install',
         summary: 'install a plugin from a git URL into the given scope',
@@ -86,6 +88,8 @@ const pluginInstall = defineLeaf({
 // ---------------------------------------------------------------------------
 const pluginRemove = defineLeaf({
     name: 'remove',
+    description: 'remove plugin and directory',
+    whenToUse: 'uninstalling a plugin: deletes its directory and removes it from config',
     help: {
         name: 'pkg plugin manage remove',
         summary: 'remove a plugin and its directory from the given scope',
@@ -141,6 +145,8 @@ const pluginRemove = defineLeaf({
 // ---------------------------------------------------------------------------
 const pluginEnable = defineLeaf({
     name: 'enable',
+    description: 'enable a plugin',
+    whenToUse: 'reactivating a plugin that was previously disabled so its skills resolve again',
     help: {
         name: 'pkg plugin manage enable',
         summary: 'enable a plugin in the given scope',
@@ -160,6 +166,8 @@ const pluginEnable = defineLeaf({
 });
 const pluginDisable = defineLeaf({
     name: 'disable',
+    description: 'disable without removing',
+    whenToUse: 'hiding a plugin from resolution without deleting it, so you can re-enable it later',
     help: {
         name: 'pkg plugin manage disable',
         summary: 'disable a plugin (keeps files, hides from resolution)',
@@ -183,6 +191,8 @@ const pluginDisable = defineLeaf({
 // ---------------------------------------------------------------------------
 const pluginUpdate = defineLeaf({
     name: 'update',
+    description: 'pull latest from git',
+    whenToUse: 'pulling the latest git version of one named plugin, or of all installed plugins when no name is given',
     help: {
         name: 'pkg plugin manage update',
         summary: 'git pull updates for one or all installed plugins',
@@ -279,16 +289,11 @@ const pluginUpdate = defineLeaf({
 });
 export const pluginManageBranch = defineBranch({
     name: 'manage',
+    description: 'install, remove, enable, disable, update',
+    whenToUse: 'changing plugin state: install, remove, enable, disable, or update installed plugins',
     help: {
         name: 'pkg plugin manage',
         summary: 'install, remove, enable, disable, or update plugins',
-        children: [
-            { name: 'install', desc: 'install from a git URL', useWhen: 'adding a new plugin' },
-            { name: 'remove', desc: 'remove plugin and directory', useWhen: 'uninstalling a plugin' },
-            { name: 'enable', desc: 'enable a plugin', useWhen: 'activating a disabled plugin' },
-            { name: 'disable', desc: 'disable without removing', useWhen: 'temporarily hiding a plugin' },
-            { name: 'update', desc: 'pull latest from git', useWhen: 'updating a plugin to its latest version' },
-        ],
     },
     children: [pluginInstall, pluginRemove, pluginEnable, pluginDisable, pluginUpdate],
 });

package/dist/commands/pkg/plugin.js

@@ -3,14 +3,12 @@ import { pluginManageBranch } from './plugin-manage.js';
 import { pluginInspectBranch } from './plugin-inspect.js';
 export const pluginBranch = defineBranch({
     name: 'plugin',
+    description: 'install and manage plugins',
+    whenToUse: 'working with individual plugins directly — installing one from a git URL, inspecting or showing what a plugin provides, or enabling, disabling, removing, and updating an installed plugin. Use `pkg market` instead when you want a curated collection: browsing a marketplace index and installing plugins by name from it rather than handling raw git URLs yourself',
     help: {
         name: 'pkg plugin',
         summary: 'install and manage plugins that extend crtr with skills',
         model: 'Plugins are git repos or local directories containing a .crouter-plugin/plugin.json manifest and a skills/ directory.',
-        children: [
-            { name: 'manage', desc: 'install, remove, enable, disable, update', useWhen: 'changing plugin state' },
-            { name: 'inspect', desc: 'list or show installed plugins', useWhen: 'reading plugin metadata' },
-        ],
     },
     children: [pluginManageBranch, pluginInspectBranch],
 });

package/dist/commands/pkg.js

@@ -15,10 +15,6 @@ export function registerPkg() {
         help: {
             name: 'pkg',
             summary: 'manage plugins and plugin marketplaces',
-            children: [
-                { name: 'plugin', desc: 'install and manage plugins', useWhen: 'working with individual plugins directly' },
-                { name: 'market', desc: 'manage marketplace sources and install from them', useWhen: 'using curated plugin collections' },
-            ],
         },
         children: [pluginBranch, marketBranch],
     });

package/dist/commands/push.js

@@ -1,9 +1,10 @@
 // `crtr push` + `crtr feed` — the one verb up the graph, and its read side.
 //
-//   crtr push update [body]   — routine progress (also auto-emitted every stop)
+//   crtr push update [body]   — routine progress to subscribers
 //   crtr push urgent [body]   — force-wake subscribers
 //   crtr push final  [body]   — finish: write result, mark node done, close window
 //   crtr feed read            — drain the caller's (or a named) inbox into a digest
+//   crtr feed peek            — live state of the nodes below you, cursor untouched
 //
 // "push" is THE verb a node uses to talk to its managers; the tier is the
 // subcommand. The caller's node is resolved from CRTR_NODE_ID (injected by the
@@ -12,6 +13,7 @@
 import { defineBranch, defineLeaf } from '../core/command.js';
 import { InputError, readStdinRaw } from '../core/io.js';
 import { push } from '../core/feed/feed.js';
+import { getNode, subscribersOf, subscriptionsOf, fullName } from '../core/canvas/index.js';
 import { readInboxSince, readCursor, writeCursor, coalesce, } from '../core/feed/inbox.js';
 function requireCallerNode() {
     const id = process.env['CRTR_NODE_ID'];
@@ -29,14 +31,24 @@ const TIER_BLURB = {
     urgent: 'force-wake subscribers (inbox tier urgent)',
     final: 'finish: write the canonical result, mark the node done, close its window',
 };
+const TIER_WHENTOUSE = {
+    update: 'you have routine progress worth surfacing to your managers but nothing that needs them to act right now — a checkpoint, a finished sub-step, a status note while you keep working, a heads-up on a decision you made. Fans a lightweight pointer to every subscriber without forcing a wake. Nothing is pushed automatically — your managers see only what you push explicitly, so reach for this whenever you want a progress signal to reach them. Use push urgent instead when a manager must see it immediately, push final when the work is actually done.',
+    urgent: 'something your managers must see and act on immediately — you are blocked and need a decision, you hit an error that derails the plan, a discovery changes the scope, or a child reported something that has to travel further up the chain now. Same report mechanism as push update, but it force-wakes every subscriber instead of waiting for them to drain their feed on their own time. Use push update instead for progress that can wait, push final when you are handing back a finished result rather than raising an alarm.',
+    final: 'the work this node was spawned to do is complete and you are ready to hand back the canonical result — this writes that result, marks the node done, and closes its window, so it is the LAST thing you do here, not a progress note. Any node finishes this way. Use push update or push urgent instead while work is still in flight, and do not reach for this on a node working directly with the user: it has no manager to report up to and would close mid-conversation (the guard blocks it unless you pass --force after the user confirms).',
+};
 function makeTierLeaf(tier) {
     return defineLeaf({
         name: tier,
+        description: TIER_BLURB[tier],
+        whenToUse: TIER_WHENTOUSE[tier],
         help: {
             name: `push ${tier}`,
             summary: TIER_BLURB[tier],
             params: [
-                { kind: 'stdin', name: 'body', required: true, constraint: 'Report body (markdown). Positional or stdin.' },
+                { kind: 'stdin', name: 'body', required: true, constraint: `Report body (markdown). Positional or stdin — use stdin/heredoc for large bodies (\`crtr push ${tier} <<'EOF' … EOF\`).` },
+                ...(tier === 'final'
+                    ? [{ kind: 'flag', name: 'force', type: 'bool', required: false, default: false, constraint: 'Override the guard that blocks `push final` on a human-attended node (a resident with no one to report up to). Only pass this after the user explicitly confirms they want this node finished.' }]
+                    : []),
             ],
             output: [
                 { name: 'report_path', type: 'string', required: true, constraint: 'Path of the written report.' },
@@ -58,6 +70,38 @@ function makeTierLeaf(tier) {
             if (body === '') {
                 throw new InputError({ error: 'missing_body', message: 'no report body', field: 'body', next: 'Pass the body as an argument or on stdin.' });
             }
+            if (tier === 'final') {
+                const node = getNode(nodeId);
+                // A 2nd `push final` in one turn (or finalizing an already dead/canceled
+                // node) is an illegal finalize-from-terminal: the underlying transition()
+                // throws a raw Error that surfaces as an `internal` "crtr bug" on stderr.
+                // Catch it here as a CLEAN user-facing error — the node is simply already
+                // finished, so there is nothing to do.
+                if (node !== null && node.status !== 'active' && node.status !== 'idle') {
+                    throw new InputError({
+                        error: 'already_finalized',
+                        message: `This node is already ${node.status} — \`push final\` finishes a node once and cannot finalize it again.`,
+                        next: 'Nothing to do here: the node is already finished. Do not push again from this node.',
+                    });
+                }
+                // A RESIDENT node with no subscribers is human-driven and has no one to
+                // submit a canonical result to: `push final` fans to subscribers, and a
+                // resident root conversation has none. Finishing it would close its window
+                // mid-conversation. Block that unless the user confirms (--force). Keyed on
+                // lifecycle, NOT subscriber-count alone: a TERMINAL node with no subscribers
+                // was deliberately terminalized to owe a final — it self-completes here
+                // (records the result, reaps) rather than being blocked for lack of a recipient.
+                if (input['force'] !== true) {
+                    const noRecipient = node !== null && node.lifecycle === 'resident' && subscribersOf(nodeId).length === 0;
+                    if (noRecipient) {
+                        throw new InputError({
+                            error: 'no_final_recipient',
+                            message: 'This node is working directly with the user — it has no manager to submit a final result to. `push final` would close its window mid-conversation.',
+                            next: 'You almost certainly do NOT need to finish here — just keep working with the user. If the user has explicitly asked you to finish and close this node, confirm with them first, then rerun with `crtr push final --force "<result>"`.',
+                        });
+                    }
+                }
+            }
             const result = await push(nodeId, { kind: tier, body });
             return { report_path: result.reportPath, delivered_to: result.deliveredTo, status: tier === 'final' ? 'done' : 'active' };
         },
@@ -77,18 +121,21 @@ function makeTierLeaf(tier) {
 // ---------------------------------------------------------------------------
 const feedReadLeaf = defineLeaf({
     name: 'read',
+    description: 'drain unread pointers into a digest',
+    whenToUse: 'you want to PROACTIVELY poll what the nodes you subscribe to — your children and anyone you follow — have reported before the watcher wakes you, draining the unread pointers in your inbox into one coalesced digest. NOTE: when a subscriber push wakes you, that wake message already IS this digest (the watcher drains your inbox to wake you), so don\'t re-run feed read to "open" it — dereference the refs in the digest you already have. Reach for read to poll before the next wake, to inspect a worker inbox via --node, or with --all to re-read the whole history (full message bodies included) after the cursor has advanced.',
     help: {
         name: 'feed read',
         summary: 'drain unread inbox pointers for the caller (or a named node) into a compact digest',
         params: [
             { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node whose inbox to read. Defaults to CRTR_NODE_ID. Use to inspect a worker\'s inbox as an orchestrator.' },
-            { kind: 'flag', name: 'all', type: 'bool', required: false, default: false, constraint: 'Ignore the cursor and return everything from the start.' },
+            { kind: 'flag', name: 'all', type: 'bool', required: false, default: false, constraint: 'Ignore the cursor and return everything from the start — use to re-read history the wake already drained.' },
         ],
         output: [
             { name: 'node_id', type: 'string', required: true, constraint: 'Node whose inbox was read.' },
             { name: 'digest', type: 'string', required: true, constraint: 'Coalesced digest — paste directly into a prompt.' },
             { name: 'entries', type: 'object[]', required: true, constraint: 'Raw InboxEntry objects.' },
             { name: 'cursor', type: 'string', required: true, constraint: 'New cursor ISO written after draining.' },
+            { name: 'inbox_total', type: 'number', required: true, constraint: 'Total entries in the inbox (read + unread). Distinguishes a never-used inbox from one already drained at wake.' },
         ],
         outputKind: 'object',
         effects: ['Advances nodes/<nodeId>/inbox.jsonl.cursor.', 'Read-only on inbox.jsonl itself.'],
@@ -99,6 +146,7 @@ const feedReadLeaf = defineLeaf({
             : requireCallerNode();
         const cursor = input['all'] === true ? undefined : readCursor(nodeId);
         const entries = readInboxSince(nodeId, cursor);
+        const total = readInboxSince(nodeId, undefined).length;
         const newCursor = entries.length > 0 ? entries[entries.length - 1].ts : cursor ?? new Date().toISOString();
         writeCursor(nodeId, newCursor);
         return {
@@ -106,17 +154,138 @@ const feedReadLeaf = defineLeaf({
             digest: coalesce(entries),
             entries: entries,
             cursor: newCursor,
+            inbox_total: total,
         };
     },
     render: (r) => {
         const n = Array.isArray(r['entries']) ? r['entries'].length : 0;
-        const digest = typeof r['digest'] === 'string' && r['digest'].trim() !== ''
-            ? r['digest']
-            : 'Inbox empty — nothing new from your subscriptions.';
+        const rawDigest = typeof r['digest'] === 'string' ? r['digest'] : '';
+        if (n > 0 && rawDigest.trim() !== '') {
+            return `<feed node="${r['node_id']}" unread="${n}">\n${rawDigest}\n</feed>`;
+        }
+        // Empty drain has two distinct causes — say which, honestly. An inbox that
+        // already holds entries was drained when the watcher woke you (the wake
+        // message WAS that digest); a never-used inbox simply has nothing yet.
+        const total = typeof r['inbox_total'] === 'number' ? r['inbox_total'] : 0;
+        const digest = total > 0
+            ? 'Nothing unread — but your inbox is not empty. The watcher drains your inbox to wake you, so the entries you already saw in your wake message are the same ones you would read here; that is why this is empty. Re-read the whole history (full message bodies included) with `crtr feed read --all`, or dereference the refs from the wake digest you already have.'
+            : 'Inbox empty — nothing has arrived from your subscriptions yet. Expected while workers run: a worker that has not pushed yet leaves no pointer, and it will wake you the moment it does. The wake is automatic — just continue your own work or end your turn. (Reach for `crtr feed peek` only if you suspect a worker died, not to confirm a live one.)';
         return `<feed node="${r['node_id']}" unread="${n}">\n${digest}\n</feed>`;
     },
 });
 // ---------------------------------------------------------------------------
+// feed peek — live state of the nodes below you, without draining anything
+// ---------------------------------------------------------------------------
+const STATUS_GLYPH = {
+    active: '●', idle: '○', done: '✓', dead: '✗', canceled: '⊘',
+};
+/** Coarse "Nm ago" age from an ISO timestamp — enough to read staleness at a glance. */
+function fmtAge(iso) {
+    const ms = Date.now() - new Date(iso).getTime();
+    if (!Number.isFinite(ms) || ms < 0)
+        return 'just now';
+    const s = Math.floor(ms / 1000);
+    if (s < 60)
+        return `${s}s ago`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m ago`;
+    const h = Math.floor(m / 60);
+    if (h < 24)
+        return `${h}h ago`;
+    return `${Math.floor(h / 24)}d ago`;
+}
+const feedPeekLeaf = defineLeaf({
+    name: 'peek',
+    description: 'live state of the nodes below you, without draining anything',
+    whenToUse: 'you are about to end a turn and want to confirm your workers are running before you chill — peek shows every node you subscribe to (the workers below you) with its live status (working/idle/done/dead), how long it has run, its cycle count, and whether it has pushed yet, plus a one-line verdict on whether it is safe to yield. Non-destructive: it never advances your inbox cursor, so a later `feed read` still delivers undrained reports. Reach for it exactly when the feed reads empty but you have outstanding children — that empty feed is EXPECTED (a worker that has not pushed yet contributes no inbox pointer); peek confirms those workers are alive and running async so you can stop and wait instead of polling.',
+    help: {
+        name: 'feed peek',
+        summary: 'show the live state of every node you subscribe to (the workers below you) with a yield-or-not verdict; never drains the inbox',
+        params: [
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node whose subscriptions to peek. Defaults to CRTR_NODE_ID. Use to inspect a worker\'s downstream as an orchestrator.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'Node that was peeked.' },
+            { name: 'unread', type: 'number', required: true, constraint: 'Inbox pointers not yet drained by `feed read`.' },
+            { name: 'children', type: 'object[]', required: true, constraint: 'One row per subscription: {node_id, kind, name, status, active, spawned, cycles, last_push}.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: reads canvas.db edges + node metas + inbox.jsonl.', 'Does NOT advance the inbox cursor — peek leaves the feed intact for a later `feed read`.'],
+    },
+    run: async (input) => {
+        const nodeId = typeof input['node'] === 'string' && input['node'].trim() !== ''
+            ? input['node'].trim()
+            : requireCallerNode();
+        // Read the WHOLE inbox to find each child's last push, but with no cursor
+        // write — peek is non-destructive by contract. `unread` is computed from the
+        // persisted cursor so peek can tell you a `feed read` would deliver something.
+        const all = readInboxSince(nodeId, undefined);
+        const unread = readInboxSince(nodeId, readCursor(nodeId)).length;
+        const children = subscriptionsOf(nodeId).map((s) => {
+            const n = getNode(s.node_id);
+            const fromMe = all.filter((e) => e.from === s.node_id);
+            const last = fromMe.length > 0 ? fromMe[fromMe.length - 1] : undefined;
+            return {
+                node_id: s.node_id,
+                kind: n?.kind ?? '?',
+                name: n !== null ? fullName(n) : s.node_id,
+                status: n?.status ?? 'dead',
+                active: s.active,
+                spawned: n?.created ?? s.created,
+                cycles: n?.cycles ?? 0,
+                last_push: last !== undefined
+                    ? { kind: last.kind, ts: last.ts, ref: last.ref ?? null, label: last.label }
+                    : null,
+            };
+        });
+        return { node_id: nodeId, unread, children };
+    },
+    render: (r) => {
+        const id = r['node_id'];
+        const unread = r['unread'] ?? 0;
+        const kids = r['children'] ?? [];
+        if (kids.length === 0) {
+            const tail = unread > 0
+                ? `${unread} unread report${unread === 1 ? '' : 's'} sit in your inbox — run \`crtr feed read\` to absorb ${unread === 1 ? 'it' : 'them'}.`
+                : 'If you spawned workers, they have finished and detached, or you never subscribed. Nothing will wake you.';
+            return `<peek node="${id}" subscriptions="0" unread="${unread}" verdict="empty">\nNo nodes below you. ${tail}\n</peek>`;
+        }
+        const working = kids.filter((k) => k.status === 'active' || k.status === 'idle');
+        const liveWaking = working.filter((k) => k.active); // active sub to a live node = it will wake me
+        const done = kids.filter((k) => k.status === 'done' || k.status === 'canceled');
+        const dead = kids.filter((k) => k.status === 'dead');
+        let verdict;
+        let line;
+        if (dead.length > 0) {
+            verdict = 'attention';
+            line = `\u26a0 ${dead.length} below you ${dead.length === 1 ? 'is' : 'are'} dead and will NOT wake you. Inspect with \`crtr node inspect show <id>\`, then re-delegate or proceed without ${dead.length === 1 ? 'it' : 'them'}.`;
+        }
+        else if (liveWaking.length > 0) {
+            verdict = 'working';
+            line = `Safe to yield \u2014 ${liveWaking.length} worker${liveWaking.length === 1 ? '' : 's'} running async will wake you on the next push. Nothing to do now; end your turn and chill.`;
+        }
+        else if (unread > 0) {
+            verdict = 'ready';
+            line = `Nothing still running, but ${unread} unread report${unread === 1 ? '' : 's'} \u2014 run \`crtr feed read\` to absorb ${unread === 1 ? 'it' : 'them'}, then continue or finish.`;
+        }
+        else {
+            verdict = 'idle';
+            line = 'Everything below you has finished and been drained \u2014 nothing is running. Continue your own work, or `crtr push final` to finish.';
+        }
+        const rows = kids.map((k) => {
+            const sub = k.active ? '' : ' (passive)';
+            const push = k.last_push !== null
+                ? `pushed ${fmtAge(k.last_push.ts)} [${k.last_push.kind}]${k.last_push.ref !== null ? ` ref:${k.last_push.ref}` : ''}`
+                : 'no push yet';
+            const glyph = STATUS_GLYPH[k.status] ?? '?';
+            return `  ${glyph} ${k.node_id}  ${k.kind}  ${k.name}${sub}  \u00b7 ${k.status} \u00b7 spawned ${fmtAge(k.spawned)} \u00b7 cyc ${k.cycles} \u00b7 ${push}`;
+        }).join('\n');
+        const attrs = `node="${id}" subscriptions="${kids.length}" working="${working.length}" done="${done.length}" dead="${dead.length}" unread="${unread}" verdict="${verdict}"`;
+        return `<peek ${attrs}>\n${line}\n\n${rows}\n</peek>`;
+    },
+});
+// ---------------------------------------------------------------------------
 // Registration
 // ---------------------------------------------------------------------------
 export function registerPush() {
@@ -130,12 +299,7 @@ export function registerPush() {
         help: {
             name: 'push',
             summary: 'push a report to your subscribers',
-            model: 'A push writes a markdown report to the node\'s reports/ history and fans a lightweight pointer to every subscriber\'s inbox (not the content — they dereference lazily). The stophook auto-pushes an `update` every stop, so the feed is continuous; you push explicitly for intentional signals. `push final` is how ANY node finishes: write the canonical result, mark done, close the window.',
-            children: [
-                { name: 'update', desc: TIER_BLURB.update, useWhen: 'sharing routine progress explicitly' },
-                { name: 'urgent', desc: TIER_BLURB.urgent, useWhen: 'something your managers must see now' },
-                { name: 'final', desc: TIER_BLURB.final, useWhen: 'the work is done — this finishes the node' },
-            ],
+            model: 'A push writes a markdown report to the node\'s reports/ history and fans a lightweight pointer to every subscriber\'s inbox (not the content — they dereference lazily). Nothing is pushed automatically — the feed contains only what a node pushes explicitly, so push whenever you want a manager to see something. Pipe large bodies via stdin/heredoc (`crtr push <tier> <<\'EOF\' … EOF`). `push final` is how ANY node finishes: write the canonical result, mark done, close the window.',
         },
         children: [makeTierLeaf('update'), makeTierLeaf('urgent'), makeTierLeaf('final')],
     });
@@ -151,9 +315,8 @@ export function registerFeed() {
         help: {
             name: 'feed',
             summary: 'read the per-node inbox feed',
-            model: 'Each node has an inbox.jsonl that accumulates ~30-token pointers from publishers it subscribes to. `feed read` coalesces unread pointers into one digest; dereference the reports that matter by reading their ref paths.',
-            children: [{ name: 'read', desc: 'drain unread pointers into a digest', useWhen: 'checking what your subscriptions pushed' }],
+            model: 'Each node has an inbox.jsonl that accumulates ~30-token pointers from publishers it subscribes to. The watcher drains this inbox to wake you, so the wake message you receive ALREADY IS the coalesced digest \u2014 dereference the reports that matter by reading their ref paths (a push carries a ref; a direct message inlines its full body). `feed read` is for PROACTIVELY polling before a wake (it advances the cursor); after a wake it reads empty because the cursor already moved \u2014 use `--all` to re-read history. An empty feed is normal while workers run \u2014 a worker that has not pushed leaves no pointer \u2014 so use `feed peek` to see the live state of the nodes below you (and whether to yield) without draining anything.',
         },
-        children: [feedReadLeaf],
+        children: [feedReadLeaf, feedPeekLeaf],
     });
 }

package/dist/commands/revive.js

@@ -2,7 +2,7 @@
 //
 // Bypasses the daemon: directly opens a fresh tmux window for a node that is
 // done, idle, or dead. Default behavior resumes the saved pi conversation
-// (--resume); pass --fresh to start a clean pi session against the context dir.
+// (--session <id>); pass --fresh to start a clean pi session against the context dir.
 import { defineLeaf } from '../core/command.js';
 import { InputError } from '../core/io.js';
 import { reviveNode } from '../core/runtime/revive.js';
@@ -12,6 +12,8 @@ import { getNode } from '../core/canvas/index.js';
 // ---------------------------------------------------------------------------
 export const reviveLeaf = defineLeaf({
     name: 'revive',
+    description: 'reopen a window for a done/idle/dead/canceled node',
+    whenToUse: 'you want to bring a dormant node back yourself — reopen a window for one that is done, idle, dead, or canceled: resume a node you closed with `node close`, reopen a finished worker for a follow-up, or restart a crashed one now instead of waiting. Resumes the saved conversation by default; pass `--fresh` to restart clean against its context dir. You rarely need this for crashes — the daemon auto-revives those; reach for it to bring a node back on demand, or to revive a canceled node the daemon will never touch on its own',
     help: {
         name: 'canvas revive',
         summary: 'open a fresh tmux window for a node, optionally resuming its saved pi conversation',
@@ -28,13 +30,13 @@ export const reviveLeaf = defineLeaf({
                 type: 'bool',
                 required: false,
                 default: false,
-                constraint: 'When set, start a clean pi session (no --resume). Default: resume the saved conversation.',
+                constraint: 'When set, start a clean pi session (no --session). Default: resume the saved conversation.',
             },
         ],
         output: [
             { name: 'window', type: 'string', required: false, constraint: 'New tmux window id.' },
             { name: 'session', type: 'string', required: true, constraint: 'Tmux session the node was placed in.' },
-            { name: 'resumed', type: 'boolean', required: true, constraint: 'True when pi was told to --resume the saved conversation.' },
+            { name: 'resumed', type: 'boolean', required: true, constraint: 'True when pi was told to --session the saved conversation.' },
         ],
         outputKind: 'object',
         effects: [

package/dist/commands/skill/author.js

@@ -12,6 +12,8 @@ import { skillCreatePrompt, skillTemplatePrompt } from '../../prompts/skill.js';
 import { VALID_TYPES, resolveWriteScope } from './shared.js';
 export const authorGuide = defineLeaf({
     name: 'guide',
+    description: 'load authoring workflow + skeleton for a type',
+    whenToUse: 'writing a new skill and you want the authoring workflow plus the template skeleton — call it once with no --type for the template picker, then again with --type for the full workflow and skeleton of that type.',
     help: {
         name: 'skill author guide',
         summary: 'load the skill authoring workflow — two stages: omit type to pick one, pass type for its full skeleton',
@@ -40,6 +42,8 @@ export const authorGuide = defineLeaf({
 });
 export const authorScaffold = defineLeaf({
     name: 'scaffold',
+    description: 'create an empty SKILL.md stub',
+    whenToUse: 'creating the empty SKILL.md stub at a `<plugin>/<skill>` qualifier before you fill in content — it writes the frontmatter and file, then points you at the authoring guide.',
     help: {
         name: 'skill author scaffold',
         summary: 'create an empty SKILL.md stub at the given qualifier',
@@ -135,13 +139,11 @@ export const authorScaffold = defineLeaf({
 });
 export const authorBranch = defineBranch({
     name: 'author',
+    description: 'create and scaffold skills',
+    whenToUse: 'you have a reusable workflow, methodology, or hard-won convention worth capturing so future agents adopt it instead of re-deriving it — author carries you from picking a template through scaffolding the file. Reach for it when a task just taught you a repeatable procedure, when the same guidance keeps getting re-explained across sessions, or when the house conventions for a tool deserve to be written down once. Start with `crtr skill author guide` for the template picker and authoring workflow; use `crtr skill author scaffold` to stub the SKILL.md file.',
     help: {
         name: 'skill author',
         summary: 'create and scaffold new skills',
-        children: [
-            { name: 'guide', desc: 'load authoring workflow + skeleton for a type', useWhen: 'writing a new skill and need the template and instructions' },
-            { name: 'scaffold', desc: 'create an empty SKILL.md stub', useWhen: 'initializing the file before writing content' },
-        ],
     },
     children: [authorGuide, authorScaffold],
 });

package/dist/commands/skill/find.js

@@ -8,6 +8,8 @@ import { paginate } from '../../core/pagination.js';
 import { walkFiles, readText } from '../../core/fs-utils.js';
 export const findList = defineLeaf({
     name: 'list',
+    description: 'paginated list of installed skills',
+    whenToUse: 'browse the whole catalog of installed skills, paginated, when you want to see everything that is available rather than hunt for a particular topic — supports --scope, --plugin, and --full filters to narrow or enrich the listing. Use `crtr skill find search` instead when you already have a topic or keyword in mind.',
     help: {
         name: 'skill find list',
         summary: 'paginated list of installed skills',
@@ -92,6 +94,8 @@ export const findList = defineLeaf({
 });
 export const findSearch = defineLeaf({
     name: 'search',
+    description: 'keyword search across name/description/keywords',
+    whenToUse: 'you have a topic, keyword, or problem in mind but not the exact skill name — search ranks installed skills by how well your terms match their name, description, and keywords (add --search-body to also look inside SKILL.md bodies). Reach for it to answer questions like is there a skill for writing tests, anything on prompt design, do we have a debugging workflow. Use `crtr skill find list` instead to browse the whole catalog when you have no particular topic in mind, and `crtr skill find grep` when you need an exact regex or literal-string match across skill bodies rather than a ranked topic match.',
     help: {
         name: 'skill find search',
         summary: 'search skills by name, description, and keywords',
@@ -177,6 +181,8 @@ export const findSearch = defineLeaf({
 });
 export const findGrep = defineLeaf({
     name: 'grep',
+    description: 'regex search across SKILL.md bodies',
+    whenToUse: 'you need to find which skills contain a specific literal string or regex pattern in their SKILL.md body — an exact text match, not a ranked topic search: locating every skill that mentions a command name, a flag, or an exact phrase. Use `crtr skill find search` instead when you want skills matched by topic or keyword rather than exact body text.',
     help: {
         name: 'skill find grep',
         summary: 'search skill file contents for a regex pattern',
@@ -241,14 +247,11 @@ export const findGrep = defineLeaf({
 });
 export const findBranch = defineBranch({
     name: 'find',
+    description: 'list, search, or grep skills',
+    whenToUse: 'you do not yet know which skill applies and need to discover what is installed — list to browse the whole catalog, search to rank skills by topic or keyword, grep to match exact text inside skill bodies.',
     help: {
         name: 'skill find',
         summary: 'discover skills by listing, keyword search, or body grep',
-        children: [
-            { name: 'list', desc: 'paginated list of installed skills', useWhen: 'enumerating all available skills' },
-            { name: 'search', desc: 'keyword search across name/description/keywords', useWhen: 'looking for skills matching a topic' },
-            { name: 'grep', desc: 'regex search across SKILL.md bodies', useWhen: 'finding skills containing specific text or patterns' },
-        ],
     },
     children: [findList, findSearch, findGrep],
 });