@crouton-kit/crouter 0.3.17 → 0.3.19

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

@@ -241,7 +241,7 @@ 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>`',
+    whenToUse: 'installing a plugin by name from a marketplace you have already registered',
     help: {
         name: 'pkg market manage install',
         summary: 'install a plugin from an added marketplace by plugin name',

package/dist/commands/push.js

@@ -59,7 +59,7 @@ function makeTierLeaf(tier) {
             effects: [
                 'Writes nodes/<nodeId>/reports/<ts>-<tier>.md.',
                 'Appends one inbox pointer per subscriber.',
-                ...(tier === 'final' ? ['Marks the node done (status + intent); its window closes on next stop.'] : []),
+                ...(tier === 'final' ? ['Marks the node done (status + intent); its engine shuts down on next stop.'] : []),
             ],
         },
         run: async (input) => {
@@ -86,8 +86,8 @@ function makeTierLeaf(tier) {
                 }
                 // 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
+                // resident root conversation has none. Finishing it would shut its
+                // engine down 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.
@@ -96,7 +96,7 @@ function makeTierLeaf(tier) {
                     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.',
+                            message: 'This node is working directly with the user — it has no manager to submit a final result to. `push final` would end the conversation mid-stream.',
                             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>"`.',
                         });
                     }
@@ -108,7 +108,7 @@ function makeTierLeaf(tier) {
         render: (r) => {
             const n = Array.isArray(r['delivered_to']) ? r['delivered_to'].length : 0;
             const line = tier === 'final'
-                ? 'Result recorded — node finished; its window closes on next stop. Nothing more to do here.'
+                ? 'Result recorded — node finished; its engine shuts down on next stop. Nothing more to do here: STOP your turn immediately. Reply with just "Done." and nothing else.'
                 : tier === 'urgent'
                     ? `Urgent report fanned to ${n} subscriber(s) — they are force-woken.`
                     : `Progress report fanned to ${n} subscriber(s).`;
@@ -122,7 +122,7 @@ 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.',
+    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 it to poll before the next wake, to inspect another node\'s inbox, or to re-read the whole history 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',

package/dist/commands/revive.js

@@ -13,7 +13,7 @@ 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',
+    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. It resumes the saved conversation by default, or can restart the node clean. 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',

package/dist/commands/skill/author.js

@@ -13,7 +13,7 @@ import { VALID_TYPES, resolveWriteScope } from './shared.js';
 export const authorGuide = defineLeaf({
     name: 'guide',
     description: 'load authoring workflow + skeleton for a type',
-    whenToUse: 'REQUIRED reading before you author a new skill OR edit an existing one — it carries the SKILL.md format, the description-drives-discovery rule (when-to-use lives in the frontmatter description, never the body), the voice constraints, and the per-type workflow. Call it once with no --type for the template picker, then again with --type for that type\'s full workflow and skeleton. Editing an existing skill counts: read this first, because the format and voice rules govern every change, not just new files.',
+    whenToUse: 'REQUIRED reading before you author a new skill OR edit an existing one — it carries the SKILL.md format, the description-drives-discovery rule (when-to-use lives in the frontmatter description, never the body), the voice constraints, and the per-type workflow. Editing an existing skill counts: read this first, because the format and voice rules govern every change, not just new files.',
     help: {
         name: 'skill author guide',
         summary: 'load the skill authoring workflow — two stages: omit type to pick one, pass type for its full skeleton',

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

@@ -5,15 +5,8 @@ export declare function buildNeighborsSection(skill: Skill): string | null;
 export declare function appendNeighbors(skill: Skill, body: string): string;
 export declare function resolveWriteScope(scopeStr: string | undefined): Scope;
 export declare const VALID_TYPES: readonly ["playbook", "primer", "reference", "runbook", "freeform"];
-type CatalogSource = {
+export type CatalogSource = {
     plugin: string;
     roots: string[];
 };
-/** The skill subtree's live state: the loaded-skills catalog as a self-named
- *  `<skills count="N">` element. The tag carries the label and the count is an
- *  attribute, so the body is the grouped tree alone — no "Loaded skills (N)"
- *  header to duplicate. Returns null (block omitted) when discovery fails or
- *  nothing is loaded. */
-export declare function buildSkillCatalog(): string | null;
 export declare function renderCatalogSection(label: string, sources: CatalogSource[], descriptions: Map<string, string>, out: string[]): void;
-export {};

package/dist/commands/skill/shared.js

@@ -1,7 +1,6 @@
-import { stateBlock } from '../../core/help.js';
 import { usage } from '../../core/errors.js';
 import { SCOPE_SKILL_PLUGIN } from '../../types.js';
-import { listSkillSiblings, listSkillChildren, listAllSkills, listAllPlugins, } from '../../core/resolver.js';
+import { listSkillSiblings, listSkillChildren, } from '../../core/resolver.js';
 import { resolveScopeArg, projectScopeRoot } from '../../core/scope.js';
 // ---------------------------------------------------------------------------
 // Neighbors section (ported from old impl)
@@ -24,7 +23,7 @@ export function buildNeighborsSection(skill) {
         return null;
     const lines = [
         '## Neighbors',
-        '*Auto-discovered from filesystem. Run `crtr skill read <name>` for full description + body.*',
+        '*Auto-discovered from filesystem. Run `crtr memory read <name>` for full description + body.*',
         '',
     ];
     if (siblings.length > 0) {
@@ -68,58 +67,6 @@ export function resolveWriteScope(scopeStr) {
 // ---------------------------------------------------------------------------
 export const VALID_TYPES = ['playbook', 'primer', 'reference', 'runbook', 'freeform'];
 const CATALOG_T = 5;
-/** The skill subtree's live state: the loaded-skills catalog as a self-named
- *  `<skills count="N">` element. The tag carries the label and the count is an
- *  attribute, so the body is the grouped tree alone — no "Loaded skills (N)"
- *  header to duplicate. Returns null (block omitted) when discovery fails or
- *  nothing is loaded. */
-export function buildSkillCatalog() {
-    let skills;
-    try {
-        skills = listAllSkills().filter((s) => s.enabled);
-    }
-    catch {
-        return null;
-    }
-    if (skills.length === 0)
-        return null;
-    const pluginDescriptions = new Map();
-    for (const p of listAllPlugins()) {
-        if (p.manifest.description)
-            pluginDescriptions.set(p.name, p.manifest.description);
-    }
-    const bySource = new Map();
-    for (const s of skills) {
-        const key = `${s.scope}\t${s.plugin}`;
-        const arr = bySource.get(key);
-        if (arr)
-            arr.push(s);
-        else
-            bySource.set(key, [s]);
-    }
-    const projectSources = [];
-    const userSources = [];
-    for (const [key, group] of bySource) {
-        const [scope, plugin] = key.split('\t');
-        const names = group.map((g) => g.name);
-        const roots = names
-            .filter((n) => !names.some((m) => m !== n && n.startsWith(m + '/')))
-            .sort();
-        if (roots.length === 0)
-            continue;
-        (scope === 'project' ? projectSources : userSources).push({ plugin, roots });
-    }
-    const body = [];
-    renderCatalogSection('Project', projectSources, pluginDescriptions, body);
-    renderCatalogSection('User', userSources, pluginDescriptions, body);
-    // renderCatalogSection leads each section with a blank separator; drop the
-    // leading one so the element body starts on its first real line.
-    while (body.length > 0 && body[0] === '')
-        body.shift();
-    body.push('');
-    body.push("Groups shown as `name/  N skills` are collapsed. Read the group to get its menu before assuming a skill is or isn't there: `crtr skill read <group>` (or `crtr skill find list --plugin <group>`). Search across everything with `crtr skill find search <topic>`.");
-    return stateBlock('skills', { count: skills.length }, body.join('\n'));
-}
 export function renderCatalogSection(label, sources, descriptions, out) {
     if (sources.length === 0)
         return;

package/dist/commands/skill.js

@@ -1,27 +1,22 @@
-// `crtr skill` subtree handlers — P3 implementation.
-// Sub-branches: find {list, search, grep}, author {guide, scaffold}, state {enable, disable}.
-// Leaf children of skill: read.
+// `crtr skill` subtree handlers.
+// Sub-branches: author {guide, scaffold}, state {enable, disable}.
+// Discovery and reading are now `crtr memory` verbs.
 import { defineBranch } from '../core/command.js';
-import { buildSkillCatalog } from './skill/shared.js';
-import { findBranch } from './skill/find.js';
-import { readLeaf } from './skill/read.js';
 import { authorBranch } from './skill/author.js';
 import { stateBranch } from './skill/state.js';
 export function registerSkill() {
     return defineBranch({
         name: 'skill',
         rootEntry: {
-            concept: 'a SKILL.md you read to adopt its workflow',
-            desc: 'find, read, author, and manage skills',
-            useWhen: 'a task matches a loaded skill — read it before improvising. `crtr skill read <name>` loads one by name from the catalog below; `crtr skill find` only when the name is not already listed. Names are crtr identifiers, not file paths — never cat or find SKILL.md off disk.',
-            dynamicState: buildSkillCatalog,
+            concept: 'a SKILL.md you author and manage',
+            desc: 'author and manage skills',
+            useWhen: 'authoring a new skill (`crtr skill author`) or toggling a skill on/off (`crtr skill state`). To discover and read skills use `crtr memory` — `crtr memory read <name>`, `crtr memory find`, `crtr memory list`.',
         },
         help: {
             name: 'skill',
-            summary: 'discover, read, author, and manage skill state',
-            model: '`find` when you do not yet know which skill applies — it locates candidates by topic, keyword, or body text. `read` (leaf) loads SKILL.md by name; takes the name as a positional, returns body + metadata, accepts --no-body to skip the body. `author` when you are writing a new skill — it carries the template workflow and the scaffolder. `state` when a skill should be hidden from discovery without being removed. Append `-h` at any branch or leaf for its full schema.',
-            dynamicState: buildSkillCatalog,
+            summary: 'author and manage skill state — use `crtr memory` to discover and read skills',
+            model: '`author` when you are writing a new skill — it carries the template workflow and the scaffolder. `state` when a skill should be hidden from discovery without being removed. Discovery and reading are `crtr memory` verbs: `crtr memory list`, `crtr memory find`, `crtr memory read`. Append `-h` at any branch or leaf for its full schema.',
         },
-        children: [findBranch, readLeaf, authorBranch, stateBranch],
+        children: [authorBranch, stateBranch],
     });
 }

package/dist/commands/sys/doctor.js

@@ -326,7 +326,7 @@ function runChecksForScope(scope, opts) {
 export const sysDoctorLeaf = defineLeaf({
     name: 'doctor',
     description: 'diagnose installation health',
-    whenToUse: 'something in your crtr install looks off and you want it diagnosed — a plugin or marketplace manifest is missing, a config entry points at a directory that no longer exists, or skill frontmatter has drifted from its filename. Reports each problem with a structured remediation; pass --fix to apply the repairs.',
+    whenToUse: 'something in your crtr install looks off and you want it diagnosed — a plugin or marketplace manifest is missing, a config entry points at a directory that no longer exists, or skill frontmatter has drifted from its filename. Reports each problem with a structured remediation, and can apply the repairs for you.',
     help: {
         name: 'sys doctor',
         summary: 'diagnose missing manifests, broken config entries, and skill frontmatter drift',

package/dist/commands/sys/update.js

@@ -7,7 +7,7 @@ import { readPackageVersion } from './shared.js';
 export const sysUpdateLeaf = defineLeaf({
     name: 'update',
     description: 'update binary and content',
-    whenToUse: 'upgrading crtr or its installed plugins and marketplaces — pull the latest binary, refresh installed content, or both; pass --check first to see what is out of date without applying anything.',
+    whenToUse: 'upgrading crtr or its installed plugins and marketplaces — pull the latest binary, refresh installed content, or both, or just check what is out of date without applying anything.',
     help: {
         name: 'sys update',
         summary: 'update the crtr binary and/or installed plugins and marketplaces',

package/dist/commands/view-cycle.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const viewCycleLeaf: LeafDef;

package/dist/commands/view-cycle.js

@@ -0,0 +1,125 @@
+// `crtr view cycle <dir>` — switch the view hosted in a monitor pane to the
+// next/prev available view, in place. Backs the Alt+V then ] (next) / Alt+V
+// then [ (prev) chord installed by installViewNavBindings, mirroring how
+// `node cycle` backs Alt+] / Alt+[ for the node graph (view = the bracket
+// grammar namespaced under the Alt+V view prefix).
+//
+// A view monitor pane is self-identifying: `view run` tags it with the tmux
+// pane option @crtr_view=<id>. Cycle reads that tag, computes the next/prev id
+// in `listViews()` order (the SAME set `view list` enumerates), and respawns
+// the pane on `crtr view run <next-id>` — `respawn-pane -k` kills the current
+// view process and re-execs in the SAME pane (cycle itself runs in tmux's
+// run-shell context, NOT inside the pane, so the kill never targets the caller).
+// The respawned run re-tags the pane, so a rapid re-cycle reads the right id.
+//
+// tmux-only; a pane with no @crtr_view tag (not a view monitor) is a no-op.
+// Output is discarded by the keybinding, so this just acts.
+import { defineLeaf } from '../core/command.js';
+import { listViews, resolveView, loadView } from '../core/tui/loader.js';
+// Commands reach the tmux driver through placement.ts (the sanctioned
+// model-over-driver seam, §5.1) — never `./tmux.js` directly.
+import { inTmux, currentTmux, getPaneOption, setPaneOption, paneCurrentPath, respawnPaneSync, piCommand, } from '../core/runtime/placement.js';
+export const viewCycleLeaf = defineLeaf({
+    name: 'cycle',
+    description: 'switch the monitor pane to the next/prev view in place',
+    whenToUse: 'flipping a view monitor to the next/prev available view without re-running a command (bound to Alt+V then ] forward / Alt+V then [ back). The pane must already be hosting a view — opened with `crtr view run <name>` (or --window/--split). Use `crtr view run <name>` to open a specific view, or `crtr view list` to see the cycle order',
+    help: {
+        name: 'view cycle',
+        summary: 'switch the view hosted in a monitor pane to the next/previous available view, in place — the views walked one monitor at a time, in `view list` order (bound to Alt+V then ] forward / Alt+V then [ back)',
+        params: [
+            { kind: 'flag', name: 'dir', type: 'enum', choices: ['next', 'prev'], required: false, default: 'next', constraint: 'Direction along the view list: next (Alt+V then ]) or prev (Alt+V then [). Wraps at the ends.' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane to cycle. Defaults to $TMUX_PANE / your current pane. The Alt+V then ]/[ bindings pass this for you.' },
+        ],
+        output: [
+            { name: 'cycled', type: 'boolean', required: true, constraint: 'True when the pane was switched to another view.' },
+            { name: 'view', type: 'string', required: false, constraint: 'The view now hosted in the pane.' },
+            { name: 'from', type: 'string', required: false, constraint: 'The view it switched away from (absent when the pane was not a view monitor).' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Respawns the target pane (respawn-pane -k) running `crtr view run <next-id>`; the prior view process is replaced in place.',
+            'Re-tags the pane @crtr_view=<next-id>. No-op outside tmux or when the pane is not a view monitor.',
+        ],
+    },
+    run: async (input) => {
+        if (!inTmux())
+            return { cycled: false };
+        const dir = (input['dir'] ?? 'next');
+        const pane = input['pane'] ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane;
+        if (pane === undefined || pane === '')
+            return { cycled: false };
+        // Self-identification: only a pane `view run` tagged is a view monitor.
+        const current = getPaneOption(pane, '@crtr_view');
+        if (current === undefined || current === '')
+            return { cycled: false };
+        const ids = listViews().map((v) => v.id); // SAME set + order as `view list`
+        if (ids.length < 2)
+            return { cycled: false, from: current };
+        // Build the candidate order: views after `current` in `dir`, wrapping. If
+        // `current` was renamed/removed (i === -1) start at the head (next) / tail
+        // (prev) so the cycle lands on the FIRST available view (m3). Then advance
+        // past any view that fails to load, so a malformed view never closes the
+        // monitor on respawn (m4) — bounded to one full lap.
+        const n = ids.length;
+        const mod = (x) => ((x % n) + n) % n;
+        const step = dir === 'next' ? 1 : -1;
+        const i = ids.indexOf(current);
+        const candidates = [];
+        if (i === -1) {
+            const startIdx = dir === 'next' ? 0 : n - 1;
+            for (let k = 0; k < n; k++)
+                candidates.push(ids[mod(startIdx + step * k)]);
+        }
+        else {
+            for (let k = 1; k < n; k++)
+                candidates.push(ids[mod(i + step * k)]);
+        }
+        let targetId;
+        for (const cand of candidates) {
+            if (cand === current)
+                continue;
+            const rv = resolveView(cand);
+            if (rv === null)
+                continue;
+            try {
+                await loadView(rv);
+                targetId = cand;
+                break;
+            }
+            catch { /* skip malformed */ }
+        }
+        if (targetId === undefined)
+            return { cycled: false, from: current };
+        // Replay the connection params the monitor was opened with (M2): a view
+        // configured with --port/--target keeps them across a cycle, so a round-trip
+        // doesn't silently drop e.g. the LinkedIn view's CDP port. Params stick to
+        // the MONITOR (pane), not the view, and are harmless to views that ignore them.
+        const keepPort = getPaneOption(pane, '@crtr_view_port');
+        const keepTarget = getPaneOption(pane, '@crtr_view_target');
+        const argv = ['view', 'run', targetId];
+        if (keepPort !== undefined && keepPort !== '')
+            argv.push('--port', keepPort);
+        if (keepTarget !== undefined && keepTarget !== '')
+            argv.push('--target', keepTarget);
+        // Preserve the monitor's cwd so project-scoped views still resolve.
+        const cwd = paneCurrentPath(pane) ?? process.cwd();
+        const command = piCommand(argv, 'crtr');
+        const ok = respawnPaneSync({ pane, cwd, env: {}, command });
+        if (!ok)
+            return { cycled: false, from: current };
+        // The respawned `view run` re-tags @crtr_view (+ params), but set them now
+        // too so a rapid re-cycle reads the right state before the new run boots.
+        try {
+            setPaneOption(pane, '@crtr_view', targetId);
+            setPaneOption(pane, '@crtr_view_port', keepPort ?? '');
+            setPaneOption(pane, '@crtr_view_target', keepTarget ?? '');
+        }
+        catch { /* best-effort */ }
+        return { cycled: true, view: targetId, from: current };
+    },
+    render: (r) => r['cycled'] === true
+        ? `<view-cycled to="${r['view']}" from="${r['from'] ?? ''}"/>`
+        : r['from'] !== undefined
+            ? `<view-cycle-noop>no other view to switch to</view-cycle-noop>`
+            : `<view-cycle-noop>this pane is not hosting a view</view-cycle-noop>`,
+});

package/dist/commands/view-list.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const viewListLeaf: LeafDef;

package/dist/commands/view-list.js

@@ -0,0 +1,66 @@
+// `crtr view list` — enumerate every resolvable view across scopes.
+//
+// Lists id · title · description · scope. Loads each view to read its manifest
+// title/description; a malformed view is shown with an error marker (it never
+// crashes the listing). Plain text — pipeable as-is. The raw array is available
+// behind --json for tooling.
+import { defineLeaf } from '../core/command.js';
+import { listViews, loadView } from '../core/tui/loader.js';
+export const viewListLeaf = defineLeaf({
+    name: 'list',
+    description: 'enumerate available views (id · title · description · scope)',
+    whenToUse: 'you want to see which views exist before running one — a flat roster across project, user, and builtin scopes. Pipeable plain text; pass --json for the raw array. Use `crtr view run <id>` to open one, `crtr view new <name>` to scaffold one',
+    help: {
+        name: 'view list',
+        summary: 'list every resolvable view (id, title, description, scope); pipeable plain text',
+        inputNote: 'No input parameters.',
+        output: [
+            { name: 'views', type: 'array', required: true, constraint: 'One entry per view: { id, title, description, scope, error? }.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const rows = [];
+        for (const r of listViews()) {
+            try {
+                const v = await loadView(r);
+                rows.push({
+                    id: r.id,
+                    title: v.manifest.title,
+                    description: v.manifest.description ?? '',
+                    scope: r.scope,
+                });
+            }
+            catch (e) {
+                // Tolerate a malformed view — show it with an error marker, don't crash.
+                rows.push({
+                    id: r.id,
+                    title: '(failed to load)',
+                    description: '',
+                    scope: r.scope,
+                    error: e instanceof Error ? e.message : String(e),
+                });
+            }
+        }
+        return { views: rows };
+    },
+    render: (result) => {
+        const rows = result['views'] ?? [];
+        if (rows.length === 0) {
+            return 'No views found. Scaffold one with `crtr view new <name>`.';
+        }
+        const idW = Math.max(...rows.map((r) => r.id.length), 2);
+        const titleW = Math.max(...rows.map((r) => r.title.length), 5);
+        const lines = rows.map((r) => {
+            const id = r.id.padEnd(idW);
+            const title = r.title.padEnd(titleW);
+            if (r.error !== undefined) {
+                return `${id}  ${title}  [${r.scope}]  ⚠ ${r.error}`;
+            }
+            const desc = r.description !== '' ? `  ${r.description}` : '';
+            return `${id}  ${title}  [${r.scope}]${desc}`;
+        });
+        return lines.join('\n');
+    },
+});

package/dist/commands/view-new.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const viewNewLeaf: LeafDef;

package/dist/commands/view-new.js

@@ -0,0 +1,70 @@
+// `crtr view new <name>` — scaffold a runnable view.mjs into a scope dir.
+//
+// Writes <viewsDir(scope)>/<name>/view.mjs from the stub in prompts/view.ts
+// (mkdir -p first). Refuses if a view of that name already resolves. The
+// scaffolded view runs as-is via `crtr view run <name>`. Mirrors how skill
+// authoring scaffolds (resolve scope → ensure dir → write → point at how to run).
+import { mkdirSync, existsSync } from 'node:fs';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { defineLeaf } from '../core/command.js';
+import { usage } from '../core/errors.js';
+import { resolveView } from '../core/tui/loader.js';
+import { viewsDir, projectScopeRoot, ensureProjectScopeRoot } from '../core/scope.js';
+import { viewScaffold } from '../prompts/view.js';
+export const viewNewLeaf = defineLeaf({
+    name: 'new',
+    description: 'scaffold a runnable view.mjs stub into a scope dir',
+    whenToUse: 'you want to author a new view — this writes a minimal, runnable view.mjs (with the contract + draw/host API documented inline) into the user or project scope, ready to open immediately with `crtr view run <name>` and to edit from there. Reach for it to start a new TUI surface rather than hand-writing the module',
+    help: {
+        name: 'view new',
+        summary: 'scaffold <viewsDir(scope)>/<name>/view.mjs from the stub; refuses if the name already resolves',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'View id / directory name. Must not already resolve as a view.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Where to scaffold. Default: project if available, else user.' },
+            { kind: 'flag', name: 'title', type: 'string', required: false, constraint: 'Manifest title (header + picker). Default: the name.' },
+            { kind: 'flag', name: 'description', type: 'string', required: false, constraint: 'Manifest description (picker + `view list`). Default: empty.' },
+        ],
+        output: [
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the scaffolded view.mjs.' },
+            { name: 'scope', type: 'string', required: true, constraint: 'The scope it was written to (user|project).' },
+            { name: 'run', type: 'string', required: true, constraint: 'The command to run the new view.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Creates the view directory and view.mjs stub at the resolved location (mkdir -p).',
+            'Initializes the project scope dir if --scope project is chosen and none exists yet.',
+        ],
+    },
+    run: async (input) => {
+        const name = input['name'];
+        const scopeArg = input['scope'];
+        const title = input['title'] ?? name;
+        const description = input['description'] ?? '';
+        // Default scope: project if a project scope exists, else user.
+        const scope = scopeArg === 'project' || scopeArg === 'user'
+            ? scopeArg
+            : (projectScopeRoot() !== null ? 'project' : 'user');
+        // Refuse if a view of this name already resolves (any scope wins).
+        const existing = resolveView(name);
+        if (existing !== null) {
+            throw usage(`view already exists: ${name} (${existing.scope}) at ${existing.entry}. ` +
+                `Pick another name, or edit it directly.`);
+        }
+        // Ensure the project scope root exists before computing its views dir.
+        if (scope === 'project')
+            ensureProjectScopeRoot();
+        const baseDir = viewsDir(scope);
+        if (baseDir === null) {
+            throw usage(`no ${scope} scope available to scaffold into — try --scope user.`);
+        }
+        const dir = join(baseDir, name);
+        const entry = join(dir, 'view.mjs');
+        if (existsSync(entry)) {
+            throw usage(`view file already exists: ${entry}`);
+        }
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(entry, viewScaffold({ id: name, title, description }), 'utf8');
+        return { path: entry, scope, run: `crtr view run ${name}` };
+    },
+});

package/dist/commands/view-pick.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const viewPickLeaf: LeafDef;

package/dist/commands/view-pick.js

@@ -0,0 +1,119 @@
+// `crtr view pick` — hidden raw-ANSI picker over the available views.
+//
+// Backs the /view popup: a minimal full-screen list of listViews(); j/k move,
+// Enter hands off to `crtr view run <id>` (execFileSync, stdio inherit — a
+// one-way handoff, the picker exits as the view takes over, same pattern as
+// browse's selectAndFocus), q/Esc/Ctrl-C quit. Outside a TTY it prints the
+// plain list and exits 0. Reuses the core/tui terminal + draw primitives.
+import { execFileSync } from 'node:child_process';
+import { defineLeaf } from '../core/command.js';
+import { listViews } from '../core/tui/loader.js';
+import { setupTerminal, restoreTerminal, getTerminalSize, parseKeypress, } from '../core/tui/terminal.js';
+import { createDraw, detectColorCaps } from '../core/tui/draw.js';
+export const viewPickLeaf = defineLeaf({
+    name: 'pick',
+    tier: 'hidden',
+    description: 'raw-ANSI view picker (used by the /view popup)',
+    whenToUse: 'internal — the /view popup shells this to choose a view, then it execs `crtr view run <id>`. You normally run `crtr view run <name>` or `crtr view list` directly',
+    help: {
+        name: 'view pick',
+        summary: 'interactive picker over available views; Enter runs the chosen view. Outside a TTY it prints the list and exits',
+        inputNote: 'No input parameters.',
+        output: [],
+        outputKind: 'object',
+        effects: [
+            'Inside a TTY: takes over the terminal in raw mode until you pick (Enter) or quit (q/Esc/Ctrl-C).',
+            'On Enter: execs `crtr view run <id>` (stdio inherited) — a one-way handoff; the picker exits.',
+            'Outside a TTY: prints the plain view list and exits 0.',
+        ],
+    },
+    run: async () => {
+        const views = listViews();
+        // Non-TTY: print the plain list and exit 0.
+        if (!process.stdin.isTTY) {
+            const text = views.length > 0
+                ? views.map((v) => `${v.id}\t${v.scope}`).join('\n')
+                : '(no views)';
+            process.stdout.write(text + '\n');
+            return;
+        }
+        if (views.length === 0) {
+            process.stdout.write('No views found. Scaffold one with `crtr view new <name>`.\n');
+            return;
+        }
+        const caps = detectColorCaps();
+        let cursor = 0;
+        let scroll = 0;
+        let restored = false;
+        const cleanup = () => {
+            if (restored)
+                return;
+            restored = true;
+            try {
+                restoreTerminal();
+            }
+            catch { /* best-effort */ }
+        };
+        process.once('exit', cleanup);
+        const render = () => {
+            const size = getTerminalSize();
+            const { draw, frame } = createDraw(size, caps);
+            draw.text(0, 0, 'crtr views — j/k move · Enter run · q quit', { bold: true });
+            draw.hline(1, 0, size.cols);
+            const rect = { row: 2, col: 0, width: size.cols, height: Math.max(1, size.rows - 3) };
+            const items = views.map((v) => ({
+                spans: [
+                    { text: v.id, style: { bold: true } },
+                    { text: `  [${v.scope}]`, style: { dim: true } },
+                ],
+            }));
+            const res = draw.list(rect, items, cursor, scroll);
+            scroll = res.scroll;
+            process.stdout.write(frame());
+        };
+        setupTerminal();
+        render();
+        await new Promise((resolve) => {
+            const finish = () => {
+                cleanup();
+                process.exit(0);
+            };
+            const launch = (id) => {
+                cleanup();
+                try {
+                    execFileSync('crtr', ['view', 'run', id], { stdio: 'inherit' });
+                }
+                catch {
+                    // The view takes the terminal over; a sync handoff may be interrupted.
+                }
+                process.exit(0);
+            };
+            process.stdin.on('data', (d) => {
+                let parsed;
+                try {
+                    parsed = parseKeypress(d);
+                }
+                catch {
+                    return;
+                }
+                const { input, key } = parsed;
+                if (key.ctrl && input === 'c')
+                    finish();
+                if (input === 'q' || key.escape)
+                    finish();
+                if (input === 'j' || key.downArrow) {
+                    cursor = Math.min(views.length - 1, cursor + 1);
+                    render();
+                    return;
+                }
+                if (input === 'k' || key.upArrow) {
+                    cursor = Math.max(0, cursor - 1);
+                    render();
+                    return;
+                }
+                if (key.return)
+                    launch(views[cursor].id);
+            });
+        });
+    },
+});

package/dist/commands/view-run.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const viewRunLeaf: LeafDef;