@crouton-kit/crouter 0.3.33 → 0.3.35

package/dist/commands/sys/setup.js

@@ -0,0 +1,516 @@
+import { defineLeaf } from '../../core/command.js';
+import { getMarkdownTheme, getSelectListTheme, getSettingsListTheme } from '@earendil-works/pi-coding-agent';
+import { TUI, ProcessTerminal, Input, matchesKey, truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+import { applyTheme } from '../../clients/attach/config-load.js';
+const ANSI_GREEN = (s) => `\x1b[32m${s}\x1b[39m`;
+const ANSI_YELLOW = (s) => `\x1b[33m${s}\x1b[39m`;
+const theme = {
+    fg(role, text) {
+        switch (role) {
+            case 'border':
+                return getMarkdownTheme().hr(text);
+            case 'accent':
+                return getMarkdownTheme().heading(text);
+            case 'dim':
+                return getSettingsListTheme().description(text);
+            case 'muted':
+                return getSelectListTheme().description(text);
+            case 'mdLink':
+                return getMarkdownTheme().link(text);
+            case 'mdLinkUrl':
+                return getMarkdownTheme().linkUrl(text);
+            case 'success':
+                return ANSI_GREEN(text);
+            case 'warning':
+                return ANSI_YELLOW(text);
+        }
+    },
+    bg(_role, text) {
+        return text;
+    },
+    bold(text) {
+        return getMarkdownTheme().bold(text);
+    },
+};
+import { buildSetupInitialState, executeSetupSubmission, formatSetupExecutionSummary, renderSetupStaticInstructions, resolveExaKeyPath, } from './setup-core.js';
+function wrapText(text, width) {
+    const clean = text.trim();
+    if (clean === '')
+        return [''];
+    if (width <= 1)
+        return [truncateToWidth(clean, width)];
+    const words = clean.split(/\s+/);
+    const lines = [];
+    let current = '';
+    for (const word of words) {
+        if (current === '') {
+            current = word;
+            continue;
+        }
+        const next = `${current} ${word}`;
+        if (truncateToWidth(next, width) === next) {
+            current = next;
+        }
+        else {
+            lines.push(truncateToWidth(current, width));
+            current = word;
+        }
+    }
+    if (current !== '')
+        lines.push(truncateToWidth(current, width));
+    return lines.length > 0 ? lines : [''];
+}
+function currentWidth() {
+    return Math.max(1, process.stdout.columns ?? 80);
+}
+function toolLabel(tool) {
+    return tool === 'nvim' ? 'nvim' : 'tmux';
+}
+function renderRows(lines, width) {
+    return lines.map((line) => truncateToWidth(line, width));
+}
+function padAnsi(text, width) {
+    const used = visibleWidth(text);
+    if (used >= width)
+        return truncateToWidth(text, width);
+    return `${text}${' '.repeat(width - used)}`;
+}
+function rule(width) {
+    return theme.fg('border', '─'.repeat(Math.max(0, width)));
+}
+function tabPill(label, active) {
+    return active
+        ? theme.bg('selectedBg', theme.fg('accent', theme.bold(` ${label} `)))
+        : theme.fg('dim', ` ${label} `);
+}
+function framed(lines, width) {
+    if (width < 4)
+        return lines.map((line) => truncateToWidth(line, width));
+    const innerWidth = width - 4;
+    const border = theme.fg('border', '│');
+    const top = theme.fg('border', `┌${'─'.repeat(width - 2)}┐`);
+    const bottom = theme.fg('border', `└${'─'.repeat(width - 2)}┘`);
+    const body = lines.map((line) => {
+        const content = padAnsi(truncateToWidth(line, innerWidth), innerWidth);
+        return `${border} ${content} ${border}`;
+    });
+    return [top, ...body, bottom];
+}
+class SetupWizard {
+    manifest;
+    installedPackageIds;
+    systemTools;
+    exaInput = new Input();
+    selectedPackageIds = new Set();
+    selectedSystemTools = new Set();
+    activeTab = 0;
+    pluginIndex = 0;
+    systemIndex = 0;
+    expandedPluginId = null;
+    confirming = false;
+    cachedWidth;
+    cachedLines;
+    _focused = false;
+    onSubmit;
+    onCancel;
+    constructor(manifest, installedPackageIds, systemTools) {
+        this.manifest = manifest;
+        this.installedPackageIds = installedPackageIds;
+        this.systemTools = systemTools;
+        for (const entry of this.manifest)
+            this.selectedPackageIds.add(entry.id);
+        for (const tool of this.systemTools) {
+            if (tool.plan.checked)
+                this.selectedSystemTools.add(tool.tool);
+        }
+        const firstMissingSystem = this.systemTools.findIndex((tool) => !tool.installed);
+        this.systemIndex = firstMissingSystem >= 0 ? firstMissingSystem : 0;
+        this.exaInput.onSubmit = () => this.finalize();
+        this.exaInput.onEscape = () => this.cancel();
+    }
+    set focused(value) {
+        this._focused = value;
+        this.exaInput.focused = value && this.activeTab === 2 && !this.confirming;
+    }
+    get focused() {
+        return this._focused;
+    }
+    invalidate() {
+        this.cachedWidth = undefined;
+        this.cachedLines = undefined;
+    }
+    setTab(next) {
+        this.activeTab = next;
+        this.exaInput.focused = this.focused && next === 2 && !this.confirming;
+        this.invalidate();
+    }
+    moveTab(delta) {
+        const next = ((this.activeTab + delta + 3) % 3);
+        this.setTab(next);
+    }
+    cancel() {
+        if (this.confirming) {
+            this.confirming = false;
+            this.invalidate();
+            return;
+        }
+        this.onCancel?.();
+    }
+    handleGlobalTabSwitch(data) {
+        if (matchesKey(data, 'tab') || matchesKey(data, 'right')) {
+            this.moveTab(1);
+            return true;
+        }
+        if (matchesKey(data, 'shift+tab') || matchesKey(data, 'left')) {
+            this.moveTab(-1);
+            return true;
+        }
+        return false;
+    }
+    selectedPackage() {
+        return this.manifest[this.pluginIndex];
+    }
+    selectedSystem() {
+        return this.systemTools[this.systemIndex];
+    }
+    movePlugin(delta) {
+        if (this.manifest.length === 0)
+            return;
+        this.pluginIndex = (this.pluginIndex + delta + this.manifest.length) % this.manifest.length;
+        this.invalidate();
+    }
+    moveSystem(delta) {
+        const interactives = this.systemTools
+            .map((tool, index) => ({ tool, index }))
+            .filter(({ tool }) => !tool.installed);
+        if (interactives.length === 0)
+            return;
+        const currentIndex = interactives.findIndex(({ index }) => index === this.systemIndex);
+        const nextPos = ((currentIndex >= 0 ? currentIndex : 0) + delta + interactives.length) % interactives.length;
+        this.systemIndex = interactives[nextPos].index;
+        this.invalidate();
+    }
+    togglePackage() {
+        const entry = this.selectedPackage();
+        if (!entry)
+            return;
+        if (this.selectedPackageIds.has(entry.id))
+            this.selectedPackageIds.delete(entry.id);
+        else
+            this.selectedPackageIds.add(entry.id);
+        this.invalidate();
+    }
+    toggleSystem() {
+        const tool = this.selectedSystem();
+        if (!tool || tool.installed)
+            return;
+        if (this.selectedSystemTools.has(tool.tool))
+            this.selectedSystemTools.delete(tool.tool);
+        else
+            this.selectedSystemTools.add(tool.tool);
+        this.invalidate();
+    }
+    toggleDetails() {
+        const entry = this.selectedPackage();
+        if (!entry)
+            return;
+        this.expandedPluginId = this.expandedPluginId === entry.id ? null : entry.id;
+        this.invalidate();
+    }
+    hasPendingInstalls() {
+        const packages = this.manifest.some((entry) => this.selectedPackageIds.has(entry.id) && !this.installedPackageIds.has(entry.id));
+        const system = this.systemTools.some((tool) => !tool.installed && this.selectedSystemTools.has(tool.tool));
+        return packages || system;
+    }
+    buildSubmission() {
+        return {
+            packages: this.manifest.filter((entry) => this.selectedPackageIds.has(entry.id)),
+            installedPackageIds: new Set(this.installedPackageIds),
+            systemDeps: this.systemTools.filter((tool) => !tool.installed && this.selectedSystemTools.has(tool.tool)).map((tool) => tool.plan),
+            exaKey: this.exaInput.getValue().trim(),
+            exaKeyPath: resolveExaKeyPath(),
+        };
+    }
+    finalize() {
+        if (this.confirming) {
+            this.onSubmit?.(this.buildSubmission());
+            return;
+        }
+        if (this.hasPendingInstalls()) {
+            this.confirming = true;
+            this.invalidate();
+            return;
+        }
+        this.onSubmit?.(this.buildSubmission());
+    }
+    handleInput(data) {
+        if (this.confirming) {
+            if (matchesKey(data, 'enter') || matchesKey(data, 'y')) {
+                this.onSubmit?.(this.buildSubmission());
+                return;
+            }
+            if (matchesKey(data, 'n') || matchesKey(data, 'escape') || matchesKey(data, 'q')) {
+                this.confirming = false;
+                this.invalidate();
+                return;
+            }
+            return;
+        }
+        if (matchesKey(data, 'ctrl+c') || matchesKey(data, 'ctrl+d') || matchesKey(data, 'q')) {
+            this.cancel();
+            return;
+        }
+        if (this.handleGlobalTabSwitch(data))
+            return;
+        if (this.activeTab === 0) {
+            if (matchesKey(data, 'j') || matchesKey(data, 'down')) {
+                this.movePlugin(1);
+                return;
+            }
+            if (matchesKey(data, 'k') || matchesKey(data, 'up')) {
+                this.movePlugin(-1);
+                return;
+            }
+            if (matchesKey(data, 'space')) {
+                this.togglePackage();
+                return;
+            }
+            if (matchesKey(data, '?')) {
+                this.toggleDetails();
+                return;
+            }
+            if (matchesKey(data, 'enter')) {
+                this.moveTab(1);
+                return;
+            }
+            return;
+        }
+        if (this.activeTab === 1) {
+            if (matchesKey(data, 'j') || matchesKey(data, 'down')) {
+                this.moveSystem(1);
+                return;
+            }
+            if (matchesKey(data, 'k') || matchesKey(data, 'up')) {
+                this.moveSystem(-1);
+                return;
+            }
+            if (matchesKey(data, 'space')) {
+                this.toggleSystem();
+                return;
+            }
+            if (matchesKey(data, 'enter')) {
+                this.moveTab(1);
+                return;
+            }
+            return;
+        }
+        this.exaInput.handleInput(data);
+    }
+    renderHeader(width) {
+        const tabs = ['Plugins', 'System deps', 'Exa key'];
+        const tabLine = tabs
+            .map((label, index) => tabPill(`${index + 1}. ${label}`, index === this.activeTab))
+            .join(theme.fg('dim', '  ·  '));
+        return [
+            truncateToWidth(theme.fg('accent', theme.bold('crtr sys setup')), width),
+            truncateToWidth(tabLine, width),
+            truncateToWidth(rule(width), width),
+        ];
+    }
+    renderFooter(width) {
+        const line = this.confirming
+            ? 'y/enter confirm · n/esc go back · q cancel'
+            : this.activeTab === 0
+                ? 'j/k or ↑/↓ move · space toggle · ? details · enter/Tab advance · ←/→ switch tabs · q cancel'
+                : this.activeTab === 1
+                    ? 'j/k or ↑/↓ move · space toggle · enter/Tab advance · ←/→ switch tabs · q cancel'
+                    : 'type EXA_API_KEY · enter finish · Tab/Shift-Tab or ←/→ switch tabs · q cancel';
+        return [truncateToWidth(theme.fg('dim', line), width)];
+    }
+    renderPlugins(width) {
+        const out = [];
+        out.push(truncateToWidth(`${theme.fg('accent', theme.bold('Plugins'))}${theme.fg('dim', '  default ON')}`, width));
+        for (const [index, entry] of this.manifest.entries()) {
+            const selected = index === this.pluginIndex;
+            const checked = this.selectedPackageIds.has(entry.id) ? theme.fg('success', '[x]') : theme.fg('dim', '[ ]');
+            const marker = selected ? theme.fg('accent', '▶') : theme.fg('dim', ' ');
+            const name = selected ? theme.fg('accent', entry.name) : entry.name;
+            const status = this.installedPackageIds.has(entry.id)
+                ? theme.fg('success', '✓ installed')
+                : theme.fg('warning', 'not installed');
+            const line = `${marker} ${checked} ${name} ${theme.fg('dim', '—')} ${theme.fg('muted', entry.shortDescription)} ${status}`;
+            out.push(truncateToWidth(line, width));
+            if (this.expandedPluginId === entry.id) {
+                for (const line of wrapText(entry.longDescription, Math.max(1, width - 4))) {
+                    out.push(truncateToWidth(theme.fg('dim', `    ${line}`), width));
+                }
+            }
+        }
+        return out;
+    }
+    renderSystems(width) {
+        const out = [];
+        out.push(truncateToWidth(`${theme.fg('accent', theme.bold('System deps'))}${theme.fg('dim', '  tmux + nvim check')}`, width));
+        for (const [index, tool] of this.systemTools.entries()) {
+            const selected = index === this.systemIndex;
+            const marker = selected ? theme.fg('accent', '▶') : theme.fg('dim', ' ');
+            if (tool.installed) {
+                const line = `${marker} ${theme.fg('success', '✓ installed')} ${theme.fg('muted', toolLabel(tool.tool))}`;
+                out.push(truncateToWidth(line, width));
+                continue;
+            }
+            const checked = this.selectedSystemTools.has(tool.tool) ? theme.fg('success', '[x]') : theme.fg('dim', '[ ]');
+            const label = tool.plan.command ?? tool.plan.hint;
+            const name = selected ? theme.fg('accent', `Install ${toolLabel(tool.tool)}`) : `Install ${toolLabel(tool.tool)}`;
+            const line = `${marker} ${checked} ${name} ${theme.fg('dim', '—')} ${theme.fg('muted', label)} ${theme.fg('warning', 'not installed')}`;
+            out.push(truncateToWidth(line, width));
+        }
+        return out;
+    }
+    renderExa(width) {
+        const out = [];
+        out.push(truncateToWidth(`${theme.fg('accent', theme.bold('Exa key'))}${theme.fg('dim', '  optional')}`, width));
+        out.push(truncateToWidth(`${theme.fg('mdLink', 'Create a key: ')}${theme.fg('mdLinkUrl', 'https://dashboard.exa.ai/api-keys')}`, width));
+        out.push(truncateToWidth(theme.fg('dim', `Will write to: ${resolveExaKeyPath()}`), width));
+        out.push(...framed([
+            theme.fg('accent', theme.bold('Paste EXA_API_KEY here')),
+            theme.fg('dim', 'Leave blank to skip.'),
+            ...this.exaInput.render(Math.max(1, width - 4)),
+        ], width));
+        return out;
+    }
+    renderConfirm(width) {
+        const out = [truncateToWidth(theme.fg('warning', theme.bold('Confirm installs')), width)];
+        const submission = this.buildSubmission();
+        if (submission.packages.length === 0 && submission.systemDeps.length === 0 && submission.exaKey === '') {
+            out.push(truncateToWidth(theme.fg('success', 'Nothing to install; press enter to finish.'), width));
+            return out;
+        }
+        if (submission.packages.length > 0) {
+            out.push(truncateToWidth(theme.fg('accent', 'Packages'), width));
+            for (const entry of submission.packages) {
+                const action = this.installedPackageIds.has(entry.id)
+                    ? theme.fg('success', 'skip (already installed)')
+                    : theme.fg('muted', `pi install ${entry.installSource}`);
+                out.push(truncateToWidth(`  • ${entry.name} ${theme.fg('dim', '→')} ${action}`, width));
+            }
+        }
+        if (submission.systemDeps.length > 0) {
+            out.push(truncateToWidth(theme.fg('accent', 'System deps'), width));
+            for (const plan of submission.systemDeps) {
+                out.push(truncateToWidth(`  • ${plan.tool} ${theme.fg('dim', '→')} ${theme.fg('muted', plan.command ?? plan.hint)}`, width));
+            }
+        }
+        if (submission.exaKey !== '') {
+            out.push(truncateToWidth(`${theme.fg('accent', 'Exa key')} ${theme.fg('dim', '→')} ${theme.fg('warning', `write ${submission.exaKeyPath}`)}`, width));
+        }
+        out.push(truncateToWidth(theme.fg('dim', 'y/enter confirm · n/esc go back'), width));
+        return out;
+    }
+    render(width) {
+        if (this.cachedLines && this.cachedWidth === width)
+            return this.cachedLines;
+        const lines = [
+            ...this.renderHeader(width),
+            '',
+            ...(this.confirming ? this.renderConfirm(width) : this.activeTab === 0 ? this.renderPlugins(width) : this.activeTab === 1 ? this.renderSystems(width) : this.renderExa(width)),
+            '',
+            ...this.renderFooter(width),
+        ];
+        this.cachedWidth = width;
+        this.cachedLines = renderRows(lines, width);
+        return this.cachedLines;
+    }
+}
+async function runSetup() {
+    const state = buildSetupInitialState();
+    if (!process.stdout.isTTY) {
+        process.stdout.write(renderSetupStaticInstructions(state));
+        return;
+    }
+    applyTheme({ cwd: process.cwd() });
+    const terminal = new ProcessTerminal();
+    const tui = new TUI(terminal, true);
+    const wizard = new SetupWizard(state.manifest, state.installedPackageIds, state.systemTools);
+    tui.addChild(wizard);
+    tui.setFocus(wizard);
+    await new Promise((resolve, reject) => {
+        let restored = false;
+        const restore = () => {
+            if (restored)
+                return;
+            restored = true;
+            try {
+                tui.stop();
+            }
+            catch {
+                /* best-effort terminal restore */
+            }
+        };
+        let done = false;
+        const finish = () => {
+            if (done)
+                return;
+            done = true;
+            restore();
+            resolve();
+        };
+        const fail = (error) => {
+            if (done)
+                return;
+            done = true;
+            restore();
+            reject(error);
+        };
+        const onSignal = () => finish();
+        process.once('exit', restore);
+        process.once('SIGTERM', onSignal);
+        process.once('SIGHUP', onSignal);
+        process.once('SIGINT', onSignal);
+        wizard.onCancel = finish;
+        wizard.onSubmit = (submission) => {
+            restore();
+            void executeSetupSubmission(submission)
+                .then((summary) => {
+                if (done)
+                    return;
+                done = true;
+                process.stdout.write(formatSetupExecutionSummary(summary));
+                resolve();
+            }, fail);
+        };
+        tui.addInputListener((data) => {
+            if (matchesKey(data, 'ctrl+c') || matchesKey(data, 'ctrl+d')) {
+                finish();
+                return { consume: true };
+            }
+            return undefined;
+        });
+        try {
+            tui.start();
+        }
+        catch (error) {
+            fail(error);
+        }
+    });
+}
+export const sysSetupLeaf = defineLeaf({
+    name: 'setup',
+    description: 'install the bundled pi plugins, system deps, and Exa key setup',
+    whenToUse: 'you want to bootstrap this machine for crtr in one pass: install the vendored pi plugins, confirm tmux and nvim, and save your Exa API key.',
+    help: {
+        name: 'sys setup',
+        summary: 'open the multi-tab setup wizard for bundled pi plugins, system deps, and Exa key',
+        inputNote: 'No input parameters.',
+        output: [],
+        outputKind: 'object',
+        effects: [
+            'Opens a pi-tui wizard that collects companion package installs, system dependency installs, and an Exa API key.',
+            'Runs pi installs for the selected bundled packages, writes EXA_API_KEY to ~/.crouter/exa.key when provided, and prints a summary.',
+        ],
+    },
+    run: async () => {
+        await runSetup();
+    },
+    render: () => '',
+});

package/dist/commands/sys/sysprompt.js

@@ -29,6 +29,9 @@ export const sysSyspromptLeaf = defineLeaf({
         ],
         outputKind: 'object',
         effects: ['Read-only: reads the node\'s job/system-prompt.md artifact, or opens it in a tmux window.'],
+        // Giant prompt dump / machine payload for an agent to inspect deliberately,
+        // not to glance at inline — collapse it in the attach viewer by default.
+        preview: { suppressOutput: true },
     },
     run: async (input) => {
         const nodeId = input['node']?.trim() || process.env['CRTR_NODE_ID'];

package/dist/commands/sys.js

@@ -5,6 +5,7 @@ import { configBranch } from './sys/config.js';
 import { sysDoctorLeaf } from './sys/doctor.js';
 import { sysFeedbackLeaf } from './sys/feedback.js';
 import { sysSettingsLeaf } from './sys/settings.js';
+import { sysSetupLeaf } from './sys/setup.js';
 import { sysSyspromptLeaf } from './sys/sysprompt.js';
 import { promptReviewLeaf } from './sys/prompt-review.js';
 import { sysPromptStudioLeaf } from './sys/promptstudio.js';
@@ -15,13 +16,13 @@ export function registerSys() {
         name: 'sys',
         rootEntry: {
             concept: 'crtr configuration, diagnostics, and self-management',
-            desc: 'config, settings, doctor, sysprompt, prompt-review, promptstudio, sync, update, version, feedback',
+            desc: 'config, settings, setup, doctor, sysprompt, prompt-review, promptstudio, sync, update, version, feedback',
             useWhen: 'managing the crtr installation or opening built-in system views',
         },
         help: {
             name: 'sys',
             summary: 'crtr system configuration, settings, diagnostics, and self-management',
         },
-        children: [configBranch, sysSettingsLeaf, sysDoctorLeaf, sysSyspromptLeaf, promptReviewLeaf, sysPromptStudioLeaf, sysFeedbackLeaf, sysUpdateLeaf, sysVersionLeaf, sysSyncLeaf],
+        children: [configBranch, sysSettingsLeaf, sysSetupLeaf, sysDoctorLeaf, sysSyspromptLeaf, promptReviewLeaf, sysPromptStudioLeaf, sysFeedbackLeaf, sysUpdateLeaf, sysVersionLeaf, sysSyncLeaf],
     });
 }

package/dist/commands/view-cycle.js

@@ -1,4 +1,4 @@
-// `crtr view cycle <dir>` — switch the view hosted in a monitor pane to the
+// `crtr surface view cycle` — 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
@@ -7,7 +7,7 @@
 // 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
+// the pane on the surface-view run command — `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.
@@ -22,7 +22,7 @@ import { inTmux, currentTmux, getPaneOption, setPaneOption, paneCurrentPath, res
 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',
+    whenToUse: 'flipping a view monitor to the next or previous 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 and the view list must contain a different target. Use run to open a specific view, or 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)',
@@ -37,7 +37,7 @@ export const viewCycleLeaf = defineLeaf({
         ],
         outputKind: 'object',
         effects: [
-            'Respawns the target pane (respawn-pane -k) running `crtr view run <next-id>`; the prior view process is replaced in place.',
+            'Respawns the target pane in place running the next view; the prior view process is replaced.',
             'Re-tags the pane @crtr_view=<next-id>. No-op outside tmux or when the pane is not a view monitor.',
         ],
     },
@@ -96,7 +96,7 @@ export const viewCycleLeaf = defineLeaf({
         // 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];
+        const argv = ['surface', 'view', 'run', targetId];
         if (keepPort !== undefined && keepPort !== '')
             argv.push('--port', keepPort);
         if (keepTarget !== undefined && keepTarget !== '')

package/dist/commands/view-list.js

@@ -1,4 +1,4 @@
-// `crtr view list` — enumerate every resolvable view across scopes.
+// `crtr surface view list` — enumerate every resolvable view across scopes.
 //
 // Lists id · title · description · scope. Loads each view's core.mjs to read its
 // manifest title/description; a malformed view is shown with an error marker (it
@@ -9,7 +9,7 @@ import { listViews, loadCore } from '../core/view/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',
+    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 run to open one and new to scaffold one',
     help: {
         name: 'view list',
         summary: 'list every resolvable view (id, title, description, scope); pipeable plain text',
@@ -48,7 +48,7 @@ export const viewListLeaf = defineLeaf({
     render: (result) => {
         const rows = result['views'] ?? [];
         if (rows.length === 0) {
-            return 'No views found. Scaffold one with `crtr view new <name>`.';
+            return 'No views found. Scaffold one with the view new leaf.';
         }
         const idW = Math.max(...rows.map((r) => r.id.length), 2);
         const titleW = Math.max(...rows.map((r) => r.title.length), 5);

package/dist/commands/view-new.js

@@ -1,9 +1,9 @@
-// `crtr view new <name>` — scaffold a runnable dual-target view into a scope dir.
+// `crtr surface view new` — scaffold a runnable dual-target view into a scope dir.
 //
 // Writes the four contract files (core.mjs + tui.mjs + web.jsx + text.mjs) under
 // <viewsDir(scope)>/<name>/ from the stubs in prompts/view.ts (mkdir -p first).
 // Refuses if a view of that name already resolves. The scaffold runs as-is via
-// `crtr view run <name>` (TUI) and `crtr view serve <name>` (web). Mirrors the
+// the surface view host (TUI/static) and the surface web server. Mirrors the
 // scope → ensure dir → write → point-at-run shape of other authoring commands.
 import { mkdirSync, existsSync } from 'node:fs';
 import { writeFileSync } from 'node:fs';
@@ -16,7 +16,7 @@ import { viewScaffold } from '../prompts/view.js';
 export const viewNewLeaf = defineLeaf({
     name: 'new',
     description: 'scaffold a runnable dual-target view directory into a scope dir',
-    whenToUse: 'you want to author a new view — this writes the four contract files (core.mjs + tui.mjs + web.jsx + text.mjs, with the contract documented inline) into the user or project scope, ready to open immediately with `crtr view run <name>` (TUI) or `crtr view serve <name>` (web) and to edit from there. Reach for it to start a new view rather than hand-writing the directory',
+    whenToUse: 'you want to author a new view — this writes the four contract files (core.mjs + tui.mjs + web.jsx + text.mjs, with the contract documented inline) into the user or project scope, ready to open in either host and to edit from there. Reach for it to start a new view rather than hand-writing the directory',
     help: {
         name: 'view new',
         summary: 'scaffold <viewsDir(scope)>/<name>/{core,tui,text}.mjs + web.jsx from the stubs; refuses if the name already resolves',
@@ -24,7 +24,7 @@ export const viewNewLeaf = defineLeaf({
             { 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.' },
+            { kind: 'flag', name: 'description', type: 'string', required: false, constraint: 'Manifest description (picker and list). Default: empty.' },
         ],
         output: [
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the scaffolded view directory.' },
@@ -69,6 +69,6 @@ export const viewNewLeaf = defineLeaf({
         for (const [filename, content] of Object.entries(files)) {
             writeFileSync(join(dir, filename), content, 'utf8');
         }
-        return { path: dir, files: Object.keys(files), scope, run: `crtr view run ${name}` };
+        return { path: dir, files: Object.keys(files), scope, run: `crtr surface view run ${name}` };
     },
 });