@reticlehq/server 2.4.0 → 2.5.0

package/dist/init/run.js

@@ -4,7 +4,42 @@
  * access goes through `InitIo` so the orchestration is unit-testable with an in-memory IO.
  */
 import { dirname, join } from 'node:path';
+import { spanSync } from '../trace.js';
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { detect, Framework } from './detect.js';
+import { wasMcpRegistered } from './mcp-registered.js';
+import { pickAstroHost } from './astro-host.js';
+import { workspaceParents } from './workspace-apps.js';
+import { chooseWorkspaceApp } from './app-choice.js';
+import { isConnectStep } from './plan.js';
+import { CURSOR_RULE_PATH } from './agent-rules.js';
+import { CRA_ENV_PATH } from './cra.js';
+/** CRA's bundled entry, in the order create-react-app itself generates them. */
+const CRA_ENTRY_CANDIDATES = ['src/index.tsx', 'src/index.jsx', 'src/index.ts', 'src/index.js'];
+function craEntryOf(io) {
+    for (const path of CRA_ENTRY_CANDIDATES) {
+        const source = io.readFile(path);
+        if (source !== null)
+            return { path, source };
+    }
+    return null;
+}
+/**
+ * The daemon's pairing token, for the one stack that cannot read it at build time.
+ *
+ * Every other framework's snippet reads this file in Node when the dev server starts, so the token
+ * is never written into the project. CRA bundles browser code and inlines only REACT_APP_*, so it
+ * has to be materialised into .env.development.local — which CRA's own template gitignores.
+ */
+function readPairingToken() {
+    try {
+        return readFileSync(join(homedir(), '.reticle', 'pairing-token'), 'utf8').trim();
+    }
+    catch {
+        return '';
+    }
+}
 import { DEPS_TARGET, MCP_TARGET, buildPlan, StepStatus, } from './plan.js';
 import { claudeAvailableProbe, claudeExistsProbe } from './mcp.js';
 import { reticleDevLocation } from './next-patch.js';
@@ -13,7 +48,7 @@ import { CURSOR_DIR_RELPATH, CURSOR_MCP_RELPATH } from './cursor.js';
 import { deriveProjectId, packageName } from './project-id.js';
 import { VITE_DEV_MODULE_PATH } from './snippets.js';
 import { CLAUDE_COMMAND_PATH, CURSOR_COMMAND_PATH } from './slash-command.js';
-import { SERVER_VERSION } from '../server-version.js';
+import { SERVER_VERSION } from '../version/server-version.js';
 import { InitFailure, reportInitOutcome } from '../telemetry/init-telemetry.js';
 /** Lockfile basenames, in package-manager preference order (mirrors detect.ts). */
 const LOCKFILE_NAMES = [
@@ -108,6 +143,16 @@ const VITE_CONFIG_CANDIDATES = [
     'vite.config.mjs',
     'vite.config.mts',
 ];
+const ASTRO_CONFIG_CANDIDATES = [
+    'astro.config.mjs',
+    'astro.config.js',
+    'astro.config.ts',
+    'astro.config.cjs',
+];
+/** Where a conventional Astro app keeps the layout every page wraps itself in. */
+const ASTRO_LAYOUTS_DIR = 'src/layouts';
+/** Also searched: an app with no layouts directory renders the document straight from a page. */
+const ASTRO_PAGES_DIR = 'src/pages';
 const NEXT_CONFIG_CANDIDATES = [
     'next.config.mjs',
     'next.config.js',
@@ -119,6 +164,21 @@ const NEXT_CONFIG_CANDIDATES = [
  * decide whether the install finished. A notice gets its own mark so "steps remaining" can reach zero
  * on a working install that happens to be on an ungated stack.
  */
+/**
+ * A step's status AFTER the run, which is what actually happened to it.
+ *
+ * `report` applies the same downgrade when printing: a step that failed or was skipped is shown as
+ * MANUAL whatever it planned to be. Reading the planned status alone would say a step applied when
+ * the run had already given up on it.
+ */
+function resolvedStatus(plan, target, failed, skipped) {
+    const step = plan.steps.find((s) => s.target === target);
+    if (step === undefined)
+        return undefined;
+    if (failed.has(target) || skipped.has(target))
+        return StepStatus.MANUAL;
+    return step.status;
+}
 const STATUS_SYMBOL = {
     [StepStatus.APPLY]: '✓',
     [StepStatus.MANUAL]: '⚠',
@@ -138,7 +198,7 @@ function gatherPlanInput(options, io, pkgRaw) {
     const projectId = deriveProjectId(packageName(pkg), options.cwd);
     const rootFiles = new Set(io.rootFiles());
     const detectInput = {
-        pkg: typeof pkg === 'object' && pkg !== null ? pkg : {},
+        pkg: 'object' === typeof pkg && pkg !== null ? pkg : {},
         configFiles: rootFiles,
         // Walk up for the lockfile so a monorepo sub-package picks the workspace's package manager.
         lockfiles: resolveLockfiles(rootFiles, options.cwd, io),
@@ -147,7 +207,7 @@ function gatherPlanInput(options, io, pkgRaw) {
     };
     const detection = detect(detectInput);
     const vitePath = firstPresent(rootFiles, VITE_CONFIG_CANDIDATES);
-    const viteSource = vitePath === null ? null : io.readFile(vitePath);
+    const viteSource = null === vitePath ? null : io.readFile(vitePath);
     const viteConfig = vitePath !== null && viteSource !== null ? { path: vitePath, source: viteSource } : null;
     // Global MCP registration targets each agent that's present: Claude via its CLI, Cursor via its
     // global config file. Only probe when the MCP step is in play.
@@ -155,16 +215,36 @@ function gatherPlanInput(options, io, pkgRaw) {
     const claudeCli = options.mcp ? io.probe(availableProbe.command, availableProbe.args) : false;
     const existsProbe = claudeExistsProbe();
     const mcpExists = claudeCli ? io.probe(existsProbe.command, existsProbe.args) : false;
-    const cursorDir = `${io.homeDir()}/${CURSOR_DIR_RELPATH}`;
-    const cursorConfigPath = `${io.homeDir()}/${CURSOR_MCP_RELPATH}`;
-    const cursorPresent = options.mcp && io.exists(cursorDir);
+    // join(), not a literal '/': this path is checked and WRITTEN on the user's machine, and a
+    // backslash platform silently misses the config it is meant to find.
+    const cursorDir = join(io.homeDir(), CURSOR_DIR_RELPATH);
+    const cursorConfigPath = join(io.homeDir(), CURSOR_MCP_RELPATH);
+    // Cursor is "present" if its global config directory exists OR the project carries a `.cursor/`.
+    // The directory alone missed a real case: Cursor installed with a FRESH profile has not written
+    // ~/.cursor yet, so a user who had it open got no Cursor step and no message about one. A
+    // project-level .cursor/ is unambiguous evidence somebody uses it here.
+    const cursorPresent = options.mcp && (io.exists(cursorDir) || io.exists(CURSOR_DIR_RELPATH));
     const cursorConfig = cursorPresent ? io.readFile(cursorConfigPath) : null;
+    const astroPath = firstPresent(rootFiles, ASTRO_CONFIG_CANDIDATES);
+    const astroSource = null === astroPath ? null : io.readFile(astroPath);
+    // Which file owns the DOCUMENT, not how many files sit in a directory. The old rule ("exactly one
+    // .astro in src/layouts") fired on neither real Astro app: one has no layouts directory and
+    // renders from src/pages/index.astro, the other has three files there of which two are partials.
+    // `</body>` is the discriminator — see astro-host.
+    const astroCandidates = [ASTRO_LAYOUTS_DIR, ASTRO_PAGES_DIR].flatMap((dir) => io
+        .listFiles(dir)
+        .filter((f) => f.endsWith('.astro'))
+        .map((f) => ({ path: `${dir}/${f}`, source: io.readFile(`${dir}/${f}`) }))
+        .filter((c) => c.source !== null));
+    const astroHost = pickAstroHost(astroCandidates);
+    const layoutRelPath = astroHost?.path ?? null;
+    const astroLayoutSource = astroHost?.source ?? null;
     const nextConfigFile = firstPresent(rootFiles, NEXT_CONFIG_CANDIDATES);
     // App Router first; a Pages Router app has no layout, and its mount point is pages/_app.
-    const layoutPath = (NEXT_LAYOUT_CANDIDATES.find((p) => io.exists(p)) ??
-        NEXT_PAGES_APP_CANDIDATES.find((p) => io.exists(p))) ??
+    const layoutPath = NEXT_LAYOUT_CANDIDATES.find((p) => io.exists(p)) ??
+        NEXT_PAGES_APP_CANDIDATES.find((p) => io.exists(p)) ??
         null;
-    const layoutSource = layoutPath === null ? null : io.readFile(layoutPath);
+    const layoutSource = null === layoutPath ? null : io.readFile(layoutPath);
     // Where the component goes depends on WHICH router mounts it: `pages/` routes on presence, so a
     // component there becomes a broken route; `app/` routes on filename, so a sibling is inert.
     const devLocation = reticleDevLocation(layoutPath ?? 'app/layout.tsx', detection.typescript);
@@ -177,8 +257,12 @@ function gatherPlanInput(options, io, pkgRaw) {
         cursorConfig,
         cursorConfigPath,
         viteConfig,
+        astroConfig: astroPath !== null && astroSource !== null ? { path: astroPath, source: astroSource } : null,
+        astroLayout: layoutRelPath !== null && astroLayoutSource !== null
+            ? { path: layoutRelPath, source: astroLayoutSource }
+            : null,
         nextConfigFile,
-        nextConfigSource: nextConfigFile === null ? null : io.readFile(nextConfigFile),
+        nextConfigSource: null === nextConfigFile ? null : io.readFile(nextConfigFile),
         nextLayout: layoutPath !== null && layoutSource !== null
             ? { path: layoutPath, source: layoutSource }
             : null,
@@ -190,13 +274,16 @@ function gatherPlanInput(options, io, pkgRaw) {
         nextReticleDevImport: devLocation.importSpecifier,
         nextReticleDevExists: io.exists(devLocation.path),
         svelteKitHooksExists: io.exists(SVELTEKIT_HOOKS),
+        craEntry: craEntryOf(io),
+        craEnv: io.readFile(CRA_ENV_PATH),
+        pairingToken: readPairingToken(),
         reticleConfigExists: io.exists('.reticle.json'),
         // Read the agent instruction files so the rule merge stays idempotent across re-runs.
         claudeMdContent: io.readFile('CLAUDE.md'),
         agentsMdContent: io.readFile('AGENTS.md'),
-        cursorRuleExists: io.exists('.cursor/rules/reticle.mdc'),
-        claudeCommandExists: io.exists(CLAUDE_COMMAND_PATH),
-        cursorCommandExists: io.exists(CURSOR_COMMAND_PATH),
+        cursorRuleContent: io.readFile(CURSOR_RULE_PATH),
+        claudeCommandContent: io.readFile(CLAUDE_COMMAND_PATH),
+        cursorCommandContent: io.readFile(CURSOR_COMMAND_PATH),
         options: {
             port: options.port,
             mcp: options.mcp,
@@ -208,12 +295,13 @@ function gatherPlanInput(options, io, pkgRaw) {
     };
 }
 /** Where workspace tooling conventionally puts packages. */
-const WORKSPACE_PARENTS = ['apps', 'packages'];
+/** pnpm's workspace declaration, read when present — it is authoritative about where packages live. */
+const PNPM_WORKSPACE = 'pnpm-workspace.yaml';
 /** Deps that mark a directory as a runnable web app even when it has no bundler config file. */
 const APP_DEPS = ['next', 'vite'];
 function looksLikeApp(dir, io) {
     const pkgRaw = io.readFile(`${dir}/${PACKAGE_JSON}`);
-    if (pkgRaw === null)
+    if (null === pkgRaw)
         return false;
     const configs = [...VITE_CONFIG_CANDIDATES, ...NEXT_CONFIG_CANDIDATES];
     if (configs.some((c) => io.exists(`${dir}/${c}`)))
@@ -231,14 +319,40 @@ function looksLikeApp(dir, io) {
  */
 export function findWorkspaceApps(io) {
     const found = [];
-    for (const parent of WORKSPACE_PARENTS) {
+    // A workspace DECLARES its packages; `['apps','packages']` was a guess that missed a real repo
+    // with three Next apps at web/, admin/ and space/ — and missing them meant init ran against the
+    // root and reported ✓ for a file Next never compiles. See workspace-apps.
+    const pkgRaw = io.readFile(PACKAGE_JSON);
+    let pkgWorkspaces;
+    try {
+        const parsed = null === pkgRaw ? undefined : JSON.parse(pkgRaw);
+        pkgWorkspaces =
+            'object' === typeof parsed && parsed !== null
+                ? parsed.workspaces
+                : undefined;
+    }
+    catch {
+        pkgWorkspaces = undefined;
+    }
+    const parents = workspaceParents({
+        ...(null === io.readFile(PNPM_WORKSPACE)
+            ? {}
+            : { pnpmWorkspace: io.readFile(PNPM_WORKSPACE) ?? '' }),
+        ...(pkgWorkspaces === undefined ? {} : { pkgWorkspaces }),
+        topLevelDirs: io.listDirs('.'),
+    });
+    // A declared parent can itself BE the app (`workspaces: ["web"]`), so check both the directory and
+    // its children rather than assuming one level of nesting.
+    for (const parent of parents) {
+        if (looksLikeApp(parent, io))
+            found.push(parent);
         for (const name of io.listDirs(parent)) {
             const dir = `${parent}/${name}`;
             if (looksLikeApp(dir, io))
                 found.push(dir);
         }
     }
-    return found;
+    return [...new Set(found)];
 }
 function restartHint(framework) {
     if (framework === Framework.NEXT)
@@ -253,13 +367,26 @@ function restartHint(framework) {
 }
 const SKIPPED_DETAIL = 'skipped — the dependency install above failed, and wiring the app to a package that is not ' +
     'installed stops it booting. Run that install, then re-run `reticle init`.';
-function report(plan, dryRun, failed, skipped, io) {
+function report(plan, dryRun, failed, skipped, degraded, io) {
     io.print(dryRun ? 'reticle init (dry run — no files written)' : 'reticle init');
     io.print('');
     let applied = 0;
     let manual = 0;
+    // A ⚠ on a CONNECT step is a guaranteed failure, not a caveat: nothing performs the manual step, so
+    // the app never dials the daemon and every tool answers "no browser session connected". `ok` was
+    // hardcoded true, so a run that could not possibly work reported success.
+    let connectPending = false;
     for (const s of plan.steps) {
         // A side effect that failed to apply is reported as a manual step with its fallback command.
+        const note = degraded.get(s.target);
+        if (note !== undefined) {
+            // Applied, but not the way it was asked for. A NOTICE, not work — the install did happen.
+            io.print(`  [${STATUS_SYMBOL[StepStatus.NOTICE]}] ${s.title} → ${s.target}`);
+            for (const line of note.split('\n'))
+                io.print(`      ${line}`);
+            applied++;
+            continue;
+        }
         const downgraded = failed.has(s.target) || skipped.has(s.target);
         const status = downgraded ? StepStatus.MANUAL : s.status;
         const detail = skipped.has(s.target)
@@ -272,8 +399,11 @@ function report(plan, dryRun, failed, skipped, io) {
             applied++;
         if (status === StepStatus.MANUAL || status === StepStatus.NOTICE) {
             // A notice prints in full like a manual step — it is worth reading — but is NOT counted as work.
-            if (status === StepStatus.MANUAL)
+            if (status === StepStatus.MANUAL) {
                 manual++;
+                if (isConnectStep(s.title))
+                    connectPending = true;
+            }
             for (const line of detail.split('\n'))
                 io.print(`      ${line}`);
         }
@@ -282,8 +412,13 @@ function report(plan, dryRun, failed, skipped, io) {
         }
     }
     io.print('');
+    if (connectPending) {
+        io.print('This app will NOT connect until the ⚠ step above is done by hand — Reticle tools will report ' +
+            '"no browser session connected" until then. Everything else is already in place.');
+        io.print('');
+    }
     io.print(restartHint(plan.framework));
-    return { ok: true, applied, manual };
+    return { ok: !connectPending, applied, manual };
 }
 /**
  * Perform the apply-step side effects; return the targets whose side effect failed.
@@ -297,23 +432,48 @@ function report(plan, dryRun, failed, skipped, io) {
 function applyEffects(plan, io) {
     const failed = new Set();
     const skipped = new Set();
+    const degraded = new Map();
     let installFailed = false;
     for (const s of plan.steps) {
         if (s.status !== StepStatus.APPLY)
             continue;
-        if (installFailed && s.dependsOnInstall === true) {
+        if (installFailed && true === s.dependsOnInstall) {
             skipped.add(s.target);
             continue;
         }
-        if (s.write !== undefined)
-            io.writeFile(s.write.path, s.write.content);
-        if (s.exec !== undefined && !io.exec(s.exec.command, s.exec.args)) {
+        const write = s.write;
+        if (write !== undefined) {
+            spanSync('init.write', { target: s.target, path: write.path }, () => {
+                io.writeFile(write.path, write.content);
+            });
+        }
+        // Bound once so the traced call cannot need a `?? ''` fallback — a default there would turn a
+        // narrowing mistake into an empty command that silently "succeeds".
+        const exec = s.exec;
+        // Per-step, because the interesting part of init's wall-clock is WHICH step spent it: a
+        // package-manager install and a `claude mcp add` are both subprocesses, and one of them being
+        // slow is a completely different problem from the other.
+        if (exec !== undefined &&
+            !spanSync('init.exec', { target: s.target, command: exec.command }, () => io.exec(exec.command, exec.args))) {
+            // A weaker second attempt beats no install at all — but only when it is REPORTED, because the
+            // thing it gives up is the version pin that keeps SDK and daemon in step.
+            //
+            // Traced separately, and it is the reason init can take twice as long as it looks like it
+            // should: this is a SECOND full package-manager run, and until it had its own span 1.6 of
+            // init's 2.3 seconds simply vanished — the span above accounted for the first attempt and
+            // nothing accounted for this one.
+            const retry = s.retry;
+            if (retry !== undefined &&
+                spanSync('init.exec.retry', { target: s.target, command: retry.command }, () => io.exec(retry.command, retry.args))) {
+                degraded.set(s.target, retry.note);
+                continue;
+            }
             failed.add(s.target);
             if (s.target === DEPS_TARGET)
                 installFailed = true;
         }
     }
-    return { failed, skipped };
+    return { failed, skipped, degraded };
 }
 /**
  * Which STEP failed, from the step targets — not from an error string, which would carry paths.
@@ -338,25 +498,35 @@ const AMBIGUOUS_HEADER = 'Several apps found in this workspace. Re-run `reticle
  * Returns null when there is nothing to redirect to — the caller then proceeds here as before.
  */
 function redirectToWorkspaceApp(options, io, pkgRaw) {
-    if (options.redirected === true)
+    if (true === options.redirected)
         return null;
     const pkg = JSON.parse(pkgRaw);
     const rootFiles = new Set(io.rootFiles());
     const here = detect({
-        pkg: typeof pkg === 'object' && pkg !== null ? pkg : {},
+        pkg: 'object' === typeof pkg && pkg !== null ? pkg : {},
         configFiles: rootFiles,
         lockfiles: new Set(),
     });
     if (here.framework !== Framework.HTML)
         return null; // this directory IS the app
     const apps = findWorkspaceApps(io);
-    const target = apps.length === 1 ? apps[0] : undefined;
+    // An explicitly named app answers the ambiguity. Refusing to guess is right, but "re-run inside the
+    // one you want" is not something a script, a CI step, or an agent that cannot change directory can
+    // act on — so the refusal was a dead end for exactly the callers most likely to hit it.
+    const chosen = chooseWorkspaceApp(options.app, apps);
+    if (!chosen.ok) {
+        io.print(chosen.message);
+        return { ok: false, applied: 0, manual: 1 };
+    }
+    const target = chosen.app ?? (1 === apps.length ? apps[0] : undefined);
     if (target === undefined) {
-        if (apps.length === 0)
+        if (0 === apps.length)
             return null; // not a workspace — fall through to the normal HTML plan
         io.print(AMBIGUOUS_HEADER);
         for (const a of apps)
             io.print(`  ${a}`);
+        io.print('');
+        io.print(`Or name one without changing directory:  reticle init --app ${apps[0] ?? '<dir>'}`);
         return { ok: false, applied: 0, manual: apps.length };
     }
     io.print(`No app in this directory — wiring ${target} instead.`);
@@ -365,7 +535,7 @@ function redirectToWorkspaceApp(options, io, pkgRaw) {
 }
 export function runInit(options, io) {
     const pkgRaw = io.readFile(PACKAGE_JSON);
-    if (pkgRaw === null) {
+    if (null === pkgRaw) {
         io.print('No package.json found. Run `reticle init` from your project root.');
         // The onboarding funnel had NO instrumentation, so a setup that died here was indistinguishable
         // from someone who never ran the command — the two failure modes with the most different fixes.
@@ -375,19 +545,23 @@ export function runInit(options, io) {
     const redirected = redirectToWorkspaceApp(options, io, pkgRaw);
     if (redirected !== null)
         return redirected;
-    const plan = buildPlan(gatherPlanInput(options, io, pkgRaw));
+    // Init is the flow a user experiences the wait of personally, and the fixture gate measures it at
+    // 1–6s per app with no explanation of the spread. These three spans split that number into detect
+    // (filesystem probing), plan (pure), and apply (writes + package-manager and CLI subprocesses).
+    const plan = spanSync('init.plan', {}, () => buildPlan(gatherPlanInput(options, io, pkgRaw)));
     const effects = options.dryRun
-        ? { failed: new Set(), skipped: new Set() }
-        : applyEffects(plan, io);
-    const { failed, skipped } = effects;
-    const result = report(plan, options.dryRun, failed, skipped, io);
+        ? { failed: new Set(), skipped: new Set(), degraded: new Map() }
+        : spanSync('init.apply', { steps: plan.steps.length }, () => applyEffects(plan, io));
+    const { failed, skipped, degraded } = effects;
+    const result = report(plan, options.dryRun, failed, skipped, degraded, io);
     // A dry run is a preview, not an outcome — reporting it would inflate both success and failure.
     if (!options.dryRun) {
         reportInitOutcome({
             ok: result.ok,
             ...(result.ok ? {} : { reason: classifyInitFailure(failed) }),
             stack: plan.framework,
-            mcpRegistered: !failed.has(MCP_TARGET),
+            // The step's REAL final status, not the absence of a failure — see mcp-registered.
+            mcpRegistered: wasMcpRegistered(resolvedStatus(plan, MCP_TARGET, failed, skipped)),
         });
     }
     return result;

package/dist/init/slash-command.d.ts

@@ -15,4 +15,13 @@
 export declare const CLAUDE_COMMAND_PATH = ".claude/commands/reticle.md";
 /** Cursor reads them from `.cursor/commands/<name>.md`. */
 export declare const CURSOR_COMMAND_PATH = ".cursor/commands/reticle.md";
+/**
+ * The frontmatter line that marks a command file as OURS.
+ *
+ * A stale command has to be refreshable — a file frozen at whatever release created it can never be
+ * improved for anyone who already ran init — but the path is one a human may have claimed for their
+ * own `/reticle`, and overwriting that would be destroying somebody's work. This line is how the two
+ * are told apart.
+ */
+export declare const SLASH_COMMAND_SIGNATURE = "description: Verify this app in the browser with Reticle";
 export declare const SLASH_COMMAND_BODY = "---\ndescription: Verify this app in the browser with Reticle \u2014 drive one real flow and report what happened.\n---\n\nVerify this running app with Reticle. Drive it; do not read the code and guess.\n\n## Pick ONE flow\n\nNot the whole app. Pick the single most important flow you can complete in a handful of steps \u2014 the\none a user would do first (sign in, search, add to cart, submit the form). If the user named a flow or\njust changed some code, use that one instead.\n\nState which flow you picked in one line before you start.\n\n## Drive it where the human can see\n\n1. `reticle_sessions` \u2014 find the connected tab. None? Tell the user to run their dev server and open\n   the app, then stop. Reticle never starts a dev server.\n2. `reticle_snapshot` \u2014 read the accessibility tree and locate the elements the flow needs. Elements\n   are addressable by role and name; you do **not** need `data-testid` to drive them.\n3. Walk the flow with `reticle_act_and_wait`, one step at a time. Narrate each step first \u2014 the human\n   is watching the page, and the HUD shows what you say.\n4. After each step, check the effect with `reticle_assert` \u2014 not just that the click dispatched, but\n   that the thing it was supposed to do actually happened.\n5. Finish with `reticle_console` and `reticle_network` to catch errors the DOM does not show.\n\n## Report\n\n- What you drove, step by step, and what each step actually produced.\n- Anything broken, with the `file:line` Reticle gave you.\n- If a step could not be verified, say so plainly. \"Unknown\" is a real answer; a green verdict you\n  cannot back is not.\n\nDo not weaken or skip an assertion to make the run pass \u2014 that is a finding, not a fix.\n";

package/dist/init/slash-command.js

@@ -15,8 +15,17 @@
 export const CLAUDE_COMMAND_PATH = '.claude/commands/reticle.md';
 /** Cursor reads them from `.cursor/commands/<name>.md`. */
 export const CURSOR_COMMAND_PATH = '.cursor/commands/reticle.md';
+/**
+ * The frontmatter line that marks a command file as OURS.
+ *
+ * A stale command has to be refreshable — a file frozen at whatever release created it can never be
+ * improved for anyone who already ran init — but the path is one a human may have claimed for their
+ * own `/reticle`, and overwriting that would be destroying somebody's work. This line is how the two
+ * are told apart.
+ */
+export const SLASH_COMMAND_SIGNATURE = 'description: Verify this app in the browser with Reticle';
 export const SLASH_COMMAND_BODY = `---
-description: Verify this app in the browser with Reticle — drive one real flow and report what happened.
+${SLASH_COMMAND_SIGNATURE} — drive one real flow and report what happened.
 ---
 
 Verify this running app with Reticle. Drive it; do not read the code and guess.

package/dist/init/snippets.d.ts

@@ -15,19 +15,16 @@ export declare function nextConfigManual(configFile: string): string;
  * setup ended at `bridge refused the connection: authentication failed` and no session ever appeared.
  */
 export declare function nextReticleDevFile(port: number | undefined, projectId?: string, testids?: readonly string[], stores?: readonly string[]): string;
+export declare function astroManual(port: number | undefined, projectId?: string, 
 /**
- * Astro connect instructions.
+ * A layout file that actually exists, when one does.
  *
- * Astro is Vite-based but SSRs its own HTML, so the plugin's index.html injection never fires, and
- * `vite` is not a direct dependency — so this used to fall through to the generic HTML advice, which
- * tells you to add a connect to an "entry module" Astro does not have, or to bundle the SDK with
- * esbuild. Both are wrong for Astro, and following either gets you nothing.
- *
- * Astro bundles a page `<script>`, so the bare import resolves there. The token has to be inlined by
- * the config because there is no plugin in the page's path to inject it, and `build.target` has to be
- * raised or Astro down-levels the modern SDK bundle and dies on a destructuring transform.
+ * Reported from the field: on `examples/framework-react` — which has no layout at all, only
+ * `src/pages/index.astro` — init printed thirty lines telling the user to paste into "your
+ * layout". Instructions that name a file the project does not have read as a mistake by the
+ * reader, and cost them the time it takes to go and confirm it is missing.
  */
-export declare function astroManual(port: number | undefined, projectId?: string): string;
+layoutPath?: string): string;
 /**
  * The app-side dev module the Vite plugin imports by convention.
  *

package/dist/init/snippets.js

@@ -47,9 +47,9 @@ export function nextConfigManual(configFile) {
  */
 export function nextReticleDevFile(port, projectId, testids = [], stores = []) {
     const base = connectArg(port, projectId);
-    const fields = base === '' ? '' : `${base.slice(1, -1).trim()}, `;
+    const fields = '' === base ? '' : `${base.slice(1, -1).trim()}, `;
     const ids = testids.map((t) => `'${t}'`).join(', ');
-    const storeBlock = stores.length === 0
+    const storeBlock = 0 === stores.length
         ? '      // No state library detected. If you add one, register it here — see docs/usage.md.'
         : stores.map((h) => `      // import your store, then: ${h}`).join('\n');
     return `'use client';
@@ -73,7 +73,7 @@ export function ReticleDev() {
       // form wires \`subscribe\` too, so every mutation emits a diff; the getter form is read-only.
 ${storeBlock}
       registerCapabilities({
-        testids: [${ids}],${testids.length === 0 ? ' // none found — add data-testid to your key elements' : ''}
+        testids: [${ids}],${0 === testids.length ? ' // none found — add data-testid to your key elements' : ''}
         signals: [], // names you pass to reticle.signal()
         stores: [], // the keys you registered above
       });
@@ -95,8 +95,28 @@ ${storeBlock}
  * the config because there is no plugin in the page's path to inject it, and `build.target` has to be
  * raised or Astro down-levels the modern SDK bundle and dies on a destructuring transform.
  */
-export function astroManual(port, projectId) {
-    const extra = port !== undefined && port !== RETICLE_DEFAULT_PORT ? `\n          url: '${bridgeWsUrl(port)}',` : '';
+/**
+ * Name the file the connect <script> should go in — the layout when one exists, otherwise the page,
+ * because a project with no layout has nowhere else to put it and should not be told otherwise.
+ */
+function layoutHost(layoutPath) {
+    return layoutPath === undefined
+        ? '2. This project has no layout, so put it in the page you want instrumented (e.g.\n   src/pages/index.astro) — every page you want a session from needs it — inside <body>:'
+        : `2. In ${layoutPath} (or any other page you want instrumented), inside <body>:`;
+}
+export function astroManual(port, projectId, 
+/**
+ * A layout file that actually exists, when one does.
+ *
+ * Reported from the field: on `examples/framework-react` — which has no layout at all, only
+ * `src/pages/index.astro` — init printed thirty lines telling the user to paste into "your
+ * layout". Instructions that name a file the project does not have read as a mistake by the
+ * reader, and cost them the time it takes to go and confirm it is missing.
+ */
+layoutPath) {
+    const extra = port !== undefined && port !== RETICLE_DEFAULT_PORT
+        ? `\n          url: '${bridgeWsUrl(port)}',`
+        : '';
     const id = projectId !== undefined && projectId.length > 0 ? `\n          projectId: '${projectId}',` : '';
     return `Astro renders its own HTML, so the connect goes in a page <script> and the pairing token is inlined by the config.
 
@@ -125,7 +145,7 @@ export function astroManual(port, projectId) {
     },
   });
 
-2. In your layout (or the page you want instrumented), inside <body>:
+${layoutHost(layoutPath)}
 
   <script>
     if (import.meta.env.DEV) {
@@ -153,7 +173,7 @@ Start the daemon BEFORE \`astro dev\`, so the token file exists when the config
  */
 export function viteDevModuleFile(testids, stores) {
     const ids = testids.map((t) => `'${t}'`).join(', ');
-    const storeBlock = stores.length === 0
+    const storeBlock = 0 === stores.length
         ? '  // No state library detected. If you add one, register it here — see docs/usage.md.'
         : stores.map((h) => `  // import your store, then: ${h}`).join('\n');
     return `// Dev-only. Imported automatically by @reticlehq/vite-plugin — you do not need to import it.
@@ -173,7 +193,7 @@ if (import.meta.env.DEV) {
 ${storeBlock}
 
   registerCapabilities({
-    testids: [${ids}],${testids.length === 0 ? ' // none found — add data-testid to your key elements' : ''}
+    testids: [${ids}],${0 === testids.length ? ' // none found — add data-testid to your key elements' : ''}
     signals: [], // names you pass to reticle.signal()
     stores: [], // the keys you registered above
   });
@@ -203,10 +223,11 @@ export function htmlManual(port, projectId) {
   • Bundled app (Create React App, webpack, Parcel, Vue/Svelte CLI, etc.) — add to your ENTRY module
     (e.g. src/index.js or src/main.js), where '@reticlehq/react' resolves through your bundler:
 
-      if (location.hostname === 'localhost') {
-        const { reticle, install } = await import('@reticlehq/react');
-        install();
-        reticle.connect(${arg});
+      if (window.location.hostname === 'localhost') {
+        void import('@reticlehq/react').then(({ reticle, install }) => {
+          install();
+          reticle.connect(${arg});
+        });
       }
 
   • Plain static HTML with no build step — the browser can't resolve the bare '@reticlehq/react' import, so
@@ -226,7 +247,7 @@ export const SVELTEKIT_HOOKS_PATH = 'src/hooks.client.ts';
  * here is the one thing this project exists not to do.
  */
 export function unverifiedUiLibraryNote(library) {
-    return `Detected a ${library} app. Reticle's DOM, network, console and state tools work here, but @reticlehq/react is a React adapter: component names and data-reticle-source file:line will be missing, and no CI gate covers ${library}. Gated today: Vite + React, Next.js, Remix, Astro. If something doesn't work, please open an issue.`;
+    return `Detected a ${library} app. Reticle's DOM, network, console and state tools work here, and source file:line does too — the build plugin stamps data-reticle-source regardless of UI library (measured on preact and svelte). What @reticlehq/react adds and you will NOT get is React component identity: component names and component stacks. No CI gate covers ${library}. Gated today: Vite + React, Next.js, Remix, Astro. If something doesn't work, please open an issue.`;
 }
 export const UNVERIFIED_FRAMEWORK_NOTE = 'Reticle has no SvelteKit app and no CI gate for one, so this wiring is untested — it may work, but nothing proves it and nothing will tell us if it breaks. Supported and gated today: Vite + React, Next.js, Remix and Astro. If the hook does not register a session, please open an issue.';
 /**
@@ -236,7 +257,7 @@ export const UNVERIFIED_FRAMEWORK_NOTE = 'Reticle has no SvelteKit app and no CI
  */
 export function svelteKitHooksFile(port, projectId) {
     const base = connectArg(port, projectId);
-    const fields = base === '' ? '' : `${base.slice(1, -1).trim()}, `;
+    const fields = '' === base ? '' : `${base.slice(1, -1).trim()}, `;
     return `// Dev-only: connect Reticle on the client. SvelteKit renders via app.html, so the Vite-plugin
 // index.html injection doesn't fire — connect from this client hook instead.
 if (import.meta.env.DEV) {
@@ -246,11 +267,19 @@ if (import.meta.env.DEV) {
     // file it lives in, so @reticlehq/vite-plugin inlines it here at build time. Without it the
     // console reads "bridge refused the connection: authentication failed" and no session appears.
     const token = typeof __RETICLE_TOKEN__ !== 'undefined' ? __RETICLE_TOKEN__ : '';
-    reticle.connect({ ${fields}...(token.length > 0 ? { token } : {}) });
+    const root = typeof __RETICLE_ROOT__ !== 'undefined' ? __RETICLE_ROOT__ : '';
+    const sdkVersion = typeof __RETICLE_SDK_VERSION__ !== 'undefined' ? __RETICLE_SDK_VERSION__ : '';
+    reticle.connect({
+      ${fields}...(token.length > 0 ? { token } : {}),
+      ...(root.length > 0 ? { root } : {}),
+      ...(sdkVersion.length > 0 ? { sdkVersion } : {}),
+    });
   });
 }
 
 declare const __RETICLE_TOKEN__: string | undefined;
+declare const __RETICLE_ROOT__: string | undefined;
+declare const __RETICLE_SDK_VERSION__: string | undefined;
 `;
 }
 /**

package/dist/init/vite-config.js

@@ -37,7 +37,7 @@ function insertImport(source) {
 function insertPlugin(source, port) {
     return source.replace(PLUGINS_ARRAY, (match, _g, offset) => {
         const next = source[offset + match.length] ?? '';
-        const separator = next === '' || /\s/.test(next) ? '' : ' ';
+        const separator = '' === next || /\s/.test(next) ? '' : ' ';
         return `${match}${reticlePluginCall(port)},${separator}`;
     });
 }