@crouton-kit/crouter 0.3.20 → 0.3.22

package/dist/commands/node.js

@@ -164,7 +164,14 @@ const nodeNew = defineLeaf({
                 : childFollowUp(parent ?? process.env['CRTR_NODE_ID']),
         };
     },
-    render: (r) => `<spawned name="${r['name']}" id="${r['node_id']}" status="${r['status']}">\n${r['follow_up']}\n</spawned>`,
+    render: (r) => {
+        const win = r['window'] ? ` in window ${r['window']}` : '';
+        const lines = [`Spawned "${r['name']}" (${r['node_id']}) — ${r['status']}${win}.`];
+        if (r['session'])
+            lines.push(`- session: ${r['session']}`);
+        lines.push('', String(r['follow_up']));
+        return lines.join('\n');
+    },
 });
 // ---------------------------------------------------------------------------
 // node list — the active canvas (or a status slice)
@@ -352,9 +359,16 @@ const nodeRecycle = defineLeaf({
         const res = await recycleNode(id, pane);
         return { recycled: res.recycled, node_id: id, finalized: res.finalized, delivered: res.delivered.length, new_root: res.newRoot ?? undefined };
     },
-    render: (r) => r['recycled'] === true
-        ? `<recycled id="${r['node_id']}" finalized="${r['finalized']}" delivered="${r['delivered']}" new_root="${r['new_root'] ?? ''}"/>`
-        : `<recycle-failed id="${r['node_id'] ?? ''}">not in tmux, or no agent in this pane</recycle-failed>`,
+    render: (r) => {
+        if (r['recycled'] !== true)
+            return `Recycle failed for ${r['node_id'] ?? '?'} — not in tmux, or no agent in this pane.`;
+        const lines = [`Recycled the pane — finished ${r['node_id']}.`, `- finalized: ${r['finalized']}`];
+        if (r['finalized'] === true)
+            lines.push(`- delivered: ${r['delivered']}`);
+        if (r['new_root'])
+            lines.push(`- new root: ${r['new_root']}`);
+        return lines.join('\n');
+    },
 });
 // ---------------------------------------------------------------------------
 // node close — close a node + cascade-cancel its exclusive subtree (Alt+C → x)
@@ -398,9 +412,12 @@ const nodeClose = defineLeaf({
         const res = closeNode(id);
         return { closed: true, node_id: res.root, count: res.closed.length, closed_ids: res.closed, spared: res.spared };
     },
-    render: (r) => r['closed'] === true
-        ? `<closed id="${r['node_id']}" count="${r['count']}" spared="${r['spared']?.length ?? 0}"/>`
-        : `<close-failed/>`,
+    render: (r) => {
+        if (r['closed'] !== true)
+            return 'Close failed — no node found in this pane to close.';
+        const spared = r['spared']?.length ?? 0;
+        return `Closed ${r['node_id']} and its exclusive subtree — ${r['count']} node(s) closed${spared > 0 ? `, ${spared} spared (still managed from outside the subtree)` : ''}.`;
+    },
 });
 // ---------------------------------------------------------------------------
 // node cycle — DFS-walk the canvas one window at a time (Alt+] / Alt+[)
@@ -486,8 +503,8 @@ const nodeCycle = defineLeaf({
         return { focused: res.focused, node_id: targetId, name: target.name, from: fromId };
     },
     render: (r) => r['focused'] === true
-        ? `<cycled to="${r['node_id']}" name="${r['name'] ?? ''}" from="${r['from'] ?? ''}"/>`
-        : `<cycle-noop>no other live node to focus</cycle-noop>`,
+        ? `Cycled to "${r['name'] ?? ''}" (${r['node_id']}) — from ${r['from'] ?? '?'}.`
+        : 'No other live node to focus.',
 });
 // ---------------------------------------------------------------------------
 // node msg — direct-address any node at a wake tier (wakes a dormant target)
@@ -582,7 +599,7 @@ const nodeSubscribe = defineLeaf({
         subscribe(subscriber, publisher, !passive);
         return { subscribed: true, subscriber, publisher, mode: passive ? 'passive' : 'active' };
     },
-    render: (r) => `<subscribed subscriber="${r['subscriber']}" publisher="${r['publisher']}" mode="${r['mode']}"/>`,
+    render: (r) => `Subscribed ${r['subscriber']} → ${r['publisher']} (${r['mode']}).`,
 });
 const nodeUnsubscribe = defineLeaf({
     name: 'unsubscribe',
@@ -609,7 +626,7 @@ const nodeUnsubscribe = defineLeaf({
         unsubscribe(subscriber, publisher);
         return { unsubscribed: true, subscriber, publisher };
     },
-    render: (r) => `<unsubscribed subscriber="${r['subscriber']}" publisher="${r['publisher']}"/>`,
+    render: (r) => `Unsubscribed ${r['subscriber']} from ${r['publisher']}.`,
 });
 // ---------------------------------------------------------------------------
 // node promote — become an orchestrator (the worker→orchestrator polymorph)
@@ -728,7 +745,7 @@ const nodeDemote = defineLeaf({
         const res = setLifecycle(id, 'terminal', { pane, detach: input['detach'] === true });
         return { node_id: res.node_id, lifecycle: res.lifecycle, detached: res.detached };
     },
-    render: (r) => `<demoted node="${r['node_id']}" lifecycle="${r['lifecycle']}"${r['detached'] === true ? ' detached="true"' : ''}/>`,
+    render: (r) => `Demoted ${r['node_id']} — lifecycle now ${r['lifecycle']} (in place)${r['detached'] === true ? ', relocated to the background crtr session' : ''}.`,
 });
 // ---------------------------------------------------------------------------
 // node lifecycle — flip the lifecycle axis (terminal ↔ resident), independent
@@ -765,7 +782,7 @@ const nodeLifecycle = defineLeaf({
         const res = setLifecycle(id, value, { pane, detach: input['detach'] === true });
         return { node_id: res.node_id, lifecycle: res.lifecycle, detached: res.detached };
     },
-    render: (r) => `<lifecycle node="${r['node_id']}" set="${r['lifecycle']}"${r['detached'] === true ? ' detached="true"' : ''}/>`,
+    render: (r) => `Set ${r['node_id']} lifecycle → ${r['lifecycle']}${r['detached'] === true ? ', relocated to the background crtr session' : ''}.`,
 });
 // ---------------------------------------------------------------------------
 // node yield — refresh: discard context, revive fresh against the roadmap
@@ -908,10 +925,6 @@ function etaHint(fireAt, now) {
         return ` (~${hrs}h)`;
     return ` (~${Math.round(ms / 86_400_000)}d)`;
 }
-/** Escape a value for a rendered XML attribute (list rows carry free-text notes). */
-function xmlAttr(s) {
-    return s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
-}
 // node wake at ---------------------------------------------------------------
 const nodeWakeAt = defineLeaf({
     name: 'at',
@@ -1011,7 +1024,10 @@ const nodeWakeAt = defineLeaf({
                 : `Bare self-alarm armed. You wake in a fresh window at ${fireAt}${eta}. End your turn now to go dormant; do not push final. The wake re-reads your roadmap.`;
         return { id, kind, fires_at: fireAt, recur: cadenceDisplay(recur), target, guidance };
     },
-    render: (r) => `<wake-armed id="${r['id']}" kind="${r['kind']}" fires-at="${r['fires_at']}" recur="${r['recur']}" target="${r['target']}">\n${r['guidance']}\n</wake-armed>`,
+    render: (r) => {
+        const recur = r['recur'] !== 'none' ? `, recurs ${r['recur']}` : '';
+        return `Armed ${r['kind']} wake ${r['id']} — fires ${r['fires_at']}${recur}, target ${r['target']}.\n\n${r['guidance']}`;
+    },
 });
 // node wake until ------------------------------------------------------------
 const nodeWakeUntil = defineLeaf({
@@ -1063,7 +1079,7 @@ const nodeWakeUntil = defineLeaf({
         const guidance = `Deadline armed. You wake on the first inbox message, or at ${w.fireAt}${eta} if none arrives. Now delegate / end your turn to go dormant — whichever fires first cancels the other.`;
         return { id, fires_at: w.fireAt, target: 'self', guidance };
     },
-    render: (r) => `<deadline-armed id="${r['id']}" fires-at="${r['fires_at']}" target="${r['target']}">\n${r['guidance']}\n</deadline-armed>`,
+    render: (r) => `Armed deadline ${r['id']} — fires ${r['fires_at']}, target ${r['target']}.\n\n${r['guidance']}`,
 });
 // node wake spawn -----------------------------------------------------------
 const nodeWakeSpawn = defineLeaf({
@@ -1164,7 +1180,10 @@ const nodeWakeSpawn = defineLeaf({
             : `Deferred spawn armed: a fresh ${kind} node is born at ${fireAt}${eta}. No node exists yet — inspect/cancel via \`crtr node wake list\` / \`crtr node wake cancel ${id}\`. Pick up other work or end your turn.`;
         return { id, kind, fires_at: fireAt, recur: cadenceDisplay(recur), guidance };
     },
-    render: (r) => `<spawn-deferred id="${r['id']}" kind="${r['kind']}" fires-at="${r['fires_at']}" recur="${r['recur']}">\n${r['guidance']}\n</spawn-deferred>`,
+    render: (r) => {
+        const recur = r['recur'] !== 'none' ? `, recurs ${r['recur']}` : '';
+        return `Armed deferred spawn ${r['id']} — a ${r['kind']} node, fires ${r['fires_at']}${recur}.\n\n${r['guidance']}`;
+    },
 });
 // node wake list -------------------------------------------------------------
 const nodeWakeList = defineLeaf({
@@ -1246,10 +1265,13 @@ const nodeWakeList = defineLeaf({
     },
     render: (r) => {
         const wakes = r['wakes'];
-        const rows = wakes.map((w) => `  <wake id="${w['id']}" kind="${w['kind']}" next="${w['next']}" recur="${xmlAttr(String(w['recur']))}" target="${xmlAttr(String(w['target']))}" owner="${xmlAttr(String(w['owner']))}" note="${xmlAttr(String(w['note']))}"/>`);
-        const body = rows.length > 0 ? '\n' + rows.join('\n') + '\n' : '\n';
-        return (`<wakes scope="${xmlAttr(String(r['scope']))}" count="${wakes.length}">${body}</wakes>\n` +
-            '<follow_up>Cancel one with `crtr node wake cancel <id>`. Fired one-shots are gone; a recurrence shows its NEXT fire, not past slots.</follow_up>');
+        const follow = 'Cancel one with `crtr node wake cancel <id>`. Fired one-shots are gone; a recurrence shows its NEXT fire, not past slots.';
+        if (wakes.length === 0)
+            return `No pending wakes in scope ${r['scope']}.\n\n${follow}`;
+        const cell = (v) => String(v).replace(/\|/g, '\\|').replace(/\n/g, ' ');
+        const head = '| id | kind | next | recur | target | owner | note |\n| --- | --- | --- | --- | --- | --- | --- |';
+        const rows = wakes.map((w) => `| ${cell(w['id'])} | ${cell(w['kind'])} | ${cell(w['next'])} | ${cell(w['recur'])} | ${cell(w['target'])} | ${cell(w['owner'])} | ${cell(w['note'])} |`);
+        return `${wakes.length} pending wake(s) in scope ${r['scope']}.\n\n${head}\n${rows.join('\n')}\n\n${follow}`;
     },
 });
 // node wake cancel -----------------------------------------------------------
@@ -1276,7 +1298,7 @@ const nodeWakeCancel = defineLeaf({
         cancelWake(id);
         return { id, was_pending: wasPending };
     },
-    render: (r) => `<wake-canceled id="${r['id']}" was-pending="${r['was_pending']}"/>`,
+    render: (r) => `Canceled wake ${r['id']}${r['was_pending'] === true ? '' : ' (already gone — no-op)'}.`,
 });
 // node wake (branch) ---------------------------------------------------------
 const nodeWake = defineBranch({

package/dist/commands/pkg/bridge.d.ts

@@ -0,0 +1 @@
+export declare const bridgeBranch: import("../../core/command.js").BranchDef;

package/dist/commands/pkg/bridge.js

@@ -0,0 +1,137 @@
+// `crtr pkg bridge` — generate crouter substrate docs from a Claude skills root
+// and file-level reconcile the bridge plugin (design §2). The mapping lives in
+// core/bridge-map.ts (one testable source of truth); the extension shells to
+// this command rather than duplicating the transform.
+import { join, basename, dirname, isAbsolute } from 'node:path';
+import { existsSync, readdirSync } from 'node:fs';
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { usage } from '../../core/errors.js';
+import { userScopeRoot } from '../../core/scope.js';
+import { ensureDir, writeJson, writeText, readText, removePath, walkFiles, } from '../../core/fs-utils.js';
+import { parseFrontmatter, parseFrontmatterGeneric } from '../../core/frontmatter.js';
+import { buildBridgeDoc } from '../../core/bridge-map.js';
+import { PLUGIN_MANIFEST_DIR, PLUGIN_MANIFEST_FILE } from '../../types.js';
+/** Enumerate `<source>/**\/SKILL.md`, stopping recursion at the first SKILL.md
+ *  on any branch — a dir that holds SKILL.md is a skill; its subdirs are assets,
+ *  not nested skills. */
+function enumerateSkillFiles(root) {
+    const out = [];
+    if (!existsSync(root))
+        return out;
+    const stack = [root];
+    while (stack.length) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        const hasSkill = entries.some((e) => e.isFile() && e.name === 'SKILL.md');
+        if (hasSkill) {
+            out.push(join(dir, 'SKILL.md'));
+            continue; // stop descent — deeper dirs are assets
+        }
+        for (const e of entries)
+            if (e.isDirectory())
+                stack.push(join(dir, e.name));
+    }
+    return out;
+}
+const bridgeSync = defineLeaf({
+    name: 'sync',
+    description: 'generate substrate docs from a Claude skills root',
+    whenToUse: 'mirroring a Claude Code skills directory into a crtr bridge plugin: maps each SKILL.md to a substrate memory doc and file-level reconciles the plugin (regenerate, prune stale, preserve hand-authored leaves + INDEX)',
+    help: {
+        name: 'pkg bridge sync',
+        summary: 'mirror a Claude skills root into a crtr bridge plugin (idempotent reconcile)',
+        guide: 'Each <source>/skills/<skillname>/SKILL.md becomes ~/.crouter/plugins/<name>/memory/<skillname>.md, stamped generator:claude-bridge. Stamped leaves whose source skill is gone are pruned; hand-authored leaves and any INDEX.md are never touched.',
+        params: [
+            { kind: 'flag', name: 'source', type: 'path', required: true, constraint: 'Absolute path to a Claude skills root (a dir whose <skillname>/SKILL.md leaves are bridged; recursion stops at the first SKILL.md).' },
+            { kind: 'flag', name: 'name', type: 'string', required: true, constraint: 'Bridge plugin name. Dest plugin dir is ~/.crouter/plugins/<name>/.' },
+            { kind: 'flag', name: 'source-desc', type: 'string', required: false, constraint: 'Optional plugin description written into the generated plugin.json.' },
+        ],
+        output: [
+            { name: 'plugin', type: 'string', required: true, constraint: 'Bridge plugin name.' },
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the bridge plugin directory.' },
+            { name: 'written', type: 'number', required: true, constraint: 'Count of substrate leaves generated from source SKILL.md files.' },
+            { name: 'pruned', type: 'number', required: true, constraint: 'Count of stale generator:claude-bridge leaves deleted (source skill gone).' },
+            { name: 'preserved', type: 'number', required: true, constraint: 'Count of untouched protected leaves (INDEX.md or unstamped hand-authored docs).' },
+        ],
+        outputKind: 'object',
+        effects: ['Writes ~/.crouter/plugins/<name>/.crouter-plugin/plugin.json and memory/*.md. Deletes stale generator:claude-bridge leaves. Never writes or deletes INDEX.md or unstamped docs.'],
+    },
+    run: async (input) => {
+        const source = input['source'];
+        const name = input['name'];
+        const sourceDesc = input['sourceDesc'];
+        if (!isAbsolute(source)) {
+            throw usage(`--source must be an absolute path: ${source}`);
+        }
+        if (!existsSync(source)) {
+            throw usage(`--source does not exist: ${source}`);
+        }
+        const destRoot = join(userScopeRoot(), 'plugins', name);
+        const memoryDir = join(destRoot, 'memory');
+        // 1. Ensure the bridge plugin manifest.
+        const manifestDir = join(destRoot, PLUGIN_MANIFEST_DIR);
+        ensureDir(manifestDir);
+        const manifest = {
+            name,
+            version: '0.0.0',
+            ...(sourceDesc !== undefined ? { description: sourceDesc } : {}),
+            source,
+            generator: 'claude-bridge',
+        };
+        writeJson(join(manifestDir, PLUGIN_MANIFEST_FILE), manifest);
+        // 2 + 3. Regenerate one stamped leaf per source skill.
+        ensureDir(memoryDir);
+        const writtenPaths = new Set();
+        for (const file of enumerateSkillFiles(source)) {
+            const skillName = basename(dirname(file));
+            const parsed = parseFrontmatter(readText(file));
+            const doc = buildBridgeDoc({
+                name: parsed.data?.name ?? skillName,
+                description: parsed.data?.description ?? '',
+                body: parsed.body,
+            });
+            const dest = join(memoryDir, `${skillName}.md`);
+            writeText(dest, doc);
+            writtenPaths.add(dest);
+        }
+        const written = writtenPaths.size;
+        // 4. Reconcile: prune stale stamped leaves; never touch INDEX.md or
+        //    unstamped (hand-authored) leaves.
+        let pruned = 0;
+        let preserved = 0;
+        for (const f of walkFiles(memoryDir, (n) => n.endsWith('.md'))) {
+            if (writtenPaths.has(f))
+                continue; // just regenerated → counted in `written`
+            if (basename(f) === 'INDEX.md') {
+                preserved++;
+                continue;
+            }
+            const generator = parseFrontmatterGeneric(readText(f)).data?.['generator'];
+            if (generator === 'claude-bridge') {
+                removePath(f);
+                pruned++;
+            }
+            else {
+                preserved++;
+            }
+        }
+        return { plugin: name, path: destRoot, written, pruned, preserved };
+    },
+});
+export const bridgeBranch = defineBranch({
+    name: 'bridge',
+    description: 'mirror Claude skills into crtr bridge plugins',
+    whenToUse: 'generating a crtr bridge plugin from a Claude Code skills root — the substrate-doc mapping and file-level reconcile invoked by the pi bridge extension',
+    help: {
+        name: 'pkg bridge',
+        summary: 'mirror Claude skills roots into crtr bridge plugins',
+        model: 'A bridge plugin is a generator:claude-bridge plugin whose memory/ docs are generated from a Claude skills root. Hand-authored leaves and INDEX ceilings are preserved across syncs.',
+    },
+    children: [bridgeSync],
+});

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

@@ -1,7 +1,8 @@
 import { defineBranch, defineLeaf } from '../../core/command.js';
 import { notFound } from '../../core/errors.js';
 import { paginate } from '../../core/pagination.js';
-import { listInstalledPlugins, findPluginByName, listSkillsInPlugin, } from '../../core/resolver.js';
+import { listInstalledPlugins, findPluginByName, } from '../../core/resolver.js';
+import { listAllMemoryDocs } from '../../core/memory-resolver.js';
 import { resolveScopeArg, projectScopeRoot } from '../../core/scope.js';
 // ---------------------------------------------------------------------------
 // plugin.inspect.list
@@ -78,8 +79,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',
+    description: 'read plugin manifest and substrate inventory',
+    whenToUse: 'reading one installed plugin in detail to decide before you enable, disable, or remove it — returns the full manifest, the substrate docs it provides (its `<pluginName>/` memory subtree), 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',
@@ -93,7 +94,7 @@ const pluginShow = defineLeaf({
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the plugin directory.' },
             { name: 'enabled', type: 'boolean', required: true, constraint: 'Whether the plugin is active.' },
             { name: 'manifest', type: 'object', required: true, constraint: 'Full plugin.json contents.' },
-            { name: 'skills', type: 'object[]', required: true, constraint: 'Each: {name, path, enabled}. Skills provided by the plugin.' },
+            { name: 'skills', type: 'object[]', required: true, constraint: 'Each: {name, path}. Substrate docs provided by the plugin (its `<pluginName>/` memory subtree).' },
         ],
         outputKind: 'object',
         effects: ['None. Read-only.'],
@@ -117,7 +118,8 @@ const pluginShow = defineLeaf({
         if (found === null) {
             throw notFound(`plugin not found: ${name}`);
         }
-        const skills = listSkillsInPlugin(found);
+        const prefix = `${found.name}/`;
+        const skills = listAllMemoryDocs().filter((d) => d.name.startsWith(prefix));
         return {
             name: found.name,
             scope: found.scope,
@@ -127,7 +129,6 @@ const pluginShow = defineLeaf({
             skills: skills.map((s) => ({
                 name: s.name,
                 path: s.path,
-                enabled: s.enabled,
             })),
         };
     },

package/dist/commands/pkg.js

@@ -4,6 +4,7 @@
 import { defineBranch } from '../core/command.js';
 import { pluginBranch } from './pkg/plugin.js';
 import { marketBranch } from './pkg/market.js';
+import { bridgeBranch } from './pkg/bridge.js';
 export function registerPkg() {
     return defineBranch({
         name: 'pkg',
@@ -16,6 +17,6 @@ export function registerPkg() {
             name: 'pkg',
             summary: 'manage plugins and plugin marketplaces',
         },
-        children: [pluginBranch, marketBranch],
+        children: [pluginBranch, marketBranch, bridgeBranch],
     });
 }

package/dist/commands/push.js

@@ -112,7 +112,7 @@ function makeTierLeaf(tier) {
                 : tier === 'urgent'
                     ? `Urgent report fanned to ${n} subscriber(s) — they are force-woken.`
                     : `Progress report fanned to ${n} subscriber(s).`;
-            return `<pushed tier="${tier}" status="${r['status']}" delivered="${n}">\n${line}\nreport: ${r['report_path']}\n</pushed>`;
+            return `${line}\n\n- report: ${r['report_path']}`;
         },
     });
 }
@@ -161,16 +161,16 @@ const feedReadLeaf = defineLeaf({
         const n = Array.isArray(r['entries']) ? r['entries'].length : 0;
         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>`;
+            return `${n} unread pointer${n === 1 ? '' : 's'} drained from ${r['node_id']}'s inbox.\n\n${rawDigest.trim()}`;
         }
         // 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>`;
+        const explanation = total > 0
+            ? 'Your inbox is not empty, though. 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.'
+            : 'Your inbox is 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 `No unread pointers for ${r['node_id']} (unread=0).\n\n${explanation}`;
     },
 });
 // ---------------------------------------------------------------------------
@@ -249,28 +249,23 @@ const feedPeekLeaf = defineLeaf({
             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>`;
+            return `No nodes below you (0 subscriptions, ${unread} unread). ${tail}`;
         }
         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) => {
@@ -279,10 +274,10 @@ const feedPeekLeaf = defineLeaf({
                 ? `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}`;
+            return `- ${glyph} ${k.name}${sub} (${k.node_id}) \u00b7 ${k.kind} \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>`;
+        const summary = `${kids.length} node${kids.length === 1 ? '' : 's'} below you — ${working.length} working, ${done.length} done, ${dead.length} dead, ${unread} unread:`;
+        return `${line}\n\n${summary}\n${rows}`;
     },
 });
 // ---------------------------------------------------------------------------

package/dist/commands/skill/author.js

@@ -1,14 +1,14 @@
-import { join } from 'node:path';
+import { dirname } from 'node:path';
 import { writeFileSync } from 'node:fs';
 import { defineLeaf, defineBranch } from '../../core/command.js';
 import { usage, general, notFound } from '../../core/errors.js';
-import { SCOPE_SKILL_PLUGIN, SKILL_ENTRY_FILE, SKILLS_DIR, SKILL_TYPES, isSkillType, } from '../../types.js';
+import { SKILL_TYPES, isSkillType } from '../../types.js';
 import { parseSkillQualifier, findPluginByName, } from '../../core/resolver.js';
-import { resolveScopeArg, requireScopeRoot, scopeSkillsDir, } from '../../core/scope.js';
-import { serializeFrontmatter } from '../../core/frontmatter.js';
+import { resolveScopeArg, requireScopeRoot, scopeMemoryDir, pluginMemoryDir, } from '../../core/scope.js';
 import { ensureScopeInitialized } from '../../core/config.js';
 import { ensureDir, pathExists } from '../../core/fs-utils.js';
 import { skillCreatePrompt, skillTemplatePrompt } from '../../prompts/skill.js';
+import { memoryFilePath, serializeMemoryDoc } from '../memory/shared.js';
 import { VALID_TYPES, resolveWriteScope } from './shared.js';
 export const authorGuide = defineLeaf({
     name: 'guide',
@@ -42,25 +42,25 @@ 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.',
+    description: 'create an empty skill substrate doc stub',
+    whenToUse: 'creating the empty `kind: skill` substrate doc at a `<plugin>/<skill>` qualifier (or a bare `<skill>` name for a scope-owned doc) 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',
+        summary: 'create an empty kind:skill substrate doc stub at the given qualifier',
         params: [
-            { kind: 'positional', name: 'qualifier', required: true, constraint: 'Skill identifier in <plugin>/<skill> form.' },
-            { kind: 'flag', name: 'type', type: 'enum', choices: [...VALID_TYPES], required: false, constraint: 'One of: playbook, primer, reference, runbook, freeform.' },
-            { kind: 'flag', name: 'description', type: 'string', required: false, constraint: 'Short description written to frontmatter.' },
+            { kind: 'positional', name: 'qualifier', required: true, constraint: 'Skill identifier: <plugin>/<skill> to scaffold into a plugin\'s memory/, or a bare <skill> for the scope-owned memory/.' },
+            { kind: 'flag', name: 'type', type: 'enum', choices: [...VALID_TYPES], required: false, constraint: 'One of: playbook, primer, reference, runbook, freeform. Drives the follow-up authoring guide only — not stored on the substrate doc.' },
+            { kind: 'flag', name: 'description', type: 'string', required: false, constraint: 'Read-routing line written to the doc\'s when-and-why-to-read frontmatter.' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Default: project if available, else user.' },
         ],
         output: [
-            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the scaffolded SKILL.md.' },
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the scaffolded substrate doc.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Recommended next call to load the authoring guide.' },
         ],
         outputKind: 'object',
         effects: [
-            'Creates the skill directory and SKILL.md stub at the resolved location.',
-            'Writes frontmatter with name, description (if provided), and type (if provided).',
+            'Creates a `kind: skill` substrate doc stub under the resolved memory/ dir (scope-owned, or the named plugin\'s).',
+            'Writes substrate frontmatter: kind:skill, when-and-why-to-read (from --description if given), system-prompt-visibility:name, file-read-visibility:none.',
         ],
     },
     run: async (input) => {
@@ -82,31 +82,20 @@ export const authorScaffold = defineLeaf({
             throw usage(`unknown skill type: ${typeStr} / valid: ${SKILL_TYPES.join(' | ')}`);
         }
         const skillType = typeStr !== undefined && isSkillType(typeStr) ? typeStr : undefined;
-        let skillFile;
-        // Scope-direct: no plugin qualifier, or explicit `_/` sentinel (internal only)
-        if (pluginName === undefined || pluginName === SCOPE_SKILL_PLUGIN) {
+        // Resolve the memory/ dir to scaffold into: the named plugin's, or the
+        // scope-owned one. One substrate, one author path.
+        let memoryDir;
+        if (pluginName === undefined) {
             const scope = resolveWriteScope(scopeStr);
             const scopeRootPath = requireScopeRoot(scope);
             ensureScopeInitialized(scope, scopeRootPath);
-            const skillsRoot = scopeSkillsDir(scope);
-            if (!skillsRoot) {
-                throw general(`no skills dir for scope ${scope}`);
+            const dir = scopeMemoryDir(scope);
+            if (!dir) {
+                throw general(`no memory dir for scope ${scope}`);
             }
-            const skillDir = join(skillsRoot, ...skillName.split('/'));
-            skillFile = join(skillDir, SKILL_ENTRY_FILE);
-            if (pathExists(skillFile)) {
-                throw general(`skill already exists: ${skillFile}`);
-            }
-            ensureDir(skillDir);
-            const fm = serializeFrontmatter({
-                name: skillName,
-                description,
-                type: skillType,
-            });
-            writeFileSync(skillFile, fm, 'utf8');
+            memoryDir = dir;
         }
         else {
-            // Plugin-scoped scaffold
             const scopeForLookup = scopeStr !== undefined
                 ? (() => {
                     const r = resolveScopeArg(scopeStr);
@@ -119,19 +108,21 @@ export const authorScaffold = defineLeaf({
             if (!plugin) {
                 throw notFound(`plugin not found: ${pluginName}`);
             }
-            const skillDir = join(plugin.root, SKILLS_DIR, ...skillName.split('/'));
-            skillFile = join(skillDir, SKILL_ENTRY_FILE);
-            if (pathExists(skillFile)) {
-                throw general(`skill already exists: ${skillFile}`);
-            }
-            ensureDir(skillDir);
-            const fm = serializeFrontmatter({
-                name: skillName,
-                description,
-                type: skillType,
-            });
-            writeFileSync(skillFile, fm, 'utf8');
+            memoryDir = pluginMemoryDir(plugin);
+        }
+        const skillFile = memoryFilePath(memoryDir, skillName);
+        if (pathExists(skillFile)) {
+            throw general(`skill already exists: ${skillFile}`);
         }
+        ensureDir(dirname(skillFile));
+        // Catalog-default substrate frontmatter (design §1.5): a name-rung,
+        // file-read-none skill doc. --description becomes the read-routing line.
+        const frontmatter = { kind: 'skill' };
+        if (description !== undefined)
+            frontmatter['when-and-why-to-read'] = description;
+        frontmatter['system-prompt-visibility'] = 'name';
+        frontmatter['file-read-visibility'] = 'none';
+        writeFileSync(skillFile, serializeMemoryDoc(frontmatter, ''), 'utf8');
         const typeHint = skillType !== undefined ? `--type ${skillType} ` : '';
         const follow_up = `crtr skill author guide ${typeHint}--topic "${skillName}"`;
         return { path: skillFile, follow_up };

package/dist/commands/skill/shared.d.ts

@@ -1,8 +1,4 @@
-import type { Skill, Scope } from '../../types.js';
-export declare function formatNeighborQualifier(s: Skill): string;
-export declare function formatNeighborKeywords(s: Skill): string;
-export declare function buildNeighborsSection(skill: Skill): string | null;
-export declare function appendNeighbors(skill: Skill, body: string): string;
+import type { Scope } from '../../types.js';
 export declare function resolveWriteScope(scopeStr: string | undefined): Scope;
 export declare const VALID_TYPES: readonly ["playbook", "primer", "reference", "runbook", "freeform"];
 export type CatalogSource = {