@reticlehq/server 3.2.0 → 3.4.0

package/dist/command/cli/ports/resolve/cli-port.d.ts

@@ -23,6 +23,13 @@ export declare const RETICLE_CONFIG_BASENAME = ".reticle.json";
  * Returns undefined when nothing is found, which keeps every caller's existing default intact.
  */
 export declare function findProjectConfig(cwd: string): Record<string, unknown> | undefined;
+/**
+ * The directory of the project this invocation serves: where its `.reticle.json` is, else the one
+ * wired workspace app below a monorepo root, else `cwd` itself. What the CLI reads the installed SDK
+ * from, so it answers for the app the port above belongs to rather than for the directory it was
+ * started in.
+ */
+export declare function projectDirOf(cwd: string): string;
 /**
  * The dev-server port heuristics live in `@reticlehq/init` — `existing-config.ts` is what diagnoses
  * a `.reticle.json` whose `port` is the app's own dev-server port, and the scaffolder may not import
@@ -33,14 +40,39 @@ export { DEV_SERVER_PORTS, isLikelyDevServerPort, devServerPortWarning } from '@
 /**
  * Read the port stored in the project's .reticle.json (written by `reticle init`).
  * Returns undefined if the file is absent, unreadable, or has no valid numeric port.
+ *
+ * With no config at or above `cwd`, it looks DOWN, the same way `projectIdsAt` does. Running from a
+ * monorepo root whose app was wired in `apps/web` used to find nothing and fall back to the default
+ * port, so `status`, `mcp` and `verify` quietly talked to another project's daemon. One wired app
+ * below, or several that agree, give their port; several that disagree give none, and
+ * `workspacePortConflict` is what says so rather than letting the default win in silence.
  */
 export declare function readProjectPort(cwd: string): number | undefined;
+/**
+ * The sentence for a monorepo root whose wired apps name different ports, or undefined when there is
+ * nothing to choose between. `readProjectPort` refuses to pick one; this is what tells the person
+ * which ports exist and how to name the one they meant.
+ */
+export declare function workspacePortConflict(cwd: string): string | undefined;
 /**
  * Read the stable projectId stored in the project's .reticle.json (written by `reticle init`). The daemon
  * uses it as the default resolve scope so auto-selection stays within the active app. Returns
  * undefined if the file is absent/unreadable or has no non-empty string projectId.
  */
 export declare function readProjectId(cwd: string): ProjectId | undefined;
+/**
+ * Every project id this directory can speak for, for "has THIS project ever connected".
+ *
+ * `readProjectId` knows only what `init` wrote. The build plugins derive the same id from the package
+ * name and the app root WITHOUT writing `.reticle.json`, so a monorepo root (the app lives in
+ * `apps/web`) and an app wired by the plugin alone both read `undefined`, and the handshake told a
+ * working project nothing had ever connected. Deriving the plugin's own id cannot reopen the opposite
+ * lie: an id only counts once an app with exactly that id has dialled in.
+ *
+ * Workspace discovery is init's `findWorkspaceApps`, reused so the two cannot disagree about which
+ * directories are apps. Best-effort: a directory it cannot read contributes nothing.
+ */
+export declare function projectIdsAt(cwd: string): ProjectId[];
 /**
  * The framework `reticle init` stamped into `.reticle.json`, when there is one.
  *
@@ -50,6 +82,12 @@ export declare function readProjectId(cwd: string): ProjectId | undefined;
  * time and the hint the agent reads hours later never mentioned it.
  */
 export declare function readProjectFramework(cwd: string): string | undefined;
+/**
+ * Whether the project this directory serves is a desktop shell (Electron, Tauri) — the same question
+ * `doctor` asks, answered from the same files. Read so the no-session guidance stops sending a
+ * desktop user to a browser URL.
+ */
+export declare function readProjectIsDesktop(cwd: string): boolean;
 /**
  * Whether the durable causal journal is enabled. On by default (the journal IS the loop); off only via
  * explicit opt-out — `.reticle.json` `"journal": false`, or `RETICLE_JOURNAL` set to `0`/`false`. The env

package/dist/command/cli/ports/resolve/cli-port.js

@@ -8,7 +8,8 @@
  * 4. RETICLE_DEFAULT_PORT (4400)
  */
 import { readFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
+import { SILENT_HOST, buildNodeIo, deriveProjectId, findWorkspaceApps, isDesktopProject, packageName, } from '@reticlehq/init';
 import { asProjectId } from '@reticlehq/core';
 /** The project config `reticle init` writes. */
 export const RETICLE_CONFIG_BASENAME = '.reticle.json';
@@ -34,18 +35,15 @@ const MAX_CONFIG_SEARCH_DEPTH = 6;
  * Returns undefined when nothing is found, which keeps every caller's existing default intact.
  */
 export function findProjectConfig(cwd) {
+    const dir = findProjectConfigDir(cwd);
+    return dir === undefined ? undefined : readConfigAt(dir);
+}
+/** The directory holding the nearest `.reticle.json` at or above `cwd`, by the same walk. */
+function findProjectConfigDir(cwd) {
     let dir = resolve(cwd);
     for (let depth = 0; depth <= MAX_CONFIG_SEARCH_DEPTH; depth += 1) {
-        try {
-            const raw = readFileSync(`${dir}/${RETICLE_CONFIG_BASENAME}`, 'utf8');
-            const config = JSON.parse(raw);
-            if ('object' === typeof config && config !== null && !Array.isArray(config)) {
-                return config;
-            }
-        }
-        catch {
-            // Absent, unreadable, or not JSON at this level — keep walking.
-        }
+        if (readConfigAt(dir) !== undefined)
+            return dir;
         const parent = dirname(dir);
         if (parent === dir)
             break;
@@ -53,6 +51,48 @@ export function findProjectConfig(cwd) {
     }
     return undefined;
 }
+/**
+ * The directory of the project this invocation serves: where its `.reticle.json` is, else the one
+ * wired workspace app below a monorepo root, else `cwd` itself. What the CLI reads the installed SDK
+ * from, so it answers for the app the port above belongs to rather than for the directory it was
+ * started in.
+ */
+export function projectDirOf(cwd) {
+    const configDir = findProjectConfigDir(cwd);
+    if (configDir !== undefined)
+        return appPointedAtBy(configDir) ?? configDir;
+    const apps = workspaceAppPorts(cwd);
+    const only = 1 === apps.length ? apps[0] : undefined;
+    return only === undefined ? resolve(cwd) : join(resolve(cwd), only.app);
+}
+/**
+ * The one workspace app below `dir` whose own config names the project `dir`'s does, or undefined.
+ *
+ * `init` writes a copy of the app's `.reticle.json` at the root the agent runs from, so the root's
+ * config is a pointer to that app rather than a project of its own. The projectId is the link — no
+ * path is stored — and a root whose id no app shares, or several do, is its own project.
+ */
+function appPointedAtBy(dir) {
+    const id = readConfigAt(dir)?.['projectId'];
+    if ('string' !== typeof id || 0 === id.length)
+        return undefined;
+    const named = workspaceApps(dir).filter((app) => id === readConfigAt(join(dir, app))?.['projectId']);
+    const only = 1 === named.length ? named[0] : undefined;
+    return only === undefined ? undefined : join(dir, only);
+}
+/** The `.reticle.json` in exactly `dir` — no walk — or undefined when absent or not an object. */
+function readConfigAt(dir) {
+    try {
+        const config = JSON.parse(readFileSync(join(dir, RETICLE_CONFIG_BASENAME), 'utf8'));
+        if ('object' === typeof config && config !== null && !Array.isArray(config)) {
+            return config;
+        }
+    }
+    catch {
+        // Absent, unreadable, or not JSON at this level.
+    }
+    return undefined;
+}
 /**
  * The dev-server port heuristics live in `@reticlehq/init` — `existing-config.ts` is what diagnoses
  * a `.reticle.json` whose `port` is the app's own dev-server port, and the scaffolder may not import
@@ -60,15 +100,70 @@ export function findProjectConfig(cwd) {
  * diagnosis, and `cli.ts`) are unchanged.
  */
 export { DEV_SERVER_PORTS, isLikelyDevServerPort, devServerPortWarning } from '@reticlehq/init';
+/** A config's `port`, when it is a usable TCP port. */
+function configPort(config) {
+    const p = config?.['port'];
+    if ('number' === typeof p && Number.isInteger(p) && p > 0 && p < 65536)
+        return p;
+    return undefined;
+}
 /**
  * Read the port stored in the project's .reticle.json (written by `reticle init`).
  * Returns undefined if the file is absent, unreadable, or has no valid numeric port.
+ *
+ * With no config at or above `cwd`, it looks DOWN, the same way `projectIdsAt` does. Running from a
+ * monorepo root whose app was wired in `apps/web` used to find nothing and fall back to the default
+ * port, so `status`, `mcp` and `verify` quietly talked to another project's daemon. One wired app
+ * below, or several that agree, give their port; several that disagree give none, and
+ * `workspacePortConflict` is what says so rather than letting the default win in silence.
  */
 export function readProjectPort(cwd) {
-    const p = findProjectConfig(cwd)?.['port'];
-    if ('number' === typeof p && Number.isInteger(p) && p > 0 && p < 65536)
-        return p;
-    return undefined;
+    const config = findProjectConfig(cwd);
+    if (config !== undefined)
+        return configPort(config);
+    const ports = new Set(workspaceAppPorts(cwd).map((a) => a.port));
+    return 1 === ports.size ? [...ports][0] : undefined;
+}
+/** Each workspace app under `cwd` whose own `.reticle.json` records a port. */
+function workspaceAppPorts(cwd) {
+    const found = [];
+    for (const app of workspaceApps(cwd)) {
+        // The app's OWN file only — walking up from an unwired sibling would reach the root, or past it.
+        const port = configPort(readConfigAt(join(cwd, app)));
+        if (port !== undefined)
+            found.push({ app, port });
+    }
+    return found;
+}
+/** init's workspace discovery under `cwd`, relative app directories; empty when `cwd` is no package. */
+function workspaceApps(cwd) {
+    // Only from a directory that is itself a package: a root with no package.json is not a workspace,
+    // and scanning, say, a home directory would adopt the port of whichever checkout happened to sit
+    // there.
+    if (packageNameAt(cwd) === undefined)
+        return [];
+    try {
+        return findWorkspaceApps(buildNodeIo(cwd, SILENT_HOST));
+    }
+    catch {
+        // Discovery touches the filesystem; an unreadable tree is simply no further evidence.
+        return [];
+    }
+}
+/**
+ * The sentence for a monorepo root whose wired apps name different ports, or undefined when there is
+ * nothing to choose between. `readProjectPort` refuses to pick one; this is what tells the person
+ * which ports exist and how to name the one they meant.
+ */
+export function workspacePortConflict(cwd) {
+    if (findProjectConfig(cwd) !== undefined)
+        return undefined;
+    const apps = workspaceAppPorts(cwd);
+    if (new Set(apps.map((a) => a.port)).size < 2)
+        return undefined;
+    const listed = apps.map((a) => `${a.app} (:${String(a.port)})`).join(', ');
+    return (`This workspace has more than one app wired for Reticle, on different ports: ${listed}. ` +
+        'Not guessing which one you meant — run the command from inside that app, or pass --port.');
 }
 /**
  * Read the stable projectId stored in the project's .reticle.json (written by `reticle init`). The daemon
@@ -84,6 +179,49 @@ export function readProjectId(cwd) {
         return asProjectId(id);
     return undefined;
 }
+const PACKAGE_JSON = 'package.json';
+/** The package name in `dir/package.json`, or undefined when there is no readable one. */
+function packageNameAt(dir) {
+    try {
+        return packageName(JSON.parse(readFileSync(join(dir, PACKAGE_JSON), 'utf8')));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The id an app at `dir` carries: the one `init` recorded, else the one the build plugin derives. */
+function projectIdFor(dir) {
+    return readProjectId(dir) ?? asProjectId(deriveProjectId(packageNameAt(dir), dir));
+}
+/**
+ * Every project id this directory can speak for, for "has THIS project ever connected".
+ *
+ * `readProjectId` knows only what `init` wrote. The build plugins derive the same id from the package
+ * name and the app root WITHOUT writing `.reticle.json`, so a monorepo root (the app lives in
+ * `apps/web`) and an app wired by the plugin alone both read `undefined`, and the handshake told a
+ * working project nothing had ever connected. Deriving the plugin's own id cannot reopen the opposite
+ * lie: an id only counts once an app with exactly that id has dialled in.
+ *
+ * Workspace discovery is init's `findWorkspaceApps`, reused so the two cannot disagree about which
+ * directories are apps. Best-effort: a directory it cannot read contributes nothing.
+ */
+export function projectIdsAt(cwd) {
+    const recorded = readProjectId(cwd);
+    if (recorded !== undefined)
+        return [recorded];
+    const ids = [];
+    if (packageNameAt(cwd) !== undefined)
+        ids.push(projectIdFor(cwd));
+    try {
+        for (const app of findWorkspaceApps(buildNodeIo(cwd, SILENT_HOST))) {
+            ids.push(projectIdFor(join(cwd, app)));
+        }
+    }
+    catch {
+        // Discovery touches the filesystem; an unreadable tree is simply no further evidence.
+    }
+    return [...new Set(ids)];
+}
 /**
  * The framework `reticle init` stamped into `.reticle.json`, when there is one.
  *
@@ -98,6 +236,22 @@ export function readProjectFramework(cwd) {
         return framework;
     return undefined;
 }
+/**
+ * Whether the project this directory serves is a desktop shell (Electron, Tauri) — the same question
+ * `doctor` asks, answered from the same files. Read so the no-session guidance stops sending a
+ * desktop user to a browser URL.
+ */
+export function readProjectIsDesktop(cwd) {
+    const dir = projectDirOf(cwd);
+    return isDesktopProject((relative) => {
+        try {
+            return readFileSync(join(dir, relative), 'utf8');
+        }
+        catch {
+            return undefined;
+        }
+    });
+}
 /**
  * Whether the durable causal journal is enabled. On by default (the journal IS the loop); off only via
  * explicit opt-out — `.reticle.json` `"journal": false`, or `RETICLE_JOURNAL` set to `0`/`false`. The env

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

@@ -0,0 +1,16 @@
+export interface ReportInput {
+    cwd: string;
+    now: number;
+    /** Did the working tree change? The hook stays silent on a turn that edited nothing. */
+    treeChanged: boolean;
+    session?: string;
+    hook?: boolean;
+}
+export declare function reportFor(input: ReportInput): Promise<{
+    lines: string[];
+}>;
+/**
+ * The command. As a hook it prints Claude Code's `systemMessage` shape and always exits 0: it is
+ * print-only by design, so the human sees the gap and the agent is never blocked by it.
+ */
+export declare function handleReport(session: string | undefined, hook: boolean): Promise<void>;

package/dist/command/cli/report-command.js

@@ -0,0 +1,97 @@
+/**
+ * `reticle report [--session <id>] [--hook]` — what this project's latest session claimed, and what held.
+ *
+ * Read from disk, with no daemon: the journal is on disk, and a Stop hook has to answer in the second
+ * after the agent stops, when there may be nothing running to ask. The fold is `gapSummary`, the same
+ * one `reticle_context` serves, so the terminal and the agent cannot be told two different stories.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { DiscoveryInvite, ReticleDir } from '@reticlehq/core';
+import { gapSummary } from '../../judgement/runs/artifact/gap-summary.js';
+import { SessionJournal } from '../../memory/journal/session-journal.js';
+import { createNodeFileSystem } from '../../memory/project/fs/fs-port.js';
+import { gapHookLine, gapReportLines } from '../../judgement/runs/artifact/gap-report.js';
+/**
+ * A session last written longer ago than this is not the turn a hook is asking about.
+ *
+ * ponytail: a fixed window, not a turn boundary — the Stop hook is not told when the turn began. A
+ * drive older than an hour reads as "no claim this session", which errs toward saying so.
+ */
+const HOOK_WINDOW_MS = 60 * 60 * 1000;
+/** The session whose action ledger was written most recently, if any. */
+function newestSession(root) {
+    const sessionsDir = join(root, ReticleDir.SESSIONS_SUBDIR);
+    if (!existsSync(sessionsDir))
+        return undefined;
+    let newest;
+    for (const id of readdirSync(sessionsDir)) {
+        const ledger = join(sessionsDir, id, ReticleDir.JOURNAL_ACTIONS_FILE);
+        if (!existsSync(ledger))
+            continue;
+        const writtenAt = statSync(ledger).mtimeMs;
+        if (newest === undefined || writtenAt > newest.writtenAt)
+            newest = { id, writtenAt };
+    }
+    return newest;
+}
+export async function reportFor(input) {
+    if (true === input.hook && !input.treeChanged)
+        return { lines: [] };
+    const root = join(input.cwd, ReticleDir.ROOT);
+    const found = input.session === undefined ? newestSession(root) : { id: input.session, writtenAt: input.now };
+    const current = found !== undefined && (true !== input.hook || input.now - found.writtenAt <= HOOK_WINDOW_MS)
+        ? found
+        : undefined;
+    const actions = current === undefined
+        ? []
+        : await new SessionJournal(createNodeFileSystem(), root, current.id).readActions();
+    const gap = gapSummary(actions);
+    if (true === input.hook) {
+        const line = gapHookLine(gap);
+        // A finish with nothing proved is the moment Reticle let somebody down: say who to tell.
+        return { lines: line === undefined ? [] : [line, DiscoveryInvite.HUMAN] };
+    }
+    const header = current === undefined ? [] : [`session ${current.id}`];
+    return { lines: [...header, ...gapReportLines(gap), DiscoveryInvite.HUMAN] };
+}
+/** Uncommitted changes in `cwd`. Outside a git repository nothing can say, so it answers yes. */
+function treeChanged(cwd) {
+    try {
+        return '' !== execFileSync('git', ['status', '--porcelain'], { cwd, encoding: 'utf8' }).trim();
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * The command. As a hook it prints Claude Code's `systemMessage` shape and always exits 0: it is
+ * print-only by design, so the human sees the gap and the agent is never blocked by it.
+ */
+export async function handleReport(session, hook) {
+    const cwd = process.cwd();
+    let lines;
+    try {
+        ({ lines } = await reportFor({
+            cwd,
+            now: Date.now(),
+            treeChanged: hook ? treeChanged(cwd) : true,
+            ...(session === undefined ? {} : { session }),
+            hook,
+        }));
+    }
+    catch (error) {
+        // A hook that throws turns the agent's stop into an error the user did not cause; it says nothing
+        // instead. Run by hand, the reason is the answer (an id that is not a session, a journal it
+        // could not read), so it is printed and the exit is non-zero.
+        if (hook)
+            return;
+        process.stderr.write(`reticle report: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    if (0 === lines.length)
+        return;
+    process.stdout.write(hook ? `${JSON.stringify({ systemMessage: lines.join('\n') })}\n` : `${lines.join('\n')}\n`);
+}

package/dist/command/cli/setup-mcp-cli.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { homedir } from 'node:os';
-import { probeCli } from '@reticlehq/init';
+import { probeCli, terminalWidth, wrapForTerminal } from '@reticlehq/init';
 import { installClosing, tutorialShownSteps } from './tutorial.js';
 import { setupMcp, knownClientLabels } from '../setup/setup-mcp.js';
 import { reportInstallSteps } from '../setup/setup-install.js';
@@ -22,7 +22,7 @@ export function handleSetupMcp(reportStep, standalone = true) {
             writeFileSync(p, contents);
         },
         homeDir: () => homedir(),
-        print: (line) => process.stdout.write(`${line}\n`),
+        print: (line) => process.stdout.write(`${wrapForTerminal(line, terminalWidth())}\n`),
         reportStep,
         // `probeCli`, not a bare `execFileSync`: on Windows `claude` is a `.cmd` shim that cannot be
         // spawned without a shell, so the plain call threw ENOENT for every Windows user and the
@@ -46,16 +46,16 @@ export function handleSetupMcp(reportStep, standalone = true) {
         return;
     }
     for (const id of result.registered)
-        io.print(`  registered  ${id}`);
+        io.print(`  ✓ ${id}`);
     for (const id of result.alreadyThere)
-        io.print(`  already     ${id}`);
+        io.print(`  ✓ ${id} (already set up)`);
     // Said, not skipped. These are the clients whose format we will not rewrite, and they used to be
     // counted as registered: the line below is the difference between a user who adds four lines to
     // one file and a user who believes they are set up and has no tools.
     for (const client of result.manual) {
-        io.print(`  BY HAND     ${client.id}: add the reticle entry to ${client.configPath}`);
+        io.print(`  ⚠ ${client.id}: add the reticle entry to ${client.configPath} by hand`);
         if (client.docs !== undefined)
-            io.print(`              see ${client.docs}`);
+            io.print(`    see ${client.docs}`);
     }
     /*
      * The OTHER agents, which `init` already reaches and this did not.
@@ -75,13 +75,13 @@ export function handleSetupMcp(reportStep, standalone = true) {
     });
     // Said on every run, attended or not: a registration only takes effect when the agent re-reads
     // its config, and an agent that was already open is the commonest reason "it did not work".
-    io.print('');
-    io.print('Restart your agent for it to pick up the new server.');
-    // Only when this IS the whole command. Inside the installer the tour follows, and its own closing
-    // already names `reticle init` — printing it here too put the same instruction twice, ten lines
-    // apart, with the tour sandwiched between them.
-    if (standalone)
+    // Only when this IS the whole command. Inside the installer the restart is the first line of the
+    // closing's Next list, where it belongs with the other things to do, not between the stages.
+    if (standalone) {
+        io.print('');
+        io.print('Restart your agent for it to pick up the new server.');
         io.print('Then: cd <your project> && reticle init');
+    }
 }
 /**
  * `reticle setup install` — the Node half of the one-line installer.
@@ -100,7 +100,7 @@ export function handleSetupInstall(opts, reportStep) {
     }
     // Installation and onboarding are one script, so the tour prints here and is not gated on
     // anything — see installClosing for the heuristic this replaced and why it reached nobody.
-    process.stdout.write(`${installClosing()}\n`);
+    process.stdout.write(`${wrapForTerminal(installClosing(opts.mcp), terminalWidth())}\n`);
     // Shown, so the ONBOARD steps are a fact rather than a guess.
     for (const step of tutorialShownSteps())
         reportStep(step);

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

@@ -76,7 +76,7 @@ export declare function tutorialScript(audience: TutorialAudience): TutorialStep
  * 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;
+export declare function tutorialNextSteps(audience: TutorialAudience, restartAgent?: boolean): string;
 /**
  * What the installer prints when it has finished.
  *
@@ -87,7 +87,7 @@ export declare function tutorialNextSteps(audience: TutorialAudience): string;
  * 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 installClosing(registered?: boolean): string;
 export declare function renderTutorial(audience: TutorialAudience): string;
 export type DemoPlan = {
     ok: true;

package/dist/command/cli/tutorial.js

@@ -91,7 +91,7 @@ export function tutorialScript(audience) {
  * 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) {
+export function tutorialNextSteps(audience, restartAgent = false) {
     const lines = TutorialAudience.AGENT === audience
         ? [
             'Next:',
@@ -101,12 +101,15 @@ export function tutorialNextSteps(audience) {
         ]
         : [
             'Next:',
-            '  cd <your project> && reticle init   # wire Reticle into the app',
+            ...(restartAgent
+                ? ['  restart your agent                 # it loads new tools only when it starts']
+                : []),
+            '  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.',
+            // One line: the terminal wraps it at the reader's width, not ours.
+            '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');
 }
@@ -120,14 +123,25 @@ export function tutorialNextSteps(audience) {
  * 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() {
+export function installClosing(registered = true) {
+    // One line a step. The reasons are for `reticle tutorial`; right after an install they turned a
+    // four-step idea into twenty-five lines of prose between the reader and the next command.
+    const steps = tutorialScript(TutorialAudience.HUMAN).map((step, index) => `  ${String(index + 1)}. ${INSTALL_SAYS[step.id] ?? step.say}`);
     return [
         '',
-        'Reticle is installed. Here is what it does, in four steps:',
+        '✓ Reticle is installed. How it works:',
+        ...steps,
         '',
-        renderTutorial(TutorialAudience.HUMAN),
+        tutorialNextSteps(TutorialAudience.HUMAN, registered),
     ].join('\n');
 }
+/**
+ * Tour steps reworded for a reader who has no app wired yet. The in-app tour's "That panel is
+ * Reticle" points at a panel on screen; straight after an install there is none to point at.
+ */
+const INSTALL_SAYS = {
+    connect: 'Once `reticle init` wires your app, a Reticle panel appears in it: your proof the SDK is connected.',
+};
 export function renderTutorial(audience) {
     const steps = tutorialScript(audience)
         .map((step, index) => {