@reticlehq/server 2.14.0 → 3.2.0

package/dist/command/cli/status/status-lines.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `reticle status`, rendered for a person.
+ *
+ * The command printed one line of JSON and nothing else. Its own source called it "the second-most
+ * run command and the one a HUMAN types" — and the answer to that human was
+ * `{"t":"…","event":"reticle_status","port":4400,"running":true,…}`. It is worse than that now that
+ * agents run it: an agent's terminal output is read by the person sitting behind it, so a machine
+ * line is a line two readers have to decode and only one of them can.
+ *
+ * The JSON stays, unchanged, on stderr — it is documented, and it is what a log is for. This is the
+ * same facts on stdout, in the shape `doctor` already uses, so the two commands read as one tool.
+ *
+ * Pure, and tolerant: it is handed the very object the log line is built from, narrows it without
+ * trusting it, and prints what it can recognise. A status that cannot be rendered must still be
+ * logged, so nothing here may throw.
+ */
+/** Every row label this block can print. The one spelling; nothing writes a label inline. */
+export declare const StatusLabel: {
+    readonly DAEMON: "daemon";
+    readonly SESSIONS: "sessions";
+    readonly AGENT_LINK: "agent link";
+    readonly NEXT: "next";
+    readonly SPLIT_BRAIN: "split brain";
+    readonly UPDATE: "update";
+};
+export type StatusLabel = (typeof StatusLabel)[keyof typeof StatusLabel];
+/** The block to print on stdout, one string per line, heading first. */
+export declare function statusLines(fields: Record<string, unknown>): string[];

package/dist/command/cli/status/status-lines.js

@@ -0,0 +1,117 @@
+/**
+ * `reticle status`, rendered for a person.
+ *
+ * The command printed one line of JSON and nothing else. Its own source called it "the second-most
+ * run command and the one a HUMAN types" — and the answer to that human was
+ * `{"t":"…","event":"reticle_status","port":4400,"running":true,…}`. It is worse than that now that
+ * agents run it: an agent's terminal output is read by the person sitting behind it, so a machine
+ * line is a line two readers have to decode and only one of them can.
+ *
+ * The JSON stays, unchanged, on stderr — it is documented, and it is what a log is for. This is the
+ * same facts on stdout, in the shape `doctor` already uses, so the two commands read as one tool.
+ *
+ * Pure, and tolerant: it is handed the very object the log line is built from, narrows it without
+ * trusting it, and prints what it can recognise. A status that cannot be rendered must still be
+ * logged, so nothing here may throw.
+ */
+/** Every row label this block can print. The one spelling; nothing writes a label inline. */
+export const StatusLabel = {
+    DAEMON: 'daemon',
+    SESSIONS: 'sessions',
+    AGENT_LINK: 'agent link',
+    NEXT: 'next',
+    SPLIT_BRAIN: 'split brain',
+    UPDATE: 'update',
+};
+const LABELS = Object.values(StatusLabel);
+/** The heading, so a reader can tell which command produced the block. */
+const HEADING = 'reticle status';
+const INDENT = '  ';
+/** Padded off the longest label, for the same reason `doctor` does it: the column IS the legibility. */
+const LABEL_COLUMN = LABELS.reduce((widest, l) => Math.max(widest, l.length), 0) + 2;
+const OK = '✓';
+const NOT_OK = '✗';
+function row(label, rest) {
+    return `${INDENT}${label.padEnd(LABEL_COLUMN)}${rest}`;
+}
+/** A continuation line under a row: indented past the label column, carrying no label of its own. */
+function continuation(rest) {
+    return `${INDENT}${' '.repeat(LABEL_COLUMN)}${rest}`;
+}
+function str(fields, key) {
+    const v = fields[key];
+    return 'string' === typeof v && v.length > 0 ? v : undefined;
+}
+function num(fields, key) {
+    const v = fields[key];
+    return 'number' === typeof v ? v : undefined;
+}
+function sessionViews(fields) {
+    const raw = fields['sessions'];
+    if (!Array.isArray(raw))
+        return [];
+    return raw.flatMap((s) => {
+        if ('object' !== typeof s || null === s)
+            return [];
+        const r = s;
+        // Each of these explains something a reader would otherwise call a bug: a throttled or hidden
+        // tab answers slowly, a stale one answers about a page that has moved on, and an unresponsive
+        // one does not answer at all.
+        const notes = [
+            true === r['throttled'] ? 'throttled' : undefined,
+            true === r['hidden'] ? 'hidden' : undefined,
+            true === r['stale'] ? 'stale' : undefined,
+            true === r['unresponsive'] ? 'unresponsive' : undefined,
+        ].filter((n) => n !== undefined);
+        return [{ url: str(r, 'url') ?? '(no url reported)', notes }];
+    });
+}
+/** The block to print on stdout, one string per line, heading first. */
+export function statusLines(fields) {
+    const port = num(fields, 'port');
+    const at = port === undefined ? '' : ` on :${String(port)}`;
+    const pid = num(fields, 'pid');
+    const running = true === fields['running'];
+    const lines = [HEADING];
+    lines.push(row(StatusLabel.DAEMON, running
+        ? `${OK} running${at}${pid === undefined ? '' : ` (pid ${String(pid)})`}`
+        : `${NOT_OK} not running${at}`));
+    // What was actually ON the port, when the pid file said nothing useful. "A stranger holds this"
+    // and "nothing is here" were the same output once, and the true sentence was said by nothing a
+    // person sees — so the word belongs in the prose, not only in the event.
+    const presence = str(fields, 'presence');
+    if (presence !== undefined)
+        lines.push(continuation(`port presence: ${presence}`));
+    // The refusal a FOREIGN port produces. It is the whole answer when it is present, so it rides the
+    // daemon row rather than waiting for a `next` that is not built in that branch.
+    const reason = str(fields, 'reason');
+    if (reason !== undefined)
+        lines.push(continuation(reason));
+    if (running) {
+        const count = num(fields, 'sessionCount') ?? 0;
+        lines.push(row(StatusLabel.SESSIONS, count > 0
+            ? `${OK} ${String(count)} page${1 === count ? '' : 's'} connected`
+            : `${NOT_OK} no page connected`));
+        for (const s of sessionViews(fields)) {
+            lines.push(continuation(`${s.url}${0 === s.notes.length ? '' : `  (${s.notes.join(', ')})`}`));
+        }
+        // The daemon's own explanation for an empty session list, which outranks anything this command
+        // could infer — it is the one holding the connection.
+        const why = str(fields, 'why');
+        if (why !== undefined)
+            lines.push(continuation(why));
+    }
+    const client = str(fields, 'mcpClient');
+    if (client !== undefined)
+        lines.push(row(StatusLabel.AGENT_LINK, client));
+    for (const [label, key] of [
+        [StatusLabel.NEXT, 'nextAction'],
+        [StatusLabel.SPLIT_BRAIN, 'splitBrain'],
+        [StatusLabel.UPDATE, 'updateAvailable'],
+    ]) {
+        const value = str(fields, key);
+        if (value !== undefined)
+            lines.push(row(label, value));
+    }
+    return lines;
+}

package/dist/command/cli/status-fields.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The two optional blocks `status` adds to its payload, out of cli.ts because that file hit the
+ * 1000-line cap and the rule is to split rather than raise it.
+ *
+ * They belong together: both answer "is there anything else the reader needs to know", both are
+ * absent when the answer is no, and both are the reason a healthy `status` reads as healthy.
+ */
+/** `{ nextAction }` when there is one, `{}` when a session is connected — so the success case is silent. */
+export declare function withNextAction(facts: {
+    running: boolean;
+    sessionCount: number;
+    previouslyConnected: boolean;
+    projectPreviouslyConnected: boolean;
+    initialized: boolean;
+    devServerPorts?: readonly number[];
+}): {
+    nextAction?: string;
+};
+/**
+ * What `status` says about a project whose daemons have split in two.
+ *
+ * Both halves in one place because they are one condition asked from two positions, and a command
+ * can be standing on either. Silent — no key at all — when there is nothing to report, so a healthy
+ * run reads exactly as it did.
+ */
+export declare function splitBrainFields(port: number, projectId: string | undefined): {
+    splitBrain?: string;
+};

package/dist/command/cli/status-fields.js

@@ -0,0 +1,29 @@
+import { statusNextAction } from './answers/status-next-action.js';
+import { daemonsServingProjectElsewhere, resolveDaemonForProject, splitBrainNote, wrongDaemonNote, } from '../daemon/daemon-resolve.js';
+import { isAlive, reticleStateHome } from '../daemon/daemon.js';
+import { hasProjectConnectedBefore } from '../../memory/recall/prior/connection-memory.js';
+/**
+ * The two optional blocks `status` adds to its payload, out of cli.ts because that file hit the
+ * 1000-line cap and the rule is to split rather than raise it.
+ *
+ * They belong together: both answer "is there anything else the reader needs to know", both are
+ * absent when the answer is no, and both are the reason a healthy `status` reads as healthy.
+ */
+/** `{ nextAction }` when there is one, `{}` when a session is connected — so the success case is silent. */
+export function withNextAction(facts) {
+    const next = statusNextAction(facts);
+    return next === undefined ? {} : { nextAction: next };
+}
+/**
+ * What `status` says about a project whose daemons have split in two.
+ *
+ * Both halves in one place because they are one condition asked from two positions, and a command
+ * can be standing on either. Silent — no key at all — when there is nothing to report, so a healthy
+ * run reads exactly as it did.
+ */
+export function splitBrainFields(port, projectId) {
+    const home = reticleStateHome();
+    const elsewhere = splitBrainNote(port, daemonsServingProjectElsewhere(projectId, port, home, isAlive, (other) => hasProjectConnectedBefore(home, other, projectId)));
+    const note = elsewhere ?? wrongDaemonNote(port, resolveDaemonForProject(projectId, home, isAlive));
+    return note === undefined ? {} : { splitBrain: note };
+}

package/dist/command/cli/tutorial.d.ts

@@ -0,0 +1,116 @@
+/**
+ * The tutorial: one sequence, two audiences.
+ *
+ * A human wants to know what to do next and why it is worth doing. An agent wants the exact call and
+ * the exact shape of the answer, because prose it has to interpret is a turn it has to spend. Write
+ * for one and hope the other copes, and you get a page agents skip and humans skim.
+ *
+ * What both MUST share is the order. Two audiences taking different routes through one product is
+ * how a support answer stops matching what anybody actually did.
+ *
+ * The sequence is not arbitrary either. It ends at a VERDICT because a tour that ends at "you can see
+ * the page now" has taught the least valuable half: looking is not verifying, and an agent that
+ * learns only to look will report that it looked. And it declares the consequence BEFORE acting,
+ * because that ordering IS the idea — naming what should happen first is the difference between a
+ * check and a rationalisation written afterwards.
+ */
+import { type OnboardingStep } from '@reticlehq/core/telemetry';
+/**
+ * The two ONBOARD steps a SHOWN tour can honestly answer.
+ *
+ * Here rather than in `command/cli-onboarding.ts`, because both callers live on this side of that
+ * line: `cli/setup-mcp-cli.ts` shows the tour when a person is watching, and reaching back into
+ * `command/` for the step names made `cli <-> command` a mutual pair — which `directory-reach`
+ * refused, with the right advice: the thing being reached for was simply filed in the wrong place.
+ * `command/` importing from `cli/` is the direction that already exists.
+ *
+ * The tour RENDERS; it does not run anything. So it knows the tour was asked for and the concept
+ * was put in front of somebody, and nothing about whether they then looked, acted or proved. The
+ * remaining three ONBOARD steps are observed by the daemon at the first look, act and verdict,
+ * which is the only place they are a fact.
+ */
+export declare function tutorialShownSteps(): OnboardingStep[];
+export declare const TutorialAudience: {
+    /** Prose, and a reason per step. */
+    readonly HUMAN: "human";
+    /** The call, and what comes back. */
+    readonly AGENT: "agent";
+};
+export type TutorialAudience = (typeof TutorialAudience)[keyof typeof TutorialAudience];
+export interface TutorialStep {
+    id: string;
+    /** What this step is, in words. Always present: an agent reading only calls learns the what, not the why. */
+    say: string;
+    /** Why it is worth doing. The half that stops a tutorial being a list of keystrokes. */
+    why: string;
+    /** The exact call, for the audience that would otherwise have to infer it from the prose. */
+    call?: string;
+}
+/**
+ * The same steps, shaped for who is reading.
+ *
+ * The agent form keeps the prose as well as the call. An agent that has only the call learns what to
+ * type and not what it means, which is exactly the reader that later reports a green it cannot
+ * explain.
+ */
+export declare function tutorialScript(audience: TutorialAudience): TutorialStep[];
+/**
+ * The script as text for whoever asked.
+ *
+ * A human gets the reason on its own line, because the reason is what makes the step worth doing and
+ * a list of commands without them is a keystroke tour. An agent gets the call, because prose it has
+ * to interpret is a turn it has to spend — and it gets the prose too, since an agent that has only
+ * the call learns what to type and not what it means, which is the reader that later reports a green
+ * it cannot explain.
+ */
+/**
+ * What to do now the tour is over.
+ *
+ * Every other stage of setup ends by naming the next command — `install.sh` points at `reticle init`
+ * and this tutorial, `init` points at the dev server and `status`. This one ended at step 4 and
+ * stopped, so the stage whose entire job is to teach the sequence was the only one that never said
+ * how to start it. The steps above describe tools that need an instrumented, running app, and a
+ * reader who has just been told that a verdict is the point and shown no way to reach one is exactly
+ * where a funnel stalls.
+ *
+ * Split from `renderTutorial` so the closing block is a value a caller can assert on, rather than a
+ * string only findable by matching rendered prose.
+ */
+export declare function tutorialNextSteps(audience: TutorialAudience): string;
+/**
+ * What the installer prints when it has finished.
+ *
+ * Installation and onboarding are ONE script, so the tour is not conditional on anything. Gating it
+ * on `process.stdout.isTTY` does not work: that is `undefined` through every pipe, so the tour never
+ * prints. A heuristic that silently answers "nobody is watching" is worse than no heuristic.
+ *
+ * It ends with the tour's OWN closing, which already names `reticle init`. Adding a second "Next:"
+ * under it would be the same instruction twice in ten lines.
+ */
+export declare function installClosing(): string;
+export declare function renderTutorial(audience: TutorialAudience): string;
+export type DemoPlan = {
+    ok: true;
+    ref: string;
+    name: string;
+    call: string;
+} | {
+    ok: false;
+    because: string;
+};
+/**
+ * Pick something safe on THIS page, and build the call that proves it moved.
+ *
+ * The sequence is the tutorial's; what this adds is a target from the app actually in front of the
+ * user, because a walkthrough against a fixture teaches the fixture. The consequence is declared in
+ * the call rather than checked afterwards — a demo that ends without a verdict would teach the exact
+ * habit the tutorial exists to correct.
+ *
+ * Refusing is a real outcome. A page with nothing safe on it gets told so, because demonstrating on
+ * "Delete account" to avoid an awkward message is not a trade anybody would make deliberately.
+ */
+export declare function demoPlan(controls: readonly {
+    ref: string;
+    name: string;
+    role?: string;
+}[]): DemoPlan;

package/dist/command/cli/tutorial.js

@@ -0,0 +1,189 @@
+/**
+ * The tutorial: one sequence, two audiences.
+ *
+ * A human wants to know what to do next and why it is worth doing. An agent wants the exact call and
+ * the exact shape of the answer, because prose it has to interpret is a turn it has to spend. Write
+ * for one and hope the other copes, and you get a page agents skip and humans skim.
+ *
+ * What both MUST share is the order. Two audiences taking different routes through one product is
+ * how a support answer stops matching what anybody actually did.
+ *
+ * The sequence is not arbitrary either. It ends at a VERDICT because a tour that ends at "you can see
+ * the page now" has taught the least valuable half: looking is not verifying, and an agent that
+ * learns only to look will report that it looked. And it declares the consequence BEFORE acting,
+ * because that ordering IS the idea — naming what should happen first is the difference between a
+ * check and a rationalisation written afterwards.
+ */
+import { OnboardingPhase, OnboardingStepStatus, } from '@reticlehq/core/telemetry';
+import { TOUR_STEPS } from '@reticlehq/core/tour';
+/**
+ * The steps, from the one place both surfaces read them.
+ *
+ * They used to be a private array here, which is why the browser could not render the same tour:
+ * nothing outside this package could see them. `title` and `anchor` are the carousel's business and
+ * a terminal ignores them.
+ */
+const STEPS = TOUR_STEPS.map((s) => ({
+    id: s.id,
+    say: s.say,
+    why: s.why,
+    ...(undefined === s.call ? {} : { call: s.call }),
+}));
+/**
+ * The two ONBOARD steps a SHOWN tour can honestly answer.
+ *
+ * Here rather than in `command/cli-onboarding.ts`, because both callers live on this side of that
+ * line: `cli/setup-mcp-cli.ts` shows the tour when a person is watching, and reaching back into
+ * `command/` for the step names made `cli <-> command` a mutual pair — which `directory-reach`
+ * refused, with the right advice: the thing being reached for was simply filed in the wrong place.
+ * `command/` importing from `cli/` is the direction that already exists.
+ *
+ * The tour RENDERS; it does not run anything. So it knows the tour was asked for and the concept
+ * was put in front of somebody, and nothing about whether they then looked, acted or proved. The
+ * remaining three ONBOARD steps are observed by the daemon at the first look, act and verdict,
+ * which is the only place they are a fact.
+ */
+export function tutorialShownSteps() {
+    return ['tour_started', 'concept_shown'].map((step) => ({
+        phase: OnboardingPhase.ONBOARD,
+        step,
+        status: OnboardingStepStatus.COMPLETED,
+    }));
+}
+export const TutorialAudience = {
+    /** Prose, and a reason per step. */
+    HUMAN: 'human',
+    /** The call, and what comes back. */
+    AGENT: 'agent',
+};
+/**
+ * The same steps, shaped for who is reading.
+ *
+ * The agent form keeps the prose as well as the call. An agent that has only the call learns what to
+ * type and not what it means, which is exactly the reader that later reports a green it cannot
+ * explain.
+ */
+export function tutorialScript(audience) {
+    return STEPS.map((step) => TutorialAudience.AGENT === audience
+        ? { ...step, call: step.call ?? '' }
+        : // A human is not handed a raw call to paste without understanding it; the prose carries it.
+            { id: step.id, say: step.say, why: step.why });
+}
+/**
+ * The script as text for whoever asked.
+ *
+ * A human gets the reason on its own line, because the reason is what makes the step worth doing and
+ * a list of commands without them is a keystroke tour. An agent gets the call, because prose it has
+ * to interpret is a turn it has to spend — and it gets the prose too, since an agent that has only
+ * the call learns what to type and not what it means, which is the reader that later reports a green
+ * it cannot explain.
+ */
+/**
+ * What to do now the tour is over.
+ *
+ * Every other stage of setup ends by naming the next command — `install.sh` points at `reticle init`
+ * and this tutorial, `init` points at the dev server and `status`. This one ended at step 4 and
+ * stopped, so the stage whose entire job is to teach the sequence was the only one that never said
+ * how to start it. The steps above describe tools that need an instrumented, running app, and a
+ * reader who has just been told that a verdict is the point and shown no way to reach one is exactly
+ * where a funnel stalls.
+ *
+ * Split from `renderTutorial` so the closing block is a value a caller can assert on, rather than a
+ * string only findable by matching rendered prose.
+ */
+export function tutorialNextSteps(audience) {
+    const lines = TutorialAudience.AGENT === audience
+        ? [
+            'Next:',
+            '  reticle init            # instrument the project in this directory',
+            '  reticle status          # confirms the app connected, or says why it has not',
+            '  then run the four steps above against it, and report the verdict',
+        ]
+        : [
+            'Next:',
+            '  cd <your project> && reticle init   # wire Reticle into the app',
+            '  npm run dev                        # then load it in a browser',
+            '  reticle status                     # confirms the app connected, or says why not',
+            '',
+            'Then ask your agent to drive one real flow and report the verdict. That is the install',
+            'proving itself, and it is the agent’s job rather than a command you run.',
+        ];
+    return lines.join('\n');
+}
+/**
+ * What the installer prints when it has finished.
+ *
+ * Installation and onboarding are ONE script, so the tour is not conditional on anything. Gating it
+ * on `process.stdout.isTTY` does not work: that is `undefined` through every pipe, so the tour never
+ * prints. A heuristic that silently answers "nobody is watching" is worse than no heuristic.
+ *
+ * It ends with the tour's OWN closing, which already names `reticle init`. Adding a second "Next:"
+ * under it would be the same instruction twice in ten lines.
+ */
+export function installClosing() {
+    return [
+        '',
+        'Reticle is installed. Here is what it does, in four steps:',
+        '',
+        renderTutorial(TutorialAudience.HUMAN),
+    ].join('\n');
+}
+export function renderTutorial(audience) {
+    const steps = tutorialScript(audience)
+        .map((step, index) => {
+        const head = `${String(index + 1)}. ${step.say}`;
+        const why = `   why: ${step.why}`;
+        return step.call === undefined || 0 === step.call.length
+            ? `${head}\n${why}`
+            : `${head}\n${why}\n   ${step.call}`;
+    })
+        .join('\n\n');
+    return `${steps}\n\n${tutorialNextSteps(audience)}`;
+}
+/**
+ * Names that must never be demonstrated on.
+ *
+ * Deliberately broad, and deliberately matched on the NAME a user reads rather than on anything
+ * structural. A demo runs unattended against an app whose author has never seen this code, so the
+ * cost of being wrong is asymmetric: refusing a harmless button wastes a demo, clicking a harmful
+ * one costs somebody their data. When those are the two errors available, take the first one every
+ * time.
+ *
+ * `cancel` is here for the case that reads backwards: "Cancel subscription" is destructive, and a
+ * word-boundary match on a dismissive "Cancel" would be a false refusal — which is the cheap error.
+ */
+const UNSAFE_TO_DEMO = /delete|remove|deploy|publish|pay|purchase|buy|checkout|cancel|revoke|archive|reset|destroy|drop|send|submit|confirm/i;
+/**
+ * Pick something safe on THIS page, and build the call that proves it moved.
+ *
+ * The sequence is the tutorial's; what this adds is a target from the app actually in front of the
+ * user, because a walkthrough against a fixture teaches the fixture. The consequence is declared in
+ * the call rather than checked afterwards — a demo that ends without a verdict would teach the exact
+ * habit the tutorial exists to correct.
+ *
+ * Refusing is a real outcome. A page with nothing safe on it gets told so, because demonstrating on
+ * "Delete account" to avoid an awkward message is not a trade anybody would make deliberately.
+ */
+export function demoPlan(controls) {
+    const safe = controls.find((c) => !UNSAFE_TO_DEMO.test(c.name));
+    if (safe === undefined) {
+        return {
+            ok: false,
+            because: 0 === controls.length
+                ? 'nothing interactive is on this page yet — load the app and try again'
+                : 'no control here is safe to demonstrate on: every one reads as something that commits. ' +
+                    'Drive it yourself with a consequence you choose.',
+        };
+    }
+    return {
+        ok: true,
+        ref: safe.ref,
+        name: safe.name,
+        // `{ element: { testid } }` reads naturally and is REFUSED: a consequence is a predicate with a
+        // `kind`, and act_and_wait says so in its own refusal text. This line is a call the reader is
+        // meant to paste, so a plausible-but-unparseable spelling here teaches the exact mistake that
+        // tool exists to catch.
+        call: `reticle_act_and_wait { ref: "${safe.ref}", action: "click", ` +
+            `until: { kind: "element", by: "testid", value: "<what should appear>" } }`,
+    };
+}

package/dist/command/cli-onboarding.d.ts

@@ -0,0 +1,21 @@
+import type { OnboardingStep } from '@reticlehq/core/telemetry';
+/**
+ * The CLI's half of the setup funnel.
+ *
+ * It lives in `command/` and not in `command/cli/` for a reason the reach guard found: `cli/` does
+ * not reach `telemetry/`, and adding that edge made a MUTUAL pair — two directories that each need
+ * the other cannot be read, moved or tested apart. `command/` already reaches telemetry, so the
+ * reporter is built here and handed down to every command that needs one.
+ */
+export declare const reportStepFromCli: (step: OnboardingStep) => void;
+/**
+ * The two ONBOARD steps `reticle tutorial` can honestly answer.
+ *
+ * Asking for the tour is a fact here, and so is having been shown what Reticle is. Whether the
+ * reader then looked, acted or proved is not — even on `tutorial --run`, which drives the demo: those
+ * three are reported by the daemon at the first look / act / verdict it actually witnesses, through
+ * the dispatch chokepoint, because that is the only place they are observations rather than claims.
+ * Reporting them from here would turn "the tour reached step four" into "somebody verified something",
+ * which is the same substitution the fourth step of the tour exists to warn about.
+ */
+export declare function reportTutorialShown(): void;

package/dist/command/cli-onboarding.js

@@ -0,0 +1,27 @@
+import { reportOnboardingStep } from '../telemetry/onboarding-funnel.js';
+import { tutorialShownSteps } from './cli/tutorial.js';
+/**
+ * The CLI's half of the setup funnel.
+ *
+ * It lives in `command/` and not in `command/cli/` for a reason the reach guard found: `cli/` does
+ * not reach `telemetry/`, and adding that edge made a MUTUAL pair — two directories that each need
+ * the other cannot be read, moved or tested apart. `command/` already reaches telemetry, so the
+ * reporter is built here and handed down to every command that needs one.
+ */
+export const reportStepFromCli = (step) => {
+    void reportOnboardingStep(step);
+};
+/**
+ * The two ONBOARD steps `reticle tutorial` can honestly answer.
+ *
+ * Asking for the tour is a fact here, and so is having been shown what Reticle is. Whether the
+ * reader then looked, acted or proved is not — even on `tutorial --run`, which drives the demo: those
+ * three are reported by the daemon at the first look / act / verdict it actually witnesses, through
+ * the dispatch chokepoint, because that is the only place they are observations rather than claims.
+ * Reporting them from here would turn "the tour reached step four" into "somebody verified something",
+ * which is the same substitution the fourth step of the tour exists to warn about.
+ */
+export function reportTutorialShown() {
+    for (const step of tutorialShownSteps())
+        reportStepFromCli(step);
+}

package/dist/command/cli.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { parseCliArgs, CLI_USAGE } from './cli/cli-parse.js';
+export { parseCliArgs, CLI_USAGE };
+export type { CliResult } from './cli/cli-parse.js';
+export declare function handleStatus(port: number, json?: boolean): Promise<void>;
+export declare function main(): void;