@reticlehq/init 2.14.0

package/dist/astro-host.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Which Astro file owns the document, and therefore where the SDK script belongs.
+ *
+ * The previous rule was "exactly one `.astro` file in `src/layouts/`". Measured on two real Astro
+ * projects, it fired on neither: one has no `src/layouts/` at all and renders from
+ * `src/pages/index.astro`; the other has three files there, two of which are partials. Both got a
+ * printed recipe instead of a working install.
+ *
+ * A file COUNT cannot tell a layout from a partial, and a directory NAME cannot tell you where the
+ * document shell is. `</body>` can — the file that closes the body is the one every page renders
+ * through, and the only place a script reaches the whole app.
+ *
+ * Ambiguity is still refused rather than guessed. Two document shells means two entry points, and
+ * silently instrumenting one of them would leave half the app unverified while reporting success.
+ */
+interface AstroCandidate {
+    path: string;
+    source: string;
+}
+export declare function pickAstroHost(candidates: readonly AstroCandidate[]): AstroCandidate | undefined;
+export {};

package/dist/astro-host.js

@@ -0,0 +1,27 @@
+/**
+ * Which Astro file owns the document, and therefore where the SDK script belongs.
+ *
+ * The previous rule was "exactly one `.astro` file in `src/layouts/`". Measured on two real Astro
+ * projects, it fired on neither: one has no `src/layouts/` at all and renders from
+ * `src/pages/index.astro`; the other has three files there, two of which are partials. Both got a
+ * printed recipe instead of a working install.
+ *
+ * A file COUNT cannot tell a layout from a partial, and a directory NAME cannot tell you where the
+ * document shell is. `</body>` can — the file that closes the body is the one every page renders
+ * through, and the only place a script reaches the whole app.
+ *
+ * Ambiguity is still refused rather than guessed. Two document shells means two entry points, and
+ * silently instrumenting one of them would leave half the app unverified while reporting success.
+ */
+/** Tolerant of whitespace and casing: `</body>`, `</BODY >`, `</body\n>`. */
+const CLOSES_BODY = /<\/\s*body\s*>/i;
+/** Layout files win over pages: a page shell is one route, a layout shell is what routes inherit. */
+const LAYOUT_DIR = 'layouts/';
+export function pickAstroHost(candidates) {
+    const owners = candidates.filter((c) => CLOSES_BODY.test(c.source));
+    if (0 === owners.length)
+        return undefined;
+    const layouts = owners.filter((c) => c.path.includes(LAYOUT_DIR));
+    const preferred = layouts.length > 0 ? layouts : owners;
+    return 1 === preferred.length ? preferred[0] : undefined;
+}

package/dist/astro-patch.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Pure, conservative patchers for an Astro app: the config gets the token/root `define` and the
+ * raised build target, one layout gets the dev-only connect `<script>`.
+ *
+ * Astro was the last gated framework where `init` printed a correct recipe and applied none of it —
+ * the only ⚠ left on a supported stack, and the user's first session was two hand-copied snippets
+ * away. Astro is Vite-based but renders its own HTML, so the Vite plugin's injection never fires and
+ * there is no entry module to wire: the connect has to live in a page or layout `<script>`, and the
+ * token has to be inlined by the config because nothing else is in the page's path to inject it.
+ *
+ * Both patchers bail to `manual` (the printed recipe) on any shape they do not fully recognise.
+ * Half-editing a build config is worse than a documented manual step.
+ */
+import { type SourcePatch } from './patch-kind.js';
+import { UiLibrary } from './detect.js';
+export declare function patchAstroConfig(source: string): SourcePatch;
+export declare function patchAstroLayout(source: string, port: number | undefined, projectId: string | undefined, uiLibrary?: UiLibrary, testids?: readonly string[]): SourcePatch;
+/** Where Astro keeps ambient types — `create-astro` ships this file. */
+export declare const ASTRO_ENV_DTS_PATH = "src/env.d.ts";
+/**
+ * The declarations `astro check` needs for the Vite `define` names (#677).
+ *
+ * Matching SvelteKit's `hooks.client.ts` typing: `string | undefined`, because the define can be
+ * absent when the pairing token file is missing.
+ */
+export declare const ASTRO_ENV_DTS_DECLARES: string;
+/**
+ * Append the Vite-define ambient declarations to `src/env.d.ts`, or create the file.
+ *
+ * Without this, `create-astro`'s default `"astro check && astro build"` fails with four
+ * `ts(2304) Cannot find name '__RETICLE_TOKEN__'` errors after a clean init (#677).
+ */
+export declare function patchAstroEnvDts(existing: string | null): SourcePatch;

package/dist/astro-patch.js

@@ -0,0 +1,103 @@
+/**
+ * Pure, conservative patchers for an Astro app: the config gets the token/root `define` and the
+ * raised build target, one layout gets the dev-only connect `<script>`.
+ *
+ * Astro was the last gated framework where `init` printed a correct recipe and applied none of it —
+ * the only ⚠ left on a supported stack, and the user's first session was two hand-copied snippets
+ * away. Astro is Vite-based but renders its own HTML, so the Vite plugin's injection never fires and
+ * there is no entry module to wire: the connect has to live in a page or layout `<script>`, and the
+ * token has to be inlined by the config because nothing else is in the page's path to inject it.
+ *
+ * Both patchers bail to `manual` (the printed recipe) on any shape they do not fully recognise.
+ * Half-editing a build config is worse than a documented manual step.
+ */
+import { RETICLE_DEFAULT_PORT, bridgeWsUrl } from '@reticlehq/core';
+import { PatchKind } from './patch-kind.js';
+import { UiLibrary } from './detect.js';
+import { registerCapabilitiesCall, sdkImport } from './snippets.js';
+import { patchViteOwningConfig } from './vite-owning-config.js';
+/** Present in a patched layout and in the printed recipe's script. */
+const LAYOUT_MARKER = 'reticle.connect';
+const BODY_CLOSE = '</body>';
+/**
+ * Astro's half of the Vite-owning config patch: the call to extend, and the SDK to pre-bundle.
+ *
+ * `@reticlehq/react` and not the detected UI library: Astro hosts islands from any framework, but
+ * `frameworkPackages` gives every Astro app the React kit (see FRAMEWORK_ADAPTERS), so that is the
+ * package the connect script imports and the one Vite must pre-bundle.
+ */
+const ASTRO_VITE_CONFIG = {
+    defineCall: /defineConfig\s*\(\s*\{/,
+    sdkSpecifier: sdkImport(UiLibrary.REACT).specifier,
+};
+export function patchAstroConfig(source) {
+    return patchViteOwningConfig(source, ASTRO_VITE_CONFIG);
+}
+/** The dev-only connect that goes inside the layout's `<body>`. */
+function astroConnectScript(port, projectId, uiLibrary, testids) {
+    // Must match what `frameworkPackages` installed. Astro hosts islands from any framework, so an
+    // Astro app whose islands are Vue or Svelte gets the sensor, and a script importing the React
+    // adapter would load a package that is not in node_modules. See sdkImport.
+    const sdk = sdkImport(uiLibrary);
+    const url = port !== undefined && port !== RETICLE_DEFAULT_PORT
+        ? `\n          url: '${bridgeWsUrl(port)}',`
+        : '';
+    const id = projectId !== undefined && projectId.length > 0 ? `\n          projectId: '${projectId}',` : '';
+    return `    <script>
+      if (import.meta.env.DEV) {
+        const token = typeof __RETICLE_TOKEN__ !== 'undefined' ? __RETICLE_TOKEN__ : '';
+        const root = typeof __RETICLE_ROOT__ !== 'undefined' ? __RETICLE_ROOT__ : '';
+        const { reticle${sdk.usesInstall ? ', install' : ''}, registerCapabilities } = await import('${sdk.specifier}');
+        ${sdk.usesInstall ? 'install();' : '// The sensor has no install(); that is the React adapter.'}
+        reticle.connect({${id}${url}
+          ...(token.length > 0 ? { token } : {}),
+          ...(root.length > 0 ? { root } : {}),
+        });
+${registerCapabilitiesCall(testids, '        ')}
+      }
+    </script>
+`;
+}
+export function patchAstroLayout(source, port, projectId, uiLibrary = UiLibrary.REACT, testids = []) {
+    if (source.includes(LAYOUT_MARKER))
+        return { kind: PatchKind.ALREADY };
+    const at = source.lastIndexOf(BODY_CLOSE);
+    if (at < 0) {
+        return {
+            kind: PatchKind.MANUAL,
+            reason: "couldn't find a `</body>` to place the connect script before",
+        };
+    }
+    return {
+        kind: PatchKind.APPLY,
+        code: `${source.slice(0, at)}${astroConnectScript(port, projectId, uiLibrary, testids)}${source.slice(at)}`,
+    };
+}
+/** Where Astro keeps ambient types — `create-astro` ships this file. */
+export const ASTRO_ENV_DTS_PATH = 'src/env.d.ts';
+/**
+ * The declarations `astro check` needs for the Vite `define` names (#677).
+ *
+ * Matching SvelteKit's `hooks.client.ts` typing: `string | undefined`, because the define can be
+ * absent when the pairing token file is missing.
+ */
+export const ASTRO_ENV_DTS_DECLARES = 'declare const __RETICLE_TOKEN__: string | undefined;\n' +
+    'declare const __RETICLE_ROOT__: string | undefined;\n';
+/** Present once either declare is in the file — both are written together. */
+const ENV_DTS_MARKER = '__RETICLE_TOKEN__';
+/**
+ * Append the Vite-define ambient declarations to `src/env.d.ts`, or create the file.
+ *
+ * Without this, `create-astro`'s default `"astro check && astro build"` fails with four
+ * `ts(2304) Cannot find name '__RETICLE_TOKEN__'` errors after a clean init (#677).
+ */
+export function patchAstroEnvDts(existing) {
+    if (null !== existing && existing.includes(ENV_DTS_MARKER)) {
+        return { kind: PatchKind.ALREADY };
+    }
+    if (null === existing || '' === existing.trim()) {
+        return { kind: PatchKind.APPLY, code: ASTRO_ENV_DTS_DECLARES };
+    }
+    const base = existing.endsWith('\n') ? existing : `${existing}\n`;
+    return { kind: PatchKind.APPLY, code: `${base}${ASTRO_ENV_DTS_DECLARES}` };
+}

package/dist/brace-scan.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Brace / paren matching for conservative source patchers.
+ *
+ * A count, not a parser. A `{` or `}` inside a string literal would fool it. That only ever
+ * shortens or lengthens the window we search, so the worst case is a MANUAL bail or a missed
+ * merge — never a corrupted file written as APPLY.
+ */
+/**
+ * The text from just inside an opening brace to its match.
+ *
+ * `at` is the index just past `{`. Shared by the Astro and electron-vite patchers, which both
+ * need "the object literal after this key" and must agree on what that means.
+ */
+export declare function blockAfter(source: string, at: number): string;
+/**
+ * Index of the matching `}` for an object whose inner start is `at` (just past `{`).
+ * `undefined` when the braces never balance.
+ */
+export declare function matchingBraceEnd(source: string, at: number): number | undefined;
+/**
+ * Index of the matching `)` for a call whose opening `(` is at `openAt`.
+ * `undefined` when the parens never balance.
+ */
+export declare function matchingParenEnd(source: string, openAt: number): number | undefined;

package/dist/brace-scan.js

@@ -0,0 +1,46 @@
+/**
+ * Brace / paren matching for conservative source patchers.
+ *
+ * A count, not a parser. A `{` or `}` inside a string literal would fool it. That only ever
+ * shortens or lengthens the window we search, so the worst case is a MANUAL bail or a missed
+ * merge — never a corrupted file written as APPLY.
+ */
+/**
+ * The text from just inside an opening brace to its match.
+ *
+ * `at` is the index just past `{`. Shared by the Astro and electron-vite patchers, which both
+ * need "the object literal after this key" and must agree on what that means.
+ */
+export function blockAfter(source, at) {
+    const end = matchingCloser(source, at, '{', '}');
+    return end === undefined ? source.slice(at) : source.slice(at, end);
+}
+/**
+ * Index of the matching `}` for an object whose inner start is `at` (just past `{`).
+ * `undefined` when the braces never balance.
+ */
+export function matchingBraceEnd(source, at) {
+    return matchingCloser(source, at, '{', '}');
+}
+/**
+ * Index of the matching `)` for a call whose opening `(` is at `openAt`.
+ * `undefined` when the parens never balance.
+ */
+export function matchingParenEnd(source, openAt) {
+    if (source[openAt] !== '(')
+        return undefined;
+    return matchingCloser(source, openAt + 1, '(', ')');
+}
+function matchingCloser(source, innerStart, open, close) {
+    let depth = 1;
+    for (let i = innerStart; i < source.length; i++) {
+        if (source[i] === open)
+            depth += 1;
+        else if (source[i] === close) {
+            depth -= 1;
+            if (0 === depth)
+                return i;
+        }
+    }
+    return undefined;
+}

package/dist/capabilities.d.ts

@@ -0,0 +1,40 @@
+/**
+ * What the app can be driven by: its `data-testid` values, and which state library holds its truth.
+ *
+ * `init` wired none of this, so every app came up with `hasCapabilities: false`, empty capabilities,
+ * and a `reticle_state` holding nothing but `__reticle_renders` — the state-truth read that SKILL.md
+ * calls the highest-value line was unavailable on every app out of the box. Measured across six.
+ *
+ * Testids are scanned rather than asked for. Stores are NAMED but not wired: detecting that an app
+ * depends on zustand is easy, knowing which module exports the store instance is not, and generating
+ * a wrong import would break the dev module that everything else now hangs off.
+ */
+/** Cap the generated list. A capabilities block is a hint for an agent, not an inventory. */
+export declare const MAX_TESTIDS = 60;
+/** Every distinct `data-testid` literal in the given sources, in first-seen order. */
+export declare function scanTestids(sources: readonly string[]): string[];
+/**
+ * The store libraries this app depends on AND the running app cannot reveal on its own, as
+ * ready-to-uncomment registration lines.
+ */
+export declare function storeHints(deps: ReadonlySet<string>): string[];
+/** A store instance we found in the app's own source, with everything needed to import and register it. */
+export interface FoundStore {
+    /** The name it registers under — what `reticle_state` keys its output by. */
+    key: string;
+    /** The exported identifier. */
+    ident: string;
+    /** Module specifier relative to `src/reticle-dev.ts`. */
+    importPath: string;
+}
+/**
+ * Store instances declared in the app's own source, ready to import and register.
+ *
+ * Only exported declarations of a factory the app actually depends on: anything less certain would
+ * generate an import that breaks the dev module everything else hangs off, and a broken module is
+ * worse than the commented hint it replaces.
+ */
+export declare function scanStores(files: readonly {
+    path: string;
+    source: string;
+}[], deps: ReadonlySet<string>, fromDir?: string): FoundStore[];

package/dist/capabilities.js

@@ -0,0 +1,167 @@
+/**
+ * What the app can be driven by: its `data-testid` values, and which state library holds its truth.
+ *
+ * `init` wired none of this, so every app came up with `hasCapabilities: false`, empty capabilities,
+ * and a `reticle_state` holding nothing but `__reticle_renders` — the state-truth read that SKILL.md
+ * calls the highest-value line was unavailable on every app out of the box. Measured across six.
+ *
+ * Testids are scanned rather than asked for. Stores are NAMED but not wired: detecting that an app
+ * depends on zustand is easy, knowing which module exports the store instance is not, and generating
+ * a wrong import would break the dev module that everything else now hangs off.
+ */
+import { posix } from 'node:path';
+/** `data-testid="foo"` / `data-testid='foo'` / `data-testid={"foo"}` — the forms people actually write. */
+const TESTID_ATTR = /data-testid\s*=\s*[{]?\s*["'`]([^"'`]+)["'`]/g;
+/** Cap the generated list. A capabilities block is a hint for an agent, not an inventory. */
+export const MAX_TESTIDS = 60;
+/**
+ * An unresolved template interpolation, anywhere in a captured value.
+ *
+ * The attribute regex excludes quote characters and nothing else, so `data-testid={`chip-${x}`}`
+ * captures `chip-${x}` whole. Reported from a monorepo audit, where the generated capabilities file
+ * listed `'${testId}'` and `` 'chip-${group.label}' `` verbatim.
+ *
+ * Nothing in the running app ever carries those as an attribute value, so each one is an advertised
+ * handle that cannot be driven. The capabilities block exists to tell an agent what it CAN act on,
+ * and a list that is partly fiction is worse than a shorter true one — an agent that tries three
+ * imaginary testids learns to distrust the whole block.
+ *
+ * A bare `$` is fine and stays: it is legal in an attribute value and appears in real ids
+ * (`total$usd`). Only `${` is evidence of an interpolation that was never resolved.
+ */
+const UNRESOLVED_INTERPOLATION = '${';
+/** Every distinct `data-testid` literal in the given sources, in first-seen order. */
+export function scanTestids(sources) {
+    const found = new Set();
+    for (const src of sources) {
+        for (const m of src.matchAll(TESTID_ATTR)) {
+            const id = m[1];
+            if (id !== undefined && id.length > 0 && !id.includes(UNRESOLVED_INTERPOLATION)) {
+                found.add(id);
+            }
+            if (found.size >= MAX_TESTIDS)
+                return [...found];
+        }
+    }
+    return [...found];
+}
+/**
+ * State libraries the browser SDK has an adapter for, in the order we would recommend registering
+ * them. TanStack Query is first on purpose: a stale cache served as fresh fires NO network request,
+ * so the network log shows silence and the DOM shows a plausible number — the cache is the only
+ * witness, which makes it the highest-value store in the list and the least obvious one to add.
+ */
+const STORE_LIBRARIES = [
+    ['@tanstack/react-query', "registerStore('queries', tanstackQueryStore(queryClient))"],
+    [
+        'zustand',
+        "registerStore('app', useStore) // pass the store itself, not () => store.getState()",
+    ],
+    ['@reduxjs/toolkit', "registerStore('app', store)"],
+    ['redux', "registerStore('app', store)"],
+    ['jotai', "registerStore('app', jotaiStore(getDefaultStore(), { cart, user }))"],
+    ['valtio', "registerStore('app', valtioStore(state))"],
+    ['mobx', "registerStore('app', mobxStore(state))"],
+    ['xstate', "registerStore('machine', xstateStore(actor))"],
+    ['pinia', "registerStore('cart', piniaStore(useCartStore()))"],
+    ['svelte', "registerStore('cart', svelteStore(cartStore))"],
+];
+/**
+ * Libraries that hand their store to React through a context provider, and therefore need no hint.
+ *
+ * `<Provider store>` and `<QueryClientProvider client>` put the store instance in the fiber tree as
+ * a prop, so the React adapter finds and registers it on the first commit — see `auto-stores.ts` in
+ * `@reticlehq/react`. Offering a commented `registerStore` line for these was asking someone to do
+ * by hand, and be nagged about, work that is already done by the time they read the report.
+ *
+ * Everything absent from this set is module-scope (Zustand, Valtio, a MobX singleton) or needs an
+ * argument only the source supplies (Jotai atoms, an XState actor). Nothing in the running app
+ * points at those, so they still need the app to hand them over, and the hint still earns its place.
+ */
+const AUTO_DISCOVERED_DEPS = new Set([
+    '@tanstack/react-query',
+    '@reduxjs/toolkit',
+    'redux',
+]);
+/**
+ * The store libraries this app depends on AND the running app cannot reveal on its own, as
+ * ready-to-uncomment registration lines.
+ */
+export function storeHints(deps) {
+    return STORE_LIBRARIES.filter(([dep]) => deps.has(dep) && !AUTO_DISCOVERED_DEPS.has(dep)).map(([, hint]) => hint);
+}
+/**
+ * Store factories whose EXPORTED result is the store instance itself — the form `registerStore`
+ * takes directly. Each is gated on the app actually depending on that library, so a local helper
+ * called `create` in an app with no store library is never mistaken for one.
+ *
+ * Deliberately short. The adapter-wrapped libraries (Jotai, XState, Valtio, MobX, TanStack Query)
+ * need an argument we cannot infer — which atoms, which actor, which queryClient — so they keep the
+ * commented hint. Guessing there produces a module that throws on import, which is strictly worse
+ * than a comment.
+ */
+const STORE_FACTORIES = [
+    ['zustand', 'create'],
+    ['@reduxjs/toolkit', 'configureStore'],
+    ['redux', 'createStore'],
+];
+/** `export const useCart = create<S>()(...)` / `export const store = configureStore({...})`. */
+function storeDeclaration(factory) {
+    return new RegExp(`export\\s+const\\s+([A-Za-z_$][\\w$]*)\\s*=\\s*${factory}\\s*[<(]`, 'g');
+}
+/**
+ * `src/cart-store.ts` → `cart`; `src/store.ts` → `app`. The key is what the agent reads state under,
+ * so it has to be stable and distinct — two stores sharing one key would silently overwrite.
+ */
+function storeKey(path, taken) {
+    const file = (path.split('/').pop() ?? '').replace(/\.[^.]+$/, '');
+    const base = file.replace(/[-_.]?stores?$/i, '').replace(/[^a-z0-9]+/gi, '-') || 'app';
+    const key = base.toLowerCase();
+    if (!taken.has(key))
+        return key;
+    for (let n = 2;; n += 1) {
+        const candidate = `${key}-${String(n)}`;
+        if (!taken.has(candidate))
+            return candidate;
+    }
+}
+/**
+ * Module specifier for `store.ts` as seen FROM the generated dev module.
+ *
+ * The dev module is not always a sibling: Vite puts it at `src/reticle-dev.ts`, Next at
+ * `app/reticle-dev.tsx` or `src/app/reticle-dev.tsx`. A specifier computed for one is dead in the
+ * other, and a dead import in this file breaks the module every other capability hangs off — so the
+ * relative path is computed, not assumed.
+ */
+function importPathFor(storePath, fromDir) {
+    const noExt = storePath.replace(/\.[^./]+$/, '');
+    const rel = posix.relative(fromDir, noExt);
+    return rel.startsWith('.') ? rel : `./${rel}`;
+}
+/** Where the generated dev module lives, for Vite. Next passes its own. */
+const DEFAULT_DEV_MODULE_DIR = 'src';
+/**
+ * Store instances declared in the app's own source, ready to import and register.
+ *
+ * Only exported declarations of a factory the app actually depends on: anything less certain would
+ * generate an import that breaks the dev module everything else hangs off, and a broken module is
+ * worse than the commented hint it replaces.
+ */
+export function scanStores(files, deps, fromDir = DEFAULT_DEV_MODULE_DIR) {
+    const factories = STORE_FACTORIES.filter(([dep]) => deps.has(dep)).map(([, f]) => f);
+    const found = [];
+    const keys = new Set();
+    for (const { path, source } of files) {
+        for (const factory of factories) {
+            for (const m of source.matchAll(storeDeclaration(factory))) {
+                const ident = m[1];
+                if (ident === undefined)
+                    continue;
+                const key = storeKey(path, keys);
+                keys.add(key);
+                found.push({ key, ident, importPath: importPathFor(path, fromDir) });
+            }
+        }
+    }
+    return found;
+}

package/dist/closing-hint.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The last thing `init` prints, and the only part of it a user is asked to act on.
+ *
+ * Split out of `run.ts` because that file sits exactly at the 1000-line cohesion cap, and because
+ * this IS a separate concern: everything else in `run.ts` decides what to write, and this decides
+ * what to say afterwards. The two failure modes are different too — a wrong write breaks an
+ * install, a wrong sentence loses a user quietly.
+ */
+import { StepStatus } from './plan.js';
+/**
+ * The standing ask, printed at the end of every `init`.
+ *
+ * Addressed to the agent as much as the human: whichever of them just ran this command is the one
+ * holding the experience, and neither has a Reticle tool surface to file through at this point.
+ *
+ * Printed by the `runInit` wrapper, NOT by `report()` — see the comment there for why, and for how
+ * the workspace redirect is kept from asking twice.
+ */
+export declare const FEEDBACK_HINT: string;
+/**
+ * The last two lines a user reads, and the order matters.
+ *
+ * This used to say only "Restart <dev server>, then ask your agent: List Reticle sessions" — and
+ * asking the agent was the one thing that could not work yet. `init` registers the MCP server, but
+ * an agent client reads its tool list when it STARTS and never re-reads it, so the session that
+ * just ran `init` has no `reticle_*` tools however clean the install was. The user follows the
+ * instruction, the agent answers "unknown tool", and the obvious conclusion is that the install
+ * failed.
+ *
+ * So the reload is named FIRST, before the sentence that depends on it. Omitted entirely when this
+ * run did not register MCP (`--no-mcp`), where it would be advice about something we did not do.
+ */
+export declare function restartHint(mcpStatus: StepStatus | undefined, 
+/** The project's own dev command, when package.json named one. */
+devCommand?: string): string;

package/dist/closing-hint.js

@@ -0,0 +1,122 @@
+/**
+ * The last thing `init` prints, and the only part of it a user is asked to act on.
+ *
+ * Split out of `run.ts` because that file sits exactly at the 1000-line cohesion cap, and because
+ * this IS a separate concern: everything else in `run.ts` decides what to write, and this decides
+ * what to say afterwards. The two failure modes are different too — a wrong write breaks an
+ * install, a wrong sentence loses a user quietly.
+ */
+import { StepStatus } from './plan.js';
+import { wasMcpRegistered } from './mcp-registered.js';
+import { CLI } from './agent-rules.js';
+/**
+ * The standing ask, printed at the end of every `init`.
+ *
+ * Addressed to the agent as much as the human: whichever of them just ran this command is the one
+ * holding the experience, and neither has a Reticle tool surface to file through at this point.
+ *
+ * Printed by the `runInit` wrapper, NOT by `report()` — see the comment there for why, and for how
+ * the workspace redirect is kept from asking twice.
+ */
+export const FEEDBACK_HINT = 'Anything wrong, missing, or awkward — in this setup or in Reticle itself? Tell us; it is the ' +
+    'one thing that decides what gets fixed:\n' +
+    `  ${CLI} feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"   (agents)\n` +
+    `  ${CLI} feedback "what worked, what didn't"   (humans)`;
+/**
+ * What to say about the dev server.
+ *
+ * Names the project's own script when `package.json` has a recognisable one, and otherwise says the
+ * THING rather than guessing the command.
+ *
+ * The guesses that used to live here — `vite`, `next dev`, `astro dev` — were wrong often enough to
+ * be worth deleting. Measured on a real app: rowy has no `dev` script at all, so "Restart `vite`"
+ * sent the reader to work out what was meant instead of starting a server. Nobody needs the guess:
+ * an agent reading this can open package.json, and a human already knows how they start their own
+ * app. A wrong command costs more than a missing one.
+ */
+function devServerRestart(devCommand) {
+    return devCommand === undefined
+        ? 'Restart your dev server'
+        : `Restart your dev server (\`${devCommand}\`)`;
+}
+/**
+ * The last two lines a user reads, and the order matters.
+ *
+ * This used to say only "Restart <dev server>, then ask your agent: List Reticle sessions" — and
+ * asking the agent was the one thing that could not work yet. `init` registers the MCP server, but
+ * an agent client reads its tool list when it STARTS and never re-reads it, so the session that
+ * just ran `init` has no `reticle_*` tools however clean the install was. The user follows the
+ * instruction, the agent answers "unknown tool", and the obvious conclusion is that the install
+ * failed.
+ *
+ * So the reload is named FIRST, before the sentence that depends on it. Omitted entirely when this
+ * run did not register MCP (`--no-mcp`), where it would be advice about something we did not do.
+ */
+export function restartHint(mcpStatus, 
+/** The project's own dev command, when package.json named one. */
+devCommand) {
+    const dev = `${devServerRestart(devCommand)}.`;
+    // NAME THE COMMAND THAT PROVES IT, not one that merely asks.
+    //
+    // `init` writes files and stops; the install is not finished until an app carrying the SDK has
+    // actually dialled the daemon, and nothing here confirmed that. The field shape is unambiguous:
+    // people complete the agent half, never complete the app half, and keep a daemon running for
+    // weeks with nothing to drive — so this is the last instruction most of them read.
+    //
+    // "Ask your agent: List Reticle sessions" asks a question whose failure is a dead end. `reticle
+    // status` ANSWERS it: as of 2.7.0 it reports the session, or says why there is none — no app
+    // running, an app running that never dialled us, a tab that closed — with the fix for each.
+    // The one thing that works BEFORE the restart, so it goes before it.
+    //
+    // What comes after the restart, named as a JOB rather than as a capability.
+    //
+    // This used to point at a `reticle demo` command that opened its own browser and drove one
+    // control. It was cut: a demo command is a side show. The thing a user needs to see is THEIR app,
+    // instrumented in THEIR codebase, driven by THEIR agent through the tools they just installed —
+    // because that is the workflow they are deciding whether to adopt, and a bespoke demo path proves
+    // nothing about it.
+    //
+    // So the close hands the agent the sequence instead. It is deliberately one drive of one real
+    // flow ending in a verdict, because an install that ends in "the tools are available" is an
+    // install that ends in nothing.
+    const demo = 'Then drive one real flow of your app end to end and report the verdict — that is the install ' +
+        "proving itself, and it is the agent's job, not a separate command.";
+    const prove = 'Then run `npx @reticlehq/server status` — it confirms the app connected, or says exactly why ' +
+        'it has not.';
+    // Nothing registered this run (`--no-mcp`, or a client that needs a manual edit): a restart picks
+    // up nothing, so advice about one would be advice about something we did not do.
+    if (!wasMcpRegistered(mcpStatus))
+        return `${dev}\n${demo}\n${prove}`;
+    // ALREADY: the tools are reachable RIGHT NOW, and this is the branch that used to lie.
+    //
+    // `wasMcpRegistered` is true for both APPLY and ALREADY, which is correct for the funnel field it
+    // was written for and wrong here, because the two cases have opposite answers to "must anybody
+    // restart". Every second project on a machine, and every Claude Code plugin install, took the
+    // APPLY text: "restart your agent — the tools only appear after that". An agent reads this AFTER
+    // whatever its skill file said, and it describes the output in front of it, so it wins. The agent
+    // stops with the project wired and nothing driven, which is the exact failure the install path
+    // exists to prevent, caused by the install path itself.
+    if (mcpStatus === StepStatus.ALREADY) {
+        return (`${dev}\n` +
+            `${demo}\n` +
+            'The Reticle MCP server was already registered on this machine, so there is no restart to do ' +
+            'and the tools are available now.\n' +
+            `${prove}\n` +
+            'Once it shows a session, drive a flow — that is the install finished. Carry straight on; ' +
+            'nothing here is waiting on a human.');
+    }
+    return (`${dev}\n` +
+        `${demo}\n` +
+        'Then restart your agent so it picks up the new MCP server. On Claude Code and Codex, do NOT ' +
+        'ask a human to do it: `npx @reticlehq/server init --relaunch` prints the exact resume command ' +
+        'for THIS conversation — run that command and the restart continues the work on the other ' +
+        'side. Everywhere else it is a human step — reload the window in Cursor, or hit Start in ' +
+        '`.vscode/mcp.json` in VS Code — so name the one that applies and ask for that alone.\n' +
+        'The tools only appear after that: your agent read its server list before Reticle existed, ' +
+        'and no slash command re-reads it (`/mcp` manages servers already loaded, so it cannot pick ' +
+        'up a new one). This is once per machine — Reticle is registered globally, so every later ' +
+        'project starts with the tools already there.\n' +
+        `${prove}\n` +
+        'Once it shows a session, drive one flow and report the verdict — that is the install ' +
+        'finished. Do it now; nothing here is waiting on a human.');
+}

package/dist/codex-toml.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The `command` and `args` strings the config declares for our server, or `[]` when it declares
+ * none — including when the shape was not one this scanner reads.
+ *
+ * Handles the three forms a Codex config actually takes: the standard table header, a dotted
+ * assignment (`mcp_servers.reticle = { … }`), and a key inside an `[mcp_servers]` table.
+ */
+export declare function codexServerTokens(existing: string | null, serversKey: string): string[];
+/** Does this config already declare a Reticle server under our name? */
+export declare function codexDeclaresOurServer(existing: string | null, serversKey: string): boolean;