@north-light/api 0.3.579 → 0.3.587

package/dist/commands/sys/terminal-option.js

@@ -0,0 +1,542 @@
+// Option-as-Alt on macOS — which terminal is this, does it already send Alt for
+// the Option key, and what (if anything) can crouter safely write to fix it.
+//
+// crouter's action menu is Alt+C, the inbox is Alt+I, and most viewer shortcuts
+// are Alt chords. macOS terminals type an accented character (ç, ˆ) for Option
+// unless told to send Alt/Meta, so a first-time user's Alt+C silently does
+// nothing. This module is the pure half of the setup step that explains that:
+// detection, instructions and the two edits that are safe to script. The panel
+// that shows it lives in panels/terminal-panel.ts.
+//
+// What is scripted, and why only that:
+//  - Ghostty reads a plain-text `key = value` config and the last assignment
+//    wins, so appending one line is a reversible, whole-file-safe edit — unless a
+//    `config-file` include (loaded AFTER every default config file, so it
+//    overrides them) also sets the key; then the line would not take effect, and
+//    the step falls back to instructions naming the overriding file.
+//  - VS Code reads settings.json (JSON with comments). Inserting one property
+//    right after the top-level opening brace never disturbs the rest of the file,
+//    so it is safe — but only for stock VS Code, whose settings path is certain.
+//    Only a TOP-LEVEL property counts; a same-named key nested in a
+//    `"[markdown]": {…}` block is a different setting.
+//  - Terminal.app and iTerm2 keep this in binary plists behind macOS's
+//    preferences daemon, which rewrites them from the running app on quit and
+//    keys profiles by GUID. A `defaults write` races the app and can be silently
+//    reverted or clobber profiles, so those get exact click-path instructions.
+//  - Kitty, Alacritty and WezTerm configs are user-authored code or structured
+//    TOML/Lua with no safe append; they get the exact line to add.
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+/** True positive identification of the terminal the user is typing into, from the
+ *  variables terminals export. `TERM_PROGRAM` is overwritten by tmux (`tmux`), so
+ *  terminal-specific markers are consulted after it. */
+export function detectTerminal(env) {
+    const termProgram = env['TERM_PROGRAM'] ?? '';
+    const term = env['TERM'] ?? '';
+    switch (termProgram) {
+        case 'Apple_Terminal': return { id: 'terminal-app', name: 'Terminal.app' };
+        case 'iTerm.app': return { id: 'iterm2', name: 'iTerm2' };
+        case 'ghostty': return { id: 'ghostty', name: 'Ghostty' };
+        case 'WezTerm': return { id: 'wezterm', name: 'WezTerm' };
+        case 'vscode':
+            return env['CURSOR_TRACE_ID'] !== undefined
+                ? { id: 'cursor', name: 'the Cursor terminal' }
+                : { id: 'vscode', name: 'the VS Code terminal' };
+    }
+    // LC_TERMINAL survives tmux and ssh, which overwrite TERM_PROGRAM, so it
+    // outranks only the markers below, never a TERM_PROGRAM that names a terminal.
+    if (env['LC_TERMINAL'] === 'iTerm2')
+        return { id: 'iterm2', name: 'iTerm2' };
+    if (env['GHOSTTY_RESOURCES_DIR'] !== undefined || term === 'xterm-ghostty')
+        return { id: 'ghostty', name: 'Ghostty' };
+    if (env['KITTY_WINDOW_ID'] !== undefined || term === 'xterm-kitty')
+        return { id: 'kitty', name: 'kitty' };
+    if (env['WEZTERM_EXECUTABLE'] !== undefined || env['WEZTERM_PANE'] !== undefined)
+        return { id: 'wezterm', name: 'WezTerm' };
+    if (env['ALACRITTY_SOCKET'] !== undefined || env['ALACRITTY_LOG'] !== undefined || term === 'alacritty')
+        return { id: 'alacritty', name: 'Alacritty' };
+    if (env['ITERM_SESSION_ID'] !== undefined)
+        return { id: 'iterm2', name: 'iTerm2' };
+    return { id: 'unknown', name: 'your terminal' };
+}
+const GHOSTTY_KEY = 'macos-option-as-alt';
+const VSCODE_KEY = 'terminal.integrated.macOptionIsMeta';
+/** Ghostty's default config files in the documented load order (ghostty.org/docs/
+ *  config#file-location) — a later file overrides an earlier one, and every macOS
+ *  Application Support file loads after every XDG file. */
+export function ghosttyConfigPaths(env, home) {
+    const xdg = env['XDG_CONFIG_HOME'] !== undefined && env['XDG_CONFIG_HOME'] !== '' ? env['XDG_CONFIG_HOME'] : join(home, '.config');
+    const appSupport = join(home, 'Library', 'Application Support', 'com.mitchellh.ghostty');
+    return [
+        join(xdg, 'ghostty', 'config.ghostty'),
+        join(xdg, 'ghostty', 'config'),
+        join(appSupport, 'config.ghostty'),
+        join(appSupport, 'config'),
+    ];
+}
+const GHOSTTY_VALUES = new Set(['true', 'false', 'left', 'right']);
+function readTextOrNull(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+function unquote(raw) {
+    const value = raw.trim();
+    return value.length >= 2 && value.startsWith('"') && value.endsWith('"') ? value.slice(1, -1) : value;
+}
+/** The effective `macos-option-as-alt`, following Ghostty's own precedence: the
+ *  default files load in order (a later file overrides an earlier one, the last
+ *  assignment within a file wins), then every `config-file` include — from any of
+ *  them — loads after ALL of them, in order, so an include overrides every
+ *  default file; includes of includes queue behind. `config-file = ""` clears the
+ *  includes gathered so far, `?path` is an optional include, relative paths are
+ *  relative to the including file, and an empty `macos-option-as-alt =` resets to
+ *  the default. A line with an unrecognised value is rejected by Ghostty and
+ *  ignored here. */
+export function resolveGhosttyOptionSetting(paths, home = homedir(), read = readTextOrNull) {
+    let value;
+    let source;
+    const unreadable = [];
+    let queue = [];
+    const seen = new Set();
+    const load = (path, optional) => {
+        const text = read(path);
+        if (text === null) {
+            if (!optional && existsSync(path))
+                unreadable.push(path);
+            return;
+        }
+        for (const line of text.split(/\r?\n/)) {
+            const match = /^\s*([A-Za-z0-9-]+)\s*=\s*(.*?)\s*$/.exec(line);
+            if (match === null)
+                continue;
+            const key = match[1];
+            if (key === GHOSTTY_KEY) {
+                const raw = unquote(match[2]).toLowerCase();
+                if (raw === '') {
+                    value = undefined;
+                    source = undefined;
+                }
+                else if (GHOSTTY_VALUES.has(raw)) {
+                    value = raw;
+                    source = path;
+                }
+            }
+            else if (key === 'config-file') {
+                let target = match[2].trim();
+                if (target === '' || target === '""') {
+                    queue = [];
+                    continue;
+                }
+                let isOptional = false;
+                if (target.startsWith('?')) {
+                    isOptional = true;
+                    target = target.slice(1);
+                }
+                target = unquote(target);
+                if (target === '')
+                    continue;
+                const resolved = target.startsWith('~/') ? join(home, target.slice(2)) : isAbsolute(target) ? target : resolve(dirname(path), target);
+                queue.push(`${isOptional ? '?' : ''}${resolved}`);
+            }
+        }
+    };
+    for (const path of paths)
+        load(path, true);
+    while (queue.length > 0) {
+        const next = queue.shift();
+        const optional = next.startsWith('?');
+        const path = optional ? next.slice(1) : next;
+        if (seen.has(path))
+            continue;
+        seen.add(path);
+        load(path, optional);
+    }
+    return { value, source, unreadable };
+}
+/** The effective `macos-option-as-alt` across Ghostty's config files (and their
+ *  `config-file` includes). `undefined` when never assigned. */
+export function readGhosttyOptionSetting(paths, home) {
+    return resolveGhosttyOptionSetting(paths, home).value;
+}
+/** Would appending `lines` to `target` make `macos-option-as-alt = true` the
+ *  effective setting? Evaluates the files as they are now, with the append
+ *  simulated. When not, `blockedBy` names the overriding file. */
+export function appendTakesEffect(paths, target, home = homedir()) {
+    const simulated = (path) => {
+        const text = readTextOrNull(path);
+        return path === target ? `${text ?? ''}\n${GHOSTTY_KEY} = true\n` : text;
+    };
+    const after = resolveGhosttyOptionSetting(paths.includes(target) ? paths : [...paths, target], home, simulated);
+    if (after.value === 'true')
+        return { effective: true, unreadable: after.unreadable };
+    return { effective: false, ...(after.source !== undefined && after.source !== target ? { blockedBy: after.source } : {}), unreadable: after.unreadable };
+}
+/** Scan JSONC for the properties of the top-level object — comments, strings and
+ *  nesting aware, so a key inside `"[markdown]": {…}` is never seen. `undefined`
+ *  when the first token is not `{`. */
+export function scanTopLevelObject(text) {
+    const props = new Map();
+    let i = 0;
+    let depth = 0;
+    let open = -1;
+    let empty = false;
+    let expectKey = false;
+    let key;
+    let expectValue = false;
+    while (i < text.length) {
+        const ch = text[i];
+        const next = text[i + 1];
+        if (/\s/.test(ch)) {
+            i += 1;
+            continue;
+        }
+        if (ch === '/' && next === '/') {
+            while (i < text.length && text[i] !== '\n')
+                i += 1;
+            continue;
+        }
+        if (ch === '/' && next === '*') {
+            const end = text.indexOf('*/', i + 2);
+            i = end === -1 ? text.length : end + 2;
+            continue;
+        }
+        if (open === -1 && ch !== '{')
+            return undefined;
+        let token = ch;
+        let end = i + 1;
+        if (ch === '"') {
+            let j = i + 1;
+            while (j < text.length && text[j] !== '"')
+                j += text[j] === '\\' ? 2 : 1;
+            end = Math.min(j + 1, text.length);
+            token = text.slice(i, end);
+        }
+        else if (!'{}[],:'.includes(ch)) {
+            while (end < text.length && !/[\s,:{}[\]"/]/.test(text[end]))
+                end += 1;
+            token = text.slice(i, end);
+        }
+        if (depth === 1) {
+            if (expectKey && token.startsWith('"')) {
+                try {
+                    key = JSON.parse(token);
+                }
+                catch {
+                    key = token.slice(1, -1);
+                }
+                expectKey = false;
+            }
+            else if (expectKey && token === '}') {
+                // fallthrough to depth handling
+            }
+            else if (key !== undefined && !expectValue && token === ':') {
+                expectValue = true;
+            }
+            else if (expectValue) {
+                props.set(key, token);
+                expectValue = false;
+                key = undefined;
+            }
+            else if (token === ',') {
+                expectKey = true;
+                key = undefined;
+            }
+        }
+        if (ch === '{' || ch === '[') {
+            depth += 1;
+            if (open === -1) {
+                open = i;
+                expectKey = true;
+                let k = end;
+                while (k < text.length) {
+                    if (/\s/.test(text[k]))
+                        k += 1;
+                    else if (text[k] === '/' && text[k + 1] === '/') {
+                        while (k < text.length && text[k] !== '\n')
+                            k += 1;
+                    }
+                    else if (text[k] === '/' && text[k + 1] === '*') {
+                        const e = text.indexOf('*/', k + 2);
+                        k = e === -1 ? text.length : e + 2;
+                    }
+                    else
+                        break;
+                }
+                empty = k >= text.length || text[k] === '}';
+            }
+        }
+        else if (ch === '}' || ch === ']') {
+            depth -= 1;
+            if (depth === 0)
+                break;
+        }
+        i = end;
+    }
+    return open === -1 ? undefined : { open, empty, props };
+}
+/** State of the TOP-LEVEL `terminal.integrated.macOptionIsMeta` in a
+ *  settings.json text. `invalid` = no top-level object; `other` = present with a
+ *  non-boolean value. */
+export function vscodePropertyState(text) {
+    if (text.trim() === '')
+        return 'absent';
+    const scan = scanTopLevelObject(text);
+    if (scan === undefined)
+        return 'invalid';
+    const value = scan.props.get(VSCODE_KEY);
+    if (value === undefined)
+        return 'absent';
+    return value === 'true' ? 'true' : value === 'false' ? 'false' : 'other';
+}
+/** The top-level value of `terminal.integrated.macOptionIsMeta`, or `undefined`
+ *  when it is absent (or not a boolean). */
+export function readVscodeOptionSetting(text) {
+    const state = vscodePropertyState(text);
+    return state === 'true' ? true : state === 'false' ? false : undefined;
+}
+/** The whole file for a settings.json that does not exist (or is blank). */
+export function freshVscodeSettings() {
+    return `{\n  "${VSCODE_KEY}": true\n}\n`;
+}
+/** Insert `"<key>": true` as the first property of the top-level object, leaving
+ *  every other byte (comments, trailing commas, formatting) untouched. A blank
+ *  file becomes a fresh object. Returns `undefined` when the text has no
+ *  recognisable top-level object. */
+export function insertVscodeProperty(text) {
+    if (text.trim() === '')
+        return freshVscodeSettings();
+    const scan = scanTopLevelObject(text);
+    if (scan === undefined)
+        return undefined;
+    const property = `"${VSCODE_KEY}": true`;
+    return `${text.slice(0, scan.open + 1)}\n  ${property}${scan.empty ? '\n' : ','}${text.slice(scan.open + 1)}`;
+}
+function vscodeSettingsPath(home) {
+    return join(home, 'Library', 'Application Support', 'Code', 'User', 'settings.json');
+}
+/** Positively stock VS Code (not Cursor, Windsurf or another fork that also says
+ *  `TERM_PROGRAM=vscode`) — the only case whose settings.json location is certain. */
+function isStockVscode(env) {
+    return [env['VSCODE_GIT_ASKPASS_MAIN'], env['VSCODE_GIT_ASKPASS_NODE']].some((value) => value?.includes('Visual Studio Code') === true);
+}
+const RESTART_NOTE = 'Restart the terminal (or open a new window) afterwards so the setting applies.';
+/** Build the Option-as-Alt plan for this machine. `null` off macOS, where Alt is
+ *  already Alt. */
+export function planOptionAsAlt(input) {
+    if (input.platform !== 'darwin')
+        return null;
+    const { env, home } = input;
+    const terminal = detectTerminal(env);
+    switch (terminal.id) {
+        case 'ghostty': {
+            const paths = ghosttyConfigPaths(env, home);
+            const current = resolveGhosttyOptionSetting(paths, home);
+            if (current.value === 'true' || current.value === 'left' || current.value === 'right') {
+                return {
+                    terminal,
+                    status: 'configured',
+                    summary: current.value === 'true'
+                        ? 'Ghostty already sends Alt for both Option keys (macos-option-as-alt = true).'
+                        : `Ghostty already sends Alt for the ${current.value} Option key only (macos-option-as-alt = ${current.value}) — Alt shortcuts work from that key.`,
+                    instructions: [],
+                };
+            }
+            const existing = paths.filter((path) => existsSync(path));
+            // A new file is `config` — the name every Ghostty version reads.
+            const target = existing.at(-1) ?? join(dirname(paths[0]), 'config');
+            const summary = 'Ghostty types accented characters for Option, so Alt+C will not open the crouter menu yet.';
+            const reload = 'Then reload the config (⌘⇧,) or restart Ghostty.';
+            const check = appendTakesEffect(paths, target, home);
+            if (check.blockedBy !== undefined) {
+                // An include (or a later file) sets the key after anything we could append,
+                // so a written line would silently not take effect.
+                return {
+                    terminal,
+                    status: 'needs-change',
+                    summary,
+                    instructions: [
+                        `${check.blockedBy} sets ${GHOSTTY_KEY} = ${current.value ?? '…'}, and Ghostty loads it after the config files crouter could add to, so crouter will not write a line that would not take effect.`,
+                        `Change that line in ${check.blockedBy} to:`,
+                        `  ${GHOSTTY_KEY} = true`,
+                        reload,
+                    ],
+                };
+            }
+            if (!check.effective || check.unreadable.length > 0) {
+                const where = check.unreadable[0];
+                return {
+                    terminal,
+                    status: 'needs-change',
+                    summary,
+                    instructions: [
+                        where === undefined
+                            ? `crouter could not confirm that a line added to ${target} would take effect.`
+                            : `crouter could not read ${where}, so it cannot confirm a line added to ${target} would take effect.`,
+                        `Add this line to ${target} (after any config-file lines):`,
+                        `  ${GHOSTTY_KEY} = true`,
+                        reload,
+                    ],
+                };
+            }
+            return {
+                terminal,
+                status: 'needs-change',
+                summary,
+                instructions: [`Add this line to ${target}:`, `  ${GHOSTTY_KEY} = true`, reload],
+                edit: {
+                    kind: 'append-lines',
+                    path: target,
+                    lines: ['# crouter: let Option act as Alt (Alt+C opens the crouter menu)', `${GHOSTTY_KEY} = true`],
+                    ghosttyPaths: paths,
+                    reload: 'Reload Ghostty’s config (⌘⇧,) or restart it.',
+                },
+            };
+        }
+        case 'vscode':
+        case 'cursor': {
+            const manual = [
+                `In ${terminal.id === 'cursor' ? 'Cursor' : 'VS Code'}, open Settings (⌘,), search "macOptionIsMeta", and tick`,
+                '"Terminal › Integrated: Mac Option Is Meta" — or in settings.json:',
+                `  "${VSCODE_KEY}": true`,
+                'Then open a new terminal.',
+            ];
+            if (terminal.id === 'vscode' && isStockVscode(env)) {
+                const path = vscodeSettingsPath(home);
+                const text = readTextOrNull(path);
+                const needsChange = {
+                    terminal,
+                    status: 'needs-change',
+                    summary: 'The VS Code terminal types accented characters for Option, so Alt+C will not open the crouter menu yet.',
+                    instructions: manual,
+                    edit: { kind: 'jsonc-insert-property', path, lines: [`"${VSCODE_KEY}": true`], reload: 'Open a new terminal in VS Code.' },
+                };
+                if (text !== null) {
+                    const state = vscodePropertyState(text);
+                    if (state === 'true') {
+                        return { terminal, status: 'configured', summary: `VS Code already treats Option as Meta (${VSCODE_KEY} is true).`, instructions: [] };
+                    }
+                    // An existing top-level `false`/other value, or a file with no top-level
+                    // object, cannot be changed by insertion without duplicating or guessing —
+                    // instructions only.
+                    if (state === 'absent')
+                        return needsChange;
+                }
+                else if (existsSync(path)) {
+                    // Exists but unreadable — leave it alone.
+                }
+                else if (existsSync(dirname(dirname(path)))) {
+                    // No settings.json yet, but this VS Code profile exists (…/Code/User, or
+                    // at least …/Code) — applying creates the file with just this property.
+                    return needsChange;
+                }
+            }
+            return { terminal, status: 'unverified', summary: `${terminal.name} types accented characters for Option unless told otherwise.`, instructions: manual };
+        }
+        case 'terminal-app':
+            return {
+                terminal,
+                status: 'unverified',
+                summary: 'Terminal.app types accented characters for Option unless told otherwise — crouter cannot check this setting.',
+                instructions: [
+                    'Terminal ▸ Settings (⌘,) ▸ Profiles ▸ (your profile) ▸ Keyboard,',
+                    'tick “Use Option as Meta key”. Close the settings window; new keystrokes use it at once.',
+                ],
+            };
+        case 'iterm2':
+            return {
+                terminal,
+                status: 'unverified',
+                summary: 'iTerm2 types accented characters for Option unless told otherwise — crouter cannot check this setting.',
+                instructions: [
+                    'iTerm2 ▸ Settings (⌘,) ▸ Profiles ▸ (your profile) ▸ Keys ▸ General,',
+                    'set “Left Option key” (and “Right Option key” if you use it) to “Esc+”.',
+                ],
+            };
+        case 'wezterm':
+            return {
+                terminal,
+                status: 'unverified',
+                summary: 'WezTerm sends Alt for the LEFT Option key by default; the right one types accents.',
+                instructions: [
+                    'To make the right Option key work too, in ~/.config/wezterm/wezterm.lua add:',
+                    '  config.send_composed_key_when_right_alt_is_pressed = false',
+                ],
+            };
+        case 'kitty':
+            return {
+                terminal,
+                status: 'unverified',
+                summary: 'kitty types accented characters for Option unless told otherwise.',
+                instructions: ['In ~/.config/kitty/kitty.conf add:', '  macos_option_as_alt yes', 'Then restart kitty.'],
+            };
+        case 'alacritty':
+            return {
+                terminal,
+                status: 'unverified',
+                summary: 'Alacritty types accented characters for Option unless told otherwise.',
+                instructions: ['In ~/.config/alacritty/alacritty.toml add:', '  [window]', '  option_as_alt = "Both"', 'Then restart Alacritty.'],
+            };
+        case 'unknown':
+            return {
+                terminal,
+                status: 'unverified',
+                summary: 'crouter could not tell which terminal this is. Most Mac terminals type accented characters for Option unless told otherwise.',
+                instructions: [
+                    'Look in your terminal’s settings for “Option as Alt”, “Option as Meta” or “Esc+”.',
+                    'Terminal.app: Settings ▸ Profiles ▸ Keyboard ▸ “Use Option as Meta key”.',
+                    'iTerm2: Settings ▸ Profiles ▸ Keys ▸ Left/Right Option key ▸ “Esc+”.',
+                    'Ghostty: macos-option-as-alt = true.  kitty: macos_option_as_alt yes.  Alacritty: option_as_alt = "Both".',
+                ],
+            };
+    }
+}
+/** The text a write would produce, exactly, for the confirm page. */
+export function describeEdit(edit) {
+    return [`${edit.path}`, ...edit.lines.map((line) => `  + ${line}`), `  ${edit.reload}`];
+}
+/** Perform one planned edit against the file as it is NOW (never a stale
+ *  snapshot). Idempotent: an already-configured file is left alone. */
+export function applyTerminalEdit(edit) {
+    try {
+        if (edit.kind === 'append-lines') {
+            const existing = readTextOrNull(edit.path) ?? '';
+            const paths = edit.ghosttyPaths ?? [edit.path];
+            const check = appendTakesEffect(paths, edit.path);
+            if (resolveGhosttyOptionSetting(paths).value === 'true')
+                return { ok: true, message: 'already set' };
+            if (!check.effective) {
+                return {
+                    ok: false,
+                    message: check.blockedBy === undefined
+                        ? `could not confirm a line added to ${edit.path} would take effect — add ${GHOSTTY_KEY} = true by hand`
+                        : `${check.blockedBy} overrides ${GHOSTTY_KEY} — change it there by hand`,
+                };
+            }
+            mkdirSync(dirname(edit.path), { recursive: true });
+            const lead = existing === '' || existing.endsWith('\n') ? '' : '\n';
+            const gap = existing === '' ? '' : '\n';
+            appendFileSync(edit.path, `${lead}${gap}${edit.lines.join('\n')}\n`, 'utf8');
+            return { ok: true, message: `appended to ${edit.path}` };
+        }
+        const text = readTextOrNull(edit.path) ?? '';
+        const state = vscodePropertyState(text);
+        if (state === 'true')
+            return { ok: true, message: 'already set' };
+        if (state === 'false' || state === 'other')
+            return { ok: false, message: `${edit.path} sets ${VSCODE_KEY} to a value other than true — change it by hand` };
+        const next = insertVscodeProperty(text);
+        if (next === undefined)
+            return { ok: false, message: `${edit.path} has no top-level object — edit it by hand` };
+        mkdirSync(dirname(edit.path), { recursive: true });
+        writeFileSync(edit.path, next, 'utf8');
+        return { ok: true, message: `${text === '' ? 'created' : 'updated'} ${edit.path}` };
+    }
+    catch (error) {
+        return { ok: false, message: error instanceof Error ? error.message : String(error) };
+    }
+}

package/dist/commands/sys/tutorial/branch.d.ts

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

package/dist/commands/sys/tutorial/branch.js

@@ -0,0 +1,15 @@
+import { defineBranch } from '../../../core/command.js';
+import { basicLeaf } from './tracks.js';
+import { scenarioBranch } from './scenario.js';
+export const tutorialBranch = defineBranch({
+    name: 'tutorial',
+    description: 'guided crouter lessons and disposable practice scenarios',
+    whenToUse: 'you need to learn crouter operation conversationally, one lesson at a time, or create the disposable canvas state a lesson asks you to inspect.',
+    extensible: true,
+    help: {
+        name: 'sys tutorial',
+        summary: 'guided crouter lessons and disposable practice scenarios',
+        model: 'Tracks serve one lesson per invocation and never record progress, so --step can start or resume anywhere. Scenarios create only the temporary canvas state a lesson needs and clean exactly the recorded rows afterward.',
+    },
+    children: [basicLeaf, scenarioBranch],
+});

package/dist/commands/sys/tutorial/lessons.d.ts

@@ -0,0 +1,5 @@
+export interface TutorialLesson {
+    readonly title: string;
+    readonly body: string;
+}
+export declare const BASIC_LESSONS: readonly TutorialLesson[];