@reticlehq/server 2.3.0 → 2.5.0

package/dist/init/run.js

@@ -4,11 +4,51 @@
  * 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';
+import { scanTestids, storeHints } from './capabilities.js';
 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 '../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 = [
@@ -43,25 +83,108 @@ export function resolveLockfiles(rootFiles, cwd, io) {
     return set;
 }
 const PACKAGE_JSON = 'package.json';
-const NEXT_RETICLE_DEV = 'app/reticle-dev.tsx';
+/**
+ * Root-layout candidates, App Router only. `--src-dir` apps keep theirs under `src/app`, and the
+ * ReticleDev component has to land NEXT TO the layout or the relative import it generates is dead.
+ */
+const NEXT_LAYOUT_CANDIDATES = [
+    'app/layout.tsx',
+    'app/layout.jsx',
+    'app/layout.js',
+    'src/app/layout.tsx',
+    'src/app/layout.jsx',
+    'src/app/layout.js',
+];
+/**
+ * Pages Router mount points, checked only when there is no App Router layout. A Pages app has no
+ * `app/` directory at all, so writing the component there produced a file nothing imported.
+ */
+const NEXT_PAGES_APP_CANDIDATES = [
+    'pages/_app.tsx',
+    'pages/_app.jsx',
+    'pages/_app.js',
+    'src/pages/_app.tsx',
+    'src/pages/_app.jsx',
+    'src/pages/_app.js',
+];
 const SVELTEKIT_HOOKS = 'src/hooks.client.ts';
+/** Where an app's components live. Bounded on purpose — this is a hint, not an index of the repo. */
+const SOURCE_DIRS = ['src', 'src/components', 'src/pages', 'app', 'components'];
+const SOURCE_FILE = /\.(tsx|jsx|ts|js|svelte|vue|astro)$/;
+/** Files read for the testid scan. A capabilities block is a hint; reading a whole repo for it is not. */
+const MAX_SCANNED_FILES = 200;
+/** Read a bounded set of the app's source files, for the `data-testid` scan. */
+function readSourceFiles(io) {
+    const out = [];
+    for (const dir of SOURCE_DIRS) {
+        for (const name of io.listFiles(dir)) {
+            if (!SOURCE_FILE.test(name))
+                continue;
+            const content = io.readFile(`${dir}/${name}`);
+            if (content !== null)
+                out.push(content);
+            if (out.length >= MAX_SCANNED_FILES)
+                return out;
+        }
+    }
+    return out;
+}
+/** Direct dependency names, for naming the state libraries an app actually has. */
+function dependencyNames(pkg) {
+    const p = (pkg ?? {});
+    return new Set([
+        ...Object.keys(p['dependencies'] ?? {}),
+        ...Object.keys(p['devDependencies'] ?? {}),
+    ]);
+}
 const VITE_CONFIG_CANDIDATES = [
     'vite.config.ts',
     'vite.config.js',
     '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',
     'next.config.ts',
     'next.config.cjs',
 ];
+/**
+ * `⚠` means WORK LEFT TO DO and nothing else — it is what an agent (and the release gate) counts to
+ * 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]: '⚠',
     [StepStatus.ALREADY]: '·',
     [StepStatus.SKIP]: '–',
+    [StepStatus.NOTICE]: 'ℹ',
 };
 function firstPresent(files, candidates) {
     for (const c of candidates)
@@ -75,14 +198,16 @@ 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),
+        // An already-installed tree names its own manager, which matters when no lockfile is committed.
+        nodeModulesMarkers: new Set(io.listFiles('node_modules')),
     };
     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.
@@ -90,55 +215,195 @@ 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)) ??
+        null;
+    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);
     return {
         detection,
         claudeCli,
         mcpExists,
         cursorPresent,
+        cursorProjectPresent: io.exists(CURSOR_DIR_RELPATH),
         cursorConfig,
         cursorConfigPath,
         viteConfig,
-        nextConfigFile: firstPresent(rootFiles, NEXT_CONFIG_CANDIDATES),
-        nextReticleDevExists: io.exists(NEXT_RETICLE_DEV),
+        astroConfig: astroPath !== null && astroSource !== null ? { path: astroPath, source: astroSource } : null,
+        astroLayout: layoutRelPath !== null && astroLayoutSource !== null
+            ? { path: layoutRelPath, source: astroLayoutSource }
+            : null,
+        nextConfigFile,
+        nextConfigSource: null === nextConfigFile ? null : io.readFile(nextConfigFile),
+        nextLayout: layoutPath !== null && layoutSource !== null
+            ? { path: layoutPath, source: layoutSource }
+            : null,
+        // Capabilities: scanned, never asked for. Bounded — a hint for the agent, not a repo index.
+        testids: scanTestids(readSourceFiles(io)),
+        storeHints: storeHints(dependencyNames(pkg)),
+        viteDevModuleExists: io.exists(VITE_DEV_MODULE_PATH),
+        nextReticleDevPath: devLocation.path,
+        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'),
-        options: { port: options.port, mcp: options.mcp, install: options.install, projectId },
+        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,
+            install: options.install,
+            projectId,
+            // The SDK must match the CLI asking for it — see pinnedPackages.
+            sdkVersion: SERVER_VERSION,
+        },
     };
 }
+/** Where workspace tooling conventionally puts 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 (null === pkgRaw)
+        return false;
+    const configs = [...VITE_CONFIG_CANDIDATES, ...NEXT_CONFIG_CANDIDATES];
+    if (configs.some((c) => io.exists(`${dir}/${c}`)))
+        return true;
+    // `next.config` is optional in Next, so the dependency list is the other half of the signal.
+    return APP_DEPS.some((d) => pkgRaw.includes(`"${d}"`));
+}
+/**
+ * App directories under a workspace root.
+ *
+ * Running `reticle init` at the repo root is what people actually do, and in a monorepo the app is a
+ * directory down — so init detected "no framework", printed a wall of manual HTML instructions, and
+ * would have installed the SDK into the ROOT package.json. It already walks UP for the lockfile, so
+ * it knows it is in a workspace; this is the matching walk DOWN.
+ */
+export function findWorkspaceApps(io) {
+    const found = [];
+    // 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 [...new Set(found)];
+}
 function restartHint(framework) {
     if (framework === Framework.NEXT)
         return 'Restart `next dev`, then ask your agent: "List Reticle sessions".';
     if (framework === Framework.VITE)
         return 'Restart `vite`, then ask your agent: "List Reticle sessions".';
+    if (framework === Framework.ASTRO)
+        return 'Restart `astro dev`, then ask your agent: "List Reticle sessions".';
     if (framework === Framework.SVELTEKIT)
         return 'Restart your dev server (`npm run dev`), then ask your agent: "List Reticle sessions".';
     return 'Reload your app on localhost, then ask your agent: "List Reticle sessions".';
 }
-function report(plan, dryRun, failed, io) {
+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, 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 downgraded = failed.has(s.target);
+        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 = downgraded && s.exec !== undefined
-            ? `step failed — run manually: ${s.exec.fallback}`
-            : s.detail;
+        const detail = skipped.has(s.target)
+            ? SKIPPED_DETAIL
+            : downgraded && s.exec !== undefined
+                ? `step failed — run manually: ${s.exec.fallback}`
+                : s.detail;
         io.print(`  [${STATUS_SYMBOL[status]}] ${s.title} → ${s.target}`);
         if (status === StepStatus.APPLY)
             applied++;
-        if (status === StepStatus.MANUAL) {
-            manual++;
+        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) {
+                manual++;
+                if (isConnectStep(s.title))
+                    connectPending = true;
+            }
             for (const line of detail.split('\n'))
                 io.print(`      ${line}`);
         }
@@ -147,21 +412,68 @@ function report(plan, dryRun, failed, 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. */
+/**
+ * Perform the apply-step side effects; return the targets whose side effect failed.
+ *
+ * Steps run in plan order, which puts the dependency install BEFORE everything that imports what it
+ * installs. If it fails, the wiring is skipped rather than applied: patching `next.config.ts` to
+ * import a `@reticlehq/next` that was never installed takes the dev server down with
+ * MODULE_NOT_FOUND, so the app stops booting *because* Reticle was installed. A skipped step is a
+ * message; a half-wired app is a broken project.
+ */
 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 (s.write !== undefined)
-            io.writeFile(s.write.path, s.write.content);
-        if (s.exec !== undefined && !io.exec(s.exec.command, s.exec.args))
+        if (installFailed && true === s.dependsOnInstall) {
+            skipped.add(s.target);
+            continue;
+        }
+        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;
+    return { failed, skipped, degraded };
 }
 /**
  * Which STEP failed, from the step targets — not from an error string, which would carry paths.
@@ -178,25 +490,78 @@ function classifyInitFailure(failed) {
         return InitFailure.MCP_REGISTRATION;
     return InitFailure.OTHER;
 }
+const AMBIGUOUS_HEADER = 'Several apps found in this workspace. Re-run `reticle init` inside the one you want:';
+/**
+ * When the current directory is a workspace root with no app of its own, wire the app instead of the
+ * root. One candidate is wired silently (there is nothing to ask about); several are listed, because
+ * guessing which app someone meant is worse than one line of output.
+ * Returns null when there is nothing to redirect to — the caller then proceeds here as before.
+ */
+function redirectToWorkspaceApp(options, io, pkgRaw) {
+    if (true === options.redirected)
+        return null;
+    const pkg = JSON.parse(pkgRaw);
+    const rootFiles = new Set(io.rootFiles());
+    const here = detect({
+        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);
+    // 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 (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.`);
+    io.print('');
+    return runInit({ ...options, cwd: join(options.cwd, target), redirected: true }, io.scoped(target));
+}
 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.
         reportInitOutcome({ ok: false, reason: InitFailure.NO_PACKAGE_JSON });
         return { ok: false, applied: 0, manual: 0 };
     }
-    const plan = buildPlan(gatherPlanInput(options, io, pkgRaw));
-    const failed = options.dryRun ? new Set() : applyEffects(plan, io);
-    const result = report(plan, options.dryRun, failed, io);
+    const redirected = redirectToWorkspaceApp(options, io, pkgRaw);
+    if (redirected !== null)
+        return redirected;
+    // 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(), 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

@@ -0,0 +1,27 @@
+/**
+ * The `/reticle` slash command — the entry point the docs have been promising and nothing created.
+ *
+ * SKILL.md tells the user "Type `/reticle` anytime to verify the app" in three places, and `init`
+ * never wrote the file that makes it exist. So the one obvious way in was a command that silently did
+ * nothing in every tool. Claude Code and Cursor both read custom commands from a markdown file per
+ * command; the body is the prompt the agent receives.
+ *
+ * Deliberately SCOPED to one flow. A user installing Reticle has an existing app with many flows, and
+ * an agent told to "verify the app" will try to instrument all of them — slow, noisy, and nothing to
+ * see for minutes. One flow, driven where the human can watch it, is the whole difference between a
+ * two-minute first impression and an afternoon.
+ */
+/** Claude Code reads project commands from `.claude/commands/<name>.md`. */
+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

@@ -0,0 +1,61 @@
+/**
+ * The `/reticle` slash command — the entry point the docs have been promising and nothing created.
+ *
+ * SKILL.md tells the user "Type `/reticle` anytime to verify the app" in three places, and `init`
+ * never wrote the file that makes it exist. So the one obvious way in was a command that silently did
+ * nothing in every tool. Claude Code and Cursor both read custom commands from a markdown file per
+ * command; the body is the prompt the agent receives.
+ *
+ * Deliberately SCOPED to one flow. A user installing Reticle has an existing app with many flows, and
+ * an agent told to "verify the app" will try to instrument all of them — slow, noisy, and nothing to
+ * see for minutes. One flow, driven where the human can watch it, is the whole difference between a
+ * two-minute first impression and an afternoon.
+ */
+/** Claude Code reads project commands from `.claude/commands/<name>.md`. */
+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 = `---
+${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.
+
+## Pick ONE flow
+
+Not the whole app. Pick the single most important flow you can complete in a handful of steps — the
+one a user would do first (sign in, search, add to cart, submit the form). If the user named a flow or
+just changed some code, use that one instead.
+
+State which flow you picked in one line before you start.
+
+## Drive it where the human can see
+
+1. \`reticle_sessions\` — find the connected tab. None? Tell the user to run their dev server and open
+   the app, then stop. Reticle never starts a dev server.
+2. \`reticle_snapshot\` — read the accessibility tree and locate the elements the flow needs. Elements
+   are addressable by role and name; you do **not** need \`data-testid\` to drive them.
+3. Walk the flow with \`reticle_act_and_wait\`, one step at a time. Narrate each step first — the human
+   is watching the page, and the HUD shows what you say.
+4. After each step, check the effect with \`reticle_assert\` — not just that the click dispatched, but
+   that the thing it was supposed to do actually happened.
+5. Finish with \`reticle_console\` and \`reticle_network\` to catch errors the DOM does not show.
+
+## Report
+
+- What you drove, step by step, and what each step actually produced.
+- Anything broken, with the \`file:line\` Reticle gave you.
+- If a step could not be verified, say so plainly. "Unknown" is a real answer; a green verdict you
+  cannot back is not.
+
+Do not weaken or skip an assertion to make the run pass — that is a finding, not a fix.
+`;