@north-light/api 0.3.580 → 0.3.588

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

@@ -0,0 +1,107 @@
+export const BASIC_LESSONS = [
+    {
+        title: 'Return to a conversation — recap, find, pin',
+        body: [
+            'Start with a conversation the user actually wants to return to. `Alt+C` opens the crouter action menu; its entries show the keys, so do not ask the user to memorize a shortcut list.',
+            '',
+            'Ask them to press `Alt+C`. Teach `/menu` alongside it: typing `/menu` in the conversation opens the same action menu without any Alt key, so it is the route to use whenever Option does not work yet (the viewer’s status line shows `Alt+C menu (or /menu)` as a standing reminder). If Option types an accented character instead of opening the menu, identify their terminal and help set Option to send Alt/Esc; show any proposed config edit and get permission before writing it. If they cannot use tmux panes yet, inspect their existing tmux prefix and bindings and teach only the pane actions they need. These are conditional setup steps, not separate lessons.',
+            '',
+            'While Option is in view, teach multiline messages: Enter sends, and `Alt+Enter` (Option+Enter on a Mac) or `Shift+Enter` inserts a new line instead. Have them type a two-line message to confirm it. If Option+Enter sends the message, it is the same Option-as-Alt setting; some terminals do not report Shift+Enter distinctly, so Alt+Enter is the one to rely on.',
+            '',
+            'Have them choose `s` from the menu to refresh this conversation’s Goal/State recap and generated title. Point out the Goal above the transcript and the State above the editor. This generates content using an agent; do not describe it as a free visual toggle. Then open Find node with `Alt+C`, `/`, search for the refreshed title, and select the conversation. The navigator searches conversations across the canvas; the graph in a later lesson is only for nodes connected to the current conversation.',
+            '',
+            'In Find node, have them select this conversation and press `p` to pin it; the star and sorting change. If it was already pinned, do not unpin it merely for practice. A pin persists, so ask before changing it and restore the original state if this is only a demonstration.',
+            '',
+            'Explain the important distinction: closing the viewer or terminal detaches from the conversation; it does not close the node. They can find it again. `Alt+C`, `x` deliberately closes the node and its subtree, so do not use it for detaching. Let them try recap, find, and pin before proceeding.',
+            '',
+            'Close by telling them two things plainly: crouter can debug itself, so whenever something looks broken or stuck they should feel free to ask you to diagnose it; and they can ask you to explain any crouter term (node, canvas, resident, inbox, and so on) the moment it comes up, rather than guessing.',
+        ].join('\n'),
+    },
+    {
+        title: 'Answer an agent — the inbox',
+        body: [
+            'When an agent needs a decision, it can put a question in the human inbox and wait without polling. The answer to an agent’s own question wakes that agent. Teach the habit: if work seems paused, check the inbox with `Alt+I`.',
+            '',
+            'Ask before creating the disposable tutorial question. Once they agree, run:',
+            '',
+            '```bash',
+            'crtr sys tutorial scenario start pending-ask --parent "$CRTR_NODE_ID"',
+            '```',
+            '',
+            'Have them open **A question from the tutorial** with `Alt+I`, select an option with the arrow keys (or `j`/`k`), toggle it with Space, optionally add a comment with `c`, and submit. This question links back to the tutorial conversation but **no agent waits on its answer**; it practices the same inbox controls as a real request. Clean up afterward, even if they decide not to submit:',
+            '',
+            '```bash',
+            'crtr sys tutorial scenario clean pending-ask',
+            '```',
+        ].join('\n'),
+    },
+    {
+        title: 'Review a document with an agent',
+        body: [
+            'Frame this lesson around one idea: a document review is the best way to read and shape anything an agent writes, such as a plan, a spec or a draft. It works like a shared Google Doc that the user and the agent edit together. The document opens in its own window. The user highlights a passage and leaves a comment on it, and an agent in the pane beside the document answers that comment. The agent can also revise the document itself, and the user watches the text change in place. That beats copying passages into chat, because every comment stays attached to the exact lines it is about.',
+            '',
+            'Ask before creating the practice review. Once they agree, run:',
+            '',
+            '```bash',
+            'crtr sys tutorial scenario start review-doc --parent "$CRTR_NODE_ID"',
+            '```',
+            '',
+            'This writes a short practice document, an offsite plan with a vague goal, an agenda step nobody owns and an open question, and queues a review of it. Have them open it from the inbox with `Alt+I`. It opens in a new tmux window, the inbox closes, and the agent pane appears beside the document. Walk them through it one step at a time:',
+            '',
+            '1. Move between blocks with the arrow keys (or `j`/`k`). `J`/`K` widens the highlight to cover several blocks.',
+            '2. Press `c` (or Enter) on something they would change, type a comment, and press Enter to save it. Suggest the vague Goal section. The agent in the side pane picks the comment up and replies or edits the document.',
+            '3. Point out the key bar at the bottom: every key it shows is labeled with what it does, and `?` opens the full list. They do not need to memorize anything.',
+            '4. `C` lists every comment so they can edit or delete one. `s` twice approves and submits the review, and `Esc` leaves it open in the inbox to come back to.',
+            '',
+            'When they submit, the approval comes back to this conversation. Use that moment to say what happens with a real review: the agent sees every comment and every edit, and it carries on from the approved document. Tell them they can ask any agent to “open that for review” whenever it has written something worth reading closely.',
+            '',
+            'Clean up afterward, whether or not they submitted:',
+            '',
+            '```bash',
+            'crtr sys tutorial scenario clean review-doc',
+            '```',
+        ].join('\n'),
+    },
+    {
+        title: 'Make it yours — settings and plugins',
+        body: [
+            'Open `Alt+C`, `,` to inspect settings and keybindings. Let the user find one binding they care about. In the keybinding editor, `/` filters, Enter edits, and Escape discards an unsaved edit. Do not save a binding change unless they ask for that exact change; saved bindings affect their future sessions.',
+            '',
+            'Then use `Alt+C`, `l` to browse plugins. Have them inspect one plugin’s capabilities and decide whether it is relevant to their work. Browsing does not install it. Installing or enabling a plugin changes local configuration, so do that only if they choose a specific plugin and approve the change.',
+            '',
+            'These are discovery tools, not a feature tour: the user should leave knowing how to find a setting or capability when they need it, not with a new configuration they did not request.',
+        ].join('\n'),
+    },
+    {
+        title: 'Take another direction — fork',
+        body: [
+            'Forking lets the user pursue another direction without replacing the original conversation. `Alt+C`, `f` forks the focused node into a separate, idle root. It does not start a model turn; the fork is a new conversation that remains on the canvas until closed.',
+            '',
+            'Ask whether they have a disposable conversation to fork and want to try it. Do not fork the current long-lived conversation just to make a demonstration. If they agree, focus that conversation, use `Alt+C`, `f`, then find both the original and the new root with `Alt+C`, `/`. Confirm which is which before offering to close the disposable fork; closing it is a separate, destructive action that needs permission.',
+            '',
+            'If there is no suitable conversation or they decline to create durable state, explain the action and move on. Mention `/fork` only if they specifically need to choose a point within the conversation; the menu action is enough for this lesson.',
+        ].join('\n'),
+    },
+    {
+        title: 'Keep a useful fact — a document',
+        body: [
+            'The practical instruction is “remember that.” The user does not need to choose a storage format: the agent can propose whether the fact is knowledge about how to do something or a preference about how it should behave, and where that document should apply.',
+            '',
+            'Ask whether there is a genuine, durable fact from their work that they want the agent to remember. State the proposed wording and scope, and get their approval before writing. Do not manufacture a personal preference or save a fact just to complete the exercise. If none exists, let them try the phrase as a future request and move on.',
+            '',
+            'A project fact should not silently become a global preference. The useful outcome is that the user knows they can say “remember that” and correct the proposed wording or scope.',
+        ].join('\n'),
+    },
+    {
+        title: 'Follow delegated work — the graph',
+        body: [
+            'Use a real task with independent parts if one is already underway. Delegation is useful when pieces can run separately or a task has several large phases; do not promote a node or spawn children solely to fill a graph. A small task stays with one agent.',
+            '',
+            'Press `Alt+g` to open the graph of this conversation and its connected nodes. With real children present, → (or `l`) expands a parent or moves to its first child, ↑↓ (or `j`/`k`) select rows, ← (or `h`) moves toward the parent, Enter focuses a child, and Esc closes the graph. Do not use `x`: it asks to close a subtree. If no real children are present, describe these controls briefly and let the user revisit the graph when an agent delegates actual work.',
+            '',
+            'A manager may look idle while its children run. That is expected: it ends its turn and waits for a child’s report, which wakes it to integrate the result. A running broker is not proof that a model turn is streaming; a fault is different from ordinary waiting and needs attention. Explain status only in response to what the user actually sees, not as a glyph glossary.',
+            '',
+            'The visible result should be a user who can open a working child and return to its manager without wondering why the manager stopped speaking. End the tutorial here; promotion, node modes, and lifecycle commands are details to explain only when a real task requires them.',
+        ].join('\n'),
+    },
+];

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

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

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

@@ -0,0 +1,431 @@
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { ApiError } from '../../../api/index.js';
+import { withMetaLock, writeMetaObjectLocked } from '../../../core/canvas/meta-file.js';
+import { defineBranch, defineLeaf } from '../../../core/command.js';
+import { InputError } from '../../../core/io.js';
+import { userScopeRoot } from '../../../core/scope.js';
+import { envNodeId } from '../../../shared/env.js';
+import { cliClient, getNodeOrNull, rethrowAsCliError } from '../../api-client.js';
+const SCENARIOS = {
+    'idle-nodes': {
+        title: 'Three practice children of a tutorial conversation',
+        teaches: 'the graph lesson — navigate a parent and its children',
+        builds: 'three child nodes without tasks under the specified parent; their brokers run until cleanup',
+    },
+    'pending-ask': {
+        title: 'A question waiting in the inbox',
+        teaches: 'the inbox lesson — reading a pending item and answering it',
+        builds: 'one durable pending request in the human inbox',
+    },
+    'review-doc': {
+        title: 'A short practice document waiting for review',
+        teaches: 'the review lesson — commenting on a document alongside an agent',
+        builds: 'one practice document owned by the calling node and one document review of it in the human inbox, with its companion agent',
+    },
+};
+const RECORD_KEYS = ['nodes', 'requests', 'documents', 'reviews'];
+/** Short on purpose, with soft spots worth a comment: a vague goal, an
+ *  unowned step and an open question. */
+const PRACTICE_DOCUMENT = [
+    '# Team offsite plan',
+    '',
+    'A one-day offsite to plan next quarter.',
+    '',
+    '## Goal',
+    '',
+    'Leave with a clear plan for the quarter.',
+    '',
+    '## Agenda',
+    '',
+    '1. Review last quarter — what shipped and what slipped.',
+    '2. Pick the three projects that matter most.',
+    '3. Assign an owner to each project.',
+    '',
+    '## Logistics',
+    '',
+    'Somewhere near the office, sometime next month. Lunch is provided.',
+    '',
+    '## Open questions',
+    '',
+    '- Should remote teammates join by video, or travel in?',
+    '',
+].join('\n');
+const DEMO_PAGE = [
+    'export default function TutorialAsk() {',
+    '  return (',
+    '    <Page title="A question from the tutorial" subtitle="Practice choosing and commenting on an option.">',
+    '      <UserQuestion',
+    '        id="answer"',
+    '        label="Which crouter topics would you like to explore?"',
+    '        body="Select one or more topics with Space and add a comment to an option with c. This is practice; no agent acts on your answer."',
+    '        mode="multi"',
+    '        options={[',
+    "          { id: 'orchestration', label: 'Delegating work to other agents' },",
+    "          { id: 'memory', label: 'Teaching it my preferences' },",
+    "          { id: 'navigation', label: 'Finding conversations and navigating the canvas' },",
+    '        ]}',
+    '      />',
+    '    </Page>',
+    '  );',
+    '}',
+].join('\n');
+function ledgerPath() {
+    return join(userScopeRoot(), 'tutorial-scenarios.json');
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+function readLedger() {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(ledgerPath(), 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return {};
+        throw error;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new InputError({ error: 'invalid_scenario_ledger', message: `tutorial scenario ledger at ${ledgerPath()} must be an object`, next: 'Remove or repair the ledger file, then retry the scenario command.' });
+    }
+    const ledger = {};
+    for (const scenario of Object.keys(SCENARIOS)) {
+        const record = parsed[scenario];
+        if (record === undefined)
+            continue;
+        if (typeof record !== 'object' || record === null || typeof record['started'] !== 'string') {
+            throw new InputError({ error: 'invalid_scenario_ledger', message: `tutorial scenario ledger has an invalid ${scenario} record`, next: 'Remove or repair the ledger file, then retry the scenario command.' });
+        }
+        const raw = record;
+        if (RECORD_KEYS.some((key) => raw[key] !== undefined && !isStringArray(raw[key]))) {
+            throw new InputError({ error: 'invalid_scenario_ledger', message: `tutorial scenario ledger has invalid ids for ${scenario}`, next: 'Remove or repair the ledger file, then retry the scenario command.' });
+        }
+        const parsedRecord = { started: raw['started'] };
+        for (const key of RECORD_KEYS)
+            if (raw[key] !== undefined)
+                parsedRecord[key] = raw[key];
+        ledger[scenario] = parsedRecord;
+    }
+    return ledger;
+}
+function withLedger(operation) {
+    const path = ledgerPath();
+    mkdirSync(dirname(path), { recursive: true });
+    return withMetaLock(path, () => operation(readLedger()));
+}
+function updateLedger(operation) {
+    const path = ledgerPath();
+    mkdirSync(dirname(path), { recursive: true });
+    return withMetaLock(path, () => {
+        const ledger = readLedger();
+        const result = operation(ledger);
+        writeMetaObjectLocked(path, ledger);
+        return result;
+    });
+}
+function reserveScenario(id) {
+    return updateLedger((ledger) => {
+        if (ledger[id] !== undefined) {
+            throw new InputError({
+                error: 'scenario_already_standing',
+                message: `the '${id}' scenario is already standing (started ${ledger[id].started})`,
+                field: 'scenario',
+                next: `Run \`crtr sys tutorial scenario clean ${id}\` first, then start it again.`,
+            });
+        }
+        const record = {
+            started: new Date().toISOString(),
+            ...(id === 'idle-nodes' ? { nodes: [] } : id === 'pending-ask' ? { requests: [] } : { documents: [], reviews: [] }),
+        };
+        ledger[id] = record;
+        return record;
+    });
+}
+async function appendScenarioId(id, key, value) {
+    const appended = updateLedger((ledger) => {
+        const record = ledger[id];
+        if (record === undefined)
+            return false;
+        record[key] = [...(record[key] ?? []), value];
+        return true;
+    });
+    if (appended)
+        return;
+    try {
+        if (key === 'nodes')
+            await cliClient().closeNode(value);
+        else if (key === 'requests')
+            await cliClient().cancelHumanRequest(value, { reason: 'Tutorial scenario start interrupted.' });
+        else if (key === 'reviews')
+            await cliClient().cancelReview(value, { reason: 'Tutorial scenario start interrupted.' });
+        else
+            await cliClient().docs.delete(value);
+    }
+    catch (error) {
+        if (!isAlreadyCleaned(error))
+            rethrowAsCliError(error);
+    }
+    throw new Error(`tutorial scenario '${id}' disappeared while it was starting`);
+}
+function isAlreadyCleaned(error) {
+    return error instanceof ApiError && (error.status === 404 || error.code === 'already_settled');
+}
+function isTerminalNode(status) {
+    return status === 'done' || status === 'dead' || status === 'canceled';
+}
+function scenario(input) {
+    const id = input['scenario'];
+    if (typeof id === 'string' && Object.hasOwn(SCENARIOS, id))
+        return id;
+    throw new InputError({
+        error: 'unknown_scenario',
+        message: `no tutorial scenario named '${String(id)}'`,
+        field: 'scenario',
+        next: `Use one of: ${Object.keys(SCENARIOS).join(', ')}. Run \`crtr sys tutorial scenario list\` for what each one builds.`,
+    });
+}
+async function startIdleNodes(record, parent) {
+    const names = ['tutorial-demo-one', 'tutorial-demo-two', 'tutorial-demo-three'];
+    for (const name of names) {
+        const created = await cliClient().createNode({
+            parent,
+            creator: parent,
+            root_lifecycle: 'resident',
+            no_kickoff: true,
+            prompt: '',
+            cwd: process.cwd(),
+            name,
+        }).catch(rethrowAsCliError);
+        await appendScenarioId('idle-nodes', 'nodes', created.node_id);
+        record.nodes.push(created.node_id);
+    }
+}
+async function startPendingAsk(record, parent) {
+    const created = await cliClient().createHumanRequest({
+        page: { dialect: 'jsx', source: DEMO_PAGE },
+        delivery: { placement: 'inline', inbox: true, reply: false },
+        source: { askedBy: 'crtr sys tutorial', sessionName: 'tutorial', nodeId: parent },
+        creator_cwd: process.cwd(),
+    }).catch(rethrowAsCliError);
+    await appendScenarioId('pending-ask', 'requests', created.request_id);
+    record.requests.push(created.request_id);
+}
+/** The practice document is owned by the calling node (the tutorial
+ *  conversation), so the review's companion is a fork of that conversation and
+ *  its approval wakes the tutorial agent to debrief. */
+async function startReviewDoc(record, parent) {
+    const written = await cliClient().docs.write({
+        name: `tutorial-review-practice-${Date.now().toString(36)}`,
+        body: PRACTICE_DOCUMENT,
+        preview: 'A short practice plan for the crouter tutorial’s document-review lesson; safe to delete.',
+        unlisted: true,
+        cwd: process.cwd(),
+    }).catch(rethrowAsCliError);
+    await appendScenarioId('review-doc', 'documents', written.name);
+    record.documents.push(written.name);
+    const review = await cliClient().createReview({
+        origin_kind: 'ticket',
+        origin_node_id: parent,
+        document: written.name,
+        idempotency_key: randomUUID(),
+        subtitle: 'Practice reviewing a document with an agent: comment on anything, then approve.',
+    }).catch(rethrowAsCliError);
+    await appendScenarioId('review-doc', 'reviews', review.review_id);
+    record.reviews.push(review.review_id);
+}
+const scenarioListLeaf = defineLeaf({
+    name: 'list',
+    description: 'list the tutorial practice scenarios',
+    whenToUse: 'you need to choose a disposable canvas scenario for a lesson or see whether one is already standing.',
+    help: {
+        name: 'sys tutorial scenario list',
+        summary: 'list the tutorial practice scenarios and their standing state',
+        inputNote: 'No input parameters.',
+        output: [
+            { name: 'scenarios', type: 'object[]', required: true, constraint: 'One row per scenario: {id, title, teaches, builds, standing}.' },
+            { name: 'standing', type: 'number', required: true, constraint: 'Number of scenarios currently recorded as standing.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async () => {
+        const ledger = withLedger((current) => current);
+        const scenarios = Object.entries(SCENARIOS).map(([id, def]) => ({
+            id,
+            title: def.title,
+            teaches: def.teaches,
+            builds: def.builds,
+            standing: ledger[id] !== undefined,
+        }));
+        return { scenarios, standing: scenarios.filter((item) => item.standing).length };
+    },
+});
+const scenarioStartLeaf = defineLeaf({
+    name: 'start',
+    description: 'create a tutorial practice scenario',
+    whenToUse: 'a tutorial lesson needs its disposable graph rows or inbox request before the user can practice against a real canvas surface.',
+    help: {
+        name: 'sys tutorial scenario start',
+        summary: 'create one tutorial practice scenario',
+        params: [
+            { kind: 'positional', name: 'scenario', type: 'string', required: true, constraint: 'idle-nodes (three children without tasks), pending-ask (one durable inbox request) or review-doc (a practice document and a review of it).' },
+            { kind: 'flag', name: 'parent', type: 'string', required: true, constraint: 'Node id of the tutorial conversation; children, the inbox request and the review are linked to this node. For review-doc it must be the calling node.' },
+        ],
+        output: [
+            { name: 'nodes', type: 'string[]', required: false, constraint: 'Created child node ids for idle-nodes.' },
+            { name: 'requests', type: 'string[]', required: false, constraint: 'Created human request ids for pending-ask.' },
+            { name: 'documents', type: 'string[]', required: false, constraint: 'Created practice document names for review-doc.' },
+            { name: 'reviews', type: 'string[]', required: false, constraint: 'Created review ids for review-doc.' },
+            { name: 'clean_with', type: 'string', required: true, constraint: 'Exact command that removes this scenario.' },
+            { name: 'look_at', type: 'string', required: true, constraint: 'Viewer surface that shows the created state.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'idle-nodes creates three resident children of --parent with no kickoff turn; their brokers run until cleanup. Their ids are recorded in ~/.crouter/tutorial-scenarios.json.',
+            'pending-ask publishes one durable human request with --parent as its source; answering it does not wake that node. Its id is recorded in ~/.crouter/tutorial-scenarios.json.',
+            'review-doc writes one unlisted practice document owned by the calling node and queues a document review of it with --parent as origin: a companion agent forked from --parent joins the review, and submitting it pushes the approval to --parent. Both ids are recorded in ~/.crouter/tutorial-scenarios.json.',
+            'Refuses a scenario already recorded as standing; clean it before starting it again.',
+        ],
+    },
+    run: async (input) => {
+        const id = scenario(input);
+        const parent = input['parent'];
+        if (parent === undefined || parent.trim() === '') {
+            throw new InputError({ error: 'parent_required', message: `${id} needs the tutorial conversation node id in --parent`, field: 'parent', next: 'Pass the node id of the conversation the user is viewing.' });
+        }
+        if (await getNodeOrNull(parent) === null) {
+            throw new InputError({ error: 'unknown_parent', message: `no local node exists for --parent ${parent}`, field: 'parent', next: 'Pass the node id of a conversation on this canvas.' });
+        }
+        if (id === 'review-doc' && envNodeId() !== parent) {
+            throw new InputError({ error: 'parent_not_caller', message: 'review-doc writes the practice document as the calling node, so --parent must be that node', field: 'parent', next: 'Run it from the tutorial conversation with --parent "$CRTR_NODE_ID".' });
+        }
+        const record = reserveScenario(id);
+        if (id === 'idle-nodes')
+            await startIdleNodes(record, parent);
+        else if (id === 'pending-ask')
+            await startPendingAsk(record, parent);
+        else
+            await startReviewDoc(record, parent);
+        const out = {};
+        for (const key of RECORD_KEYS)
+            if (record[key] !== undefined)
+                out[key] = record[key];
+        return {
+            ...out,
+            clean_with: `crtr sys tutorial scenario clean ${id}`,
+            look_at: id === 'idle-nodes'
+                ? 'Open the graph with `Alt+g`.'
+                : id === 'pending-ask'
+                    ? 'Open the inbox with `Alt+I`.'
+                    : 'Open the inbox with `Alt+I` and select the review; it opens in its own window.',
+        };
+    },
+});
+const scenarioCleanLeaf = defineLeaf({
+    name: 'clean',
+    description: 'remove a tutorial practice scenario',
+    whenToUse: 'the lesson has finished with a scenario and you need to remove exactly the nodes or request it recorded.',
+    help: {
+        name: 'sys tutorial scenario clean',
+        summary: 'remove exactly the rows recorded for one tutorial practice scenario',
+        params: [
+            { kind: 'positional', name: 'scenario', type: 'string', required: true, constraint: 'Scenario to remove: idle-nodes, pending-ask or review-doc.' },
+        ],
+        output: [
+            { name: 'was_standing', type: 'boolean', required: true, constraint: 'Whether this scenario had a ledger record to remove.' },
+            { name: 'closed_nodes', type: 'number', required: false, constraint: 'Number of ledger-recorded node ids closed. Present when the scenario was standing.' },
+            { name: 'canceled_requests', type: 'number', required: false, constraint: 'Number of ledger-recorded request ids canceled. Present when the scenario was standing.' },
+            { name: 'already_settled_requests', type: 'number', required: false, constraint: 'Number of ledger-recorded request or review ids already terminal when clean processed them. Present when the scenario was standing.' },
+            { name: 'deleted_documents', type: 'number', required: false, constraint: 'Number of ledger-recorded practice documents deleted. Present when the scenario was standing.' },
+        ],
+        outputKind: 'object',
+        effects: ['Closes, cancels or deletes only ids recorded for this scenario in ~/.crouter/tutorial-scenarios.json, then removes that scenario record. A review is canceled before its practice document is deleted.'],
+    },
+    run: async (input) => {
+        const id = scenario(input);
+        const standing = withLedger((ledger) => ledger[id]);
+        if (standing === undefined)
+            return { was_standing: false };
+        let closedNodes = 0;
+        let canceledRequests = 0;
+        let alreadySettledRequests = 0;
+        for (const nodeId of standing.nodes ?? []) {
+            const node = await getNodeOrNull(nodeId);
+            if (node === null || isTerminalNode(node.status))
+                continue;
+            try {
+                await cliClient().closeNode(nodeId);
+                closedNodes++;
+            }
+            catch (error) {
+                if (!isAlreadyCleaned(error))
+                    rethrowAsCliError(error);
+            }
+        }
+        for (const requestId of standing.requests ?? []) {
+            try {
+                await cliClient().cancelHumanRequest(requestId, { reason: 'Tutorial scenario cleaned up.' });
+                canceledRequests++;
+            }
+            catch (error) {
+                if (error instanceof ApiError && error.code === 'already_settled') {
+                    alreadySettledRequests++;
+                }
+                else if (!isAlreadyCleaned(error)) {
+                    rethrowAsCliError(error);
+                }
+            }
+        }
+        for (const reviewId of standing.reviews ?? []) {
+            try {
+                const result = await cliClient().cancelReview(reviewId, { reason: 'Tutorial scenario cleaned up.' });
+                if (result.outcome === 'already_settled')
+                    alreadySettledRequests++;
+                else
+                    canceledRequests++;
+            }
+            catch (error) {
+                if (error instanceof ApiError && (error.code === 'already_settled' || error.code === 'review_terminal_conflict')) {
+                    alreadySettledRequests++;
+                }
+                else if (!isAlreadyCleaned(error)) {
+                    rethrowAsCliError(error);
+                }
+            }
+        }
+        let deletedDocuments = 0;
+        for (const document of standing.documents ?? []) {
+            try {
+                await cliClient().docs.delete(document);
+                deletedDocuments++;
+            }
+            catch (error) {
+                if (!isAlreadyCleaned(error))
+                    rethrowAsCliError(error);
+            }
+        }
+        updateLedger((ledger) => {
+            delete ledger[id];
+        });
+        return {
+            was_standing: true,
+            closed_nodes: closedNodes,
+            canceled_requests: canceledRequests,
+            ...(standing.documents === undefined ? {} : { deleted_documents: deletedDocuments }),
+            ...(alreadySettledRequests === 0 ? {} : { already_settled_requests: alreadySettledRequests }),
+        };
+    },
+});
+export const scenarioBranch = defineBranch({
+    name: 'scenario',
+    description: 'create and remove disposable tutorial practice state',
+    whenToUse: 'a tutorial lesson needs real but disposable canvas rows or an inbox request to inspect and practice against.',
+    help: {
+        name: 'sys tutorial scenario',
+        summary: 'create and remove disposable canvas state for tutorial lessons',
+        model: 'Each scenario records only the ids it creates. Start refuses an already-standing scenario, and clean acts only on that recorded list.',
+    },
+    children: [scenarioListLeaf, scenarioStartLeaf, scenarioCleanLeaf],
+});

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

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

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

@@ -0,0 +1,96 @@
+import { defineLeaf } from '../../../core/command.js';
+import { InputError } from '../../../core/io.js';
+import { BASIC_LESSONS } from './lessons.js';
+const TEACHING_CONTRACT = [
+    'Teach this conversationally, in your own words — do not paste this lesson at the user.',
+    'Ask before you change anything on their machine, and show the exact diff you propose.',
+    'Let the user actually try each thing and confirm it worked before you move on.',
+].join(' ');
+const TRACKS = {
+    basic: BASIC_LESSONS,
+};
+function tableOfContents(lessons) {
+    return lessons.map((lesson, index) => `${index + 1}. ${lesson.title}`).join('\n');
+}
+async function tutorialListing() {
+    const { resolveRoot } = await import('../../../build-root.js');
+    const root = await resolveRoot('sys');
+    const sys = root.subtrees.find((subtree) => subtree.name === 'sys');
+    if (sys?.kind !== 'branch')
+        throw new Error('The assembled sys subtree is missing.');
+    const tutorial = sys.children.find((child) => child.name === 'tutorial');
+    if (tutorial?.kind !== 'branch')
+        throw new Error('The assembled sys tutorial branch is missing.');
+    if (tutorial.help.listing === undefined)
+        throw new Error('The assembled sys tutorial listing is missing.');
+    return tutorial.help.listing;
+}
+function nextTracksLine(nextTracks) {
+    if (nextTracks.length === 0)
+        return 'That is the whole tutorial.';
+    return `What's next: ${nextTracks.map(({ command, description }) => `${command} — ${description}`).join('; ')}`;
+}
+async function runTrack(track, input) {
+    const lessons = TRACKS[track];
+    const total = lessons.length;
+    const raw = input['step'];
+    const step = raw === undefined || raw === null ? 1 : Number(raw);
+    if (!Number.isInteger(step) || step < 1 || step > total) {
+        throw new InputError({
+            error: 'step_out_of_range',
+            message: `--step must be between 1 and ${total} (got ${String(raw)})`,
+            field: 'step',
+            next: `Run \`crtr sys tutorial ${track} -h\` and read the contents, then pick a lesson in range.`,
+        });
+    }
+    const lesson = lessons[step - 1];
+    const next = step < total ? `crtr sys tutorial ${track} --step ${step + 1}` : undefined;
+    const listing = next === undefined ? await tutorialListing() : undefined;
+    let nextTracks;
+    if (listing !== undefined) {
+        const pluginTracks = listing
+            .filter((child) => child.plugin !== undefined)
+            .map((child) => ({ command: `crtr sys tutorial ${child.name}`, description: child.description }));
+        nextTracks = pluginTracks;
+    }
+    return {
+        track,
+        step,
+        total,
+        title: lesson.title,
+        body: nextTracks === undefined ? lesson.body : `${lesson.body}\n\n${nextTracksLine(nextTracks)}`,
+        ...(next === undefined ? {} : { next }),
+        teaching_contract: TEACHING_CONTRACT,
+        ...(step === 1 ? { contents: tableOfContents(lessons) } : {}),
+        ...(nextTracks === undefined ? {} : { next_tracks: nextTracks }),
+    };
+}
+function trackLeaf(track, description, whenToUse) {
+    return defineLeaf({
+        name: track,
+        description,
+        whenToUse,
+        help: {
+            name: `sys tutorial ${track}`,
+            summary: `serve one lesson from the ${track} crouter tutorial track`,
+            params: [
+                { kind: 'flag', name: 'step', type: 'int', required: false, default: 1, constraint: `Lesson number, from 1 through ${TRACKS[track].length}. Default: 1.` },
+            ],
+            output: [
+                { name: 'track', type: 'string', required: true, constraint: `The served track: ${track}.` },
+                { name: 'step', type: 'number', required: true, constraint: 'The served lesson number.' },
+                { name: 'total', type: 'number', required: true, constraint: 'Number of lessons in this track.' },
+                { name: 'title', type: 'string', required: true, constraint: 'Lesson title.' },
+                { name: 'body', type: 'string', required: true, constraint: 'Lesson instructions for the teaching agent.' },
+                { name: 'next', type: 'string', required: false, constraint: 'The exact command for the next lesson. Absent on the last lesson.' },
+                { name: 'teaching_contract', type: 'string', required: true, constraint: 'Rules for teaching the lesson conversationally and safely.' },
+                { name: 'contents', type: 'string', required: false, constraint: 'Numbered titles for every lesson in this track. Present only for step 1.' },
+                { name: 'next_tracks', type: 'array', required: false, constraint: 'Available core and plugin tutorial tracks, each with command and description. Present only on the last lesson.' },
+            ],
+            outputKind: 'object',
+            effects: ['None. Read-only. Progress is not stored.'],
+        },
+        run: async (input) => runTrack(track, input),
+    });
+}
+export const basicLeaf = trackLeaf('basic', 'serve one task-first crouter lesson', 'you want to learn everyday crouter actions, from returning to a conversation through following delegated work.');

package/dist/commands/sys/update.d.ts

@@ -0,0 +1,2 @@
+export declare const sysUpdateLeaf: import("../../core/command.js").LeafDef;
+export declare const sysVersionLeaf: import("../../core/command.js").LeafDef;