@reticlehq/server 2.7.0 → 2.8.0

package/dist/init/non-js-project.js

@@ -29,7 +29,13 @@ const ECOSYSTEM_MARKERS = [
     ['pom.xml', 'Java'],
     ['build.gradle', 'Java'],
     ['mix.exs', 'Elixir'],
+    // Not like the others. Every ecosystem above can grow a JS front end that Reticle instruments
+    // perfectly well, so their message ends with a lead. Flutter web paints into a canvas, and there
+    // is no DOM behind it at any path, so the honest answer is a named refusal.
+    ['pubspec.yaml', 'Flutter'],
 ];
+/** The one ecosystem where no directory, front end or flag could ever help. */
+const FLUTTER = 'Flutter';
 /** The ecosystem this directory looks like, or undefined when nothing says. */
 export function detectNonJsEcosystem(exists) {
     for (const [marker, name] of ECOSYSTEM_MARKERS) {
@@ -51,10 +57,28 @@ export function noPackageJsonMessage(exists) {
         return ('No package.json found here, and no app directory beneath it either. Run `reticle init` from ' +
             "your app's directory, or from a repo root that contains it.");
     }
+    if (ecosystem === FLUTTER) {
+        // An agent on a Flutter workspace asked us to "support Flutter, or clearly identify it as
+        // unsupported during init". The second is the truthful one, and saying it by name in one line
+        // is the difference between an agent that stops and an agent that spends an hour looking for
+        // the package.json we told it was missing.
+        return ('This is a Flutter project. Reticle cannot instrument it, and no directory or flag will ' +
+            'change that: Reticle reads the DOM of a running page, and Flutter web paints its entire UI ' +
+            'into a single canvas element with no DOM behind it. Nothing here is missing or misconfigured. ' +
+            'If this repo also contains an ordinary web app with its own package.json, run `reticle init` ' +
+            'inside that directory instead.');
+    }
     return (`This looks like a ${ecosystem} project, and there is no package.json here or in any app ` +
-        'directory beneath it. Reticle instruments a page by having its SDK imported into the app’s own ' +
-        'JavaScript build — so a server-rendered app with no JS build has nowhere to load it from, and ' +
-        'there is no directory you could run this from that would change that. ' +
-        'If this project does have a JS front end (a `frontend/`, `client/` or `assets/` directory with ' +
-        'its own package.json), run `reticle init` there, or point at it with `--app <dir>`.');
+        'directory beneath it. That is not a blocker: Reticle needs its SDK loaded by the page, not ' +
+        'built by npm, and a page with no build step can load it from a URL. ' +
+        // The old message ended at "there is no directory you could run this from that would change
+        // that", which read as a refusal and was acted on as one — agents went looking for a bundler,
+        // or for a standalone build to inject by hand, or gave up and used a different tool. The
+        // capability was there the whole time; only the sentence was missing. Proven end to end on a
+        // page served by `python3 -m http.server` before this line was written.
+        'Add the script-tag snippet below to a template you only serve in development, then reload the ' +
+        'page. ' +
+        'If this project ALSO has a JS front end (a `frontend/`, `client/` or `assets/` directory with ' +
+        'its own package.json), running `reticle init` there instead gives you source mapping and ' +
+        'framework state as well: point at it with `--app <dir>`.');
 }

package/dist/init/plan-framework.js

@@ -23,6 +23,36 @@ export const VITE_PLUGIN_DETAIL = {
     SVELTEKIT: 'add reticle() to plugins (stamps data-reticle-source in .svelte components)',
 };
 const CAPABILITIES_TITLE = 'Capabilities + store';
+/**
+ * The one step `init` genuinely cannot finish, addressed to the AGENT reading this report.
+ *
+ * It used to read "Capabilities are empty until you edit that file" and describe the consequence to
+ * a human — homework, in a report a human mostly does not read, naming no file to open and no thing
+ * to look for. The agent that ran `init` is right there, has the codebase, and can finish this in
+ * the same minute; what it needed was the specific instruction, not the rationale.
+ *
+ * What is left is exactly what could not be PROVEN from source: which atoms/actor/queryClient an
+ * adapter-wrapped store should be built from, and which elements matter enough to name. `init`
+ * emits nothing it cannot prove, because a wrong import here throws on every dev page load — worse
+ * than an empty file.
+ */
+const CAPABILITIES_TODO_TITLE = 'AGENT: finish the capabilities file';
+function capabilitiesTodo(path, stores) {
+    const store = stores.length > 0
+        ? `This app depends on a state library init cannot wire on its own (it needs an argument only ` +
+            `reading the code can supply). Uncomment the suggested line in that file and complete it: ` +
+            `${stores.join('; ')}.`
+        : `No state library was detected. If the app holds state somewhere init cannot see, register ` +
+            `it — see node_modules/@reticlehq/server/docs/usage.md.`;
+    return (`${path} was written but registers nothing, so \`hasCapabilities\` stays false and reticle_state ` +
+        `has nothing to read.\n` +
+        `Do this now, before driving anything:\n` +
+        `  1. ${store}\n` +
+        `  2. Open the app's main flow and add \`testids\` for the elements it touches (or add ` +
+        `data-testid attributes where there are none).\n` +
+        `  3. Prove it: drive one flow and check reticle_state returns your keys. An empty state read ` +
+        `means this file is still not doing anything, whatever else went green.`);
+}
 /**
  * The dev module carrying `registerCapabilities` / `registerStore`.
  *
@@ -37,23 +67,32 @@ function capabilitiesStep(input) {
                 title: CAPABILITIES_TITLE,
                 target: VITE_DEV_MODULE_PATH,
                 status: StepStatus.ALREADY,
-                detail: 'file exists — left alone, it is yours to edit',
+                detail: 'file exists, left alone, it is yours to edit',
             },
         ];
     }
     const testids = input.testids ?? [];
     const stores = input.storeHints ?? [];
+    const wired = input.foundStores ?? [];
     const found = testids.length > 0
         ? `${String(testids.length)} data-testid values`
         : 'no data-testid values yet';
-    const nothingToRegister = 0 === testids.length && 0 === stores.length;
+    // A store we found and wired IS a registration, so the "registers nothing" notice must not fire.
+    const nothingToRegister = 0 === testids.length && 0 === stores.length && 0 === wired.length;
     return [
         {
             title: CAPABILITIES_TITLE,
             target: VITE_DEV_MODULE_PATH,
             status: StepStatus.APPLY,
-            detail: `${found}; ${stores.length > 0 ? `store: uncomment the ${String(stores.length)} suggested line(s)` : 'no state library detected'}`,
-            write: { path: VITE_DEV_MODULE_PATH, content: viteDevModuleFile(testids, stores) },
+            detail: `${found}; ${wired.length > 0
+                ? `registered ${wired.map((s) => `'${s.key}'`).join(', ')} from your source`
+                : stores.length > 0
+                    ? `store: uncomment the ${String(stores.length)} suggested line(s)`
+                    : 'no state library detected'}`,
+            write: {
+                path: VITE_DEV_MODULE_PATH,
+                content: viteDevModuleFile(testids, stores, wired, input.detection.uiLibrary),
+            },
             dependsOnInstall: true,
         },
         // The write is real; what it registers is not. `registerCapabilities({ testids: [], signals: [],
@@ -67,14 +106,10 @@ function capabilitiesStep(input) {
         ...(nothingToRegister
             ? [
                 {
-                    title: 'Capabilities are empty until you edit that file',
+                    title: CAPABILITIES_TODO_TITLE,
                     target: VITE_DEV_MODULE_PATH,
                     status: StepStatus.NOTICE,
-                    detail: 'the module was written but registers nothing — no data-testid values were found and ' +
-                        'no state library was detected, so `hasCapabilities` stays false and reticle_state ' +
-                        'has nothing to read. Add data-testid to the elements your main flow touches, or ' +
-                        'register a store in that file, and the agent gains what the app BELIEVES rather than ' +
-                        'only what it rendered.',
+                    detail: capabilitiesTodo(VITE_DEV_MODULE_PATH, stores),
                 },
             ]
             : []),
@@ -94,7 +129,7 @@ function viteConfigSteps(input, detail) {
                 title: 'Vite plugin',
                 target: 'vite.config',
                 status: StepStatus.MANUAL,
-                detail: viteManual(port),
+                detail: viteManual(port, input.detection.uiLibrary),
             },
         ];
     }
@@ -115,7 +150,7 @@ function viteConfigSteps(input, detail) {
                 title: 'Vite plugin',
                 target: cfg.path,
                 status: StepStatus.MANUAL,
-                detail: `${patch.reason}\n\n${viteManual(port)}`,
+                detail: `${patch.reason}\n\n${viteManual(port, input.detection.uiLibrary)}`,
             },
         ];
     }
@@ -177,7 +212,10 @@ export function nextSteps(input) {
             detail: 'create dev-only connect component',
             write: {
                 path: devPath,
-                content: nextReticleDevFile(input.options.port, input.options.projectId, input.testids ?? [], input.storeHints ?? []),
+                content: nextReticleDevFile(input.options.port, input.options.projectId, input.testids ?? [], input.storeHints ?? [], 
+                // Next's dev module is not a sibling of `src/` — its imports are resolved from wherever
+                // the component actually lands (`app/`, or `src/app/` in a --src-dir app).
+                input.nextFoundStores ?? []),
             },
             dependsOnInstall: true,
         };
@@ -338,7 +376,7 @@ export function svelteKitSteps(input) {
             detail: 'create dev-only client connect (SvelteKit renders via app.html)',
             write: {
                 path: SVELTEKIT_HOOKS_PATH,
-                content: svelteKitHooksFile(input.options.port, input.options.projectId),
+                content: svelteKitHooksFile(input.options.port, input.options.projectId, input.detection.uiLibrary),
             },
             dependsOnInstall: true,
         },
@@ -375,7 +413,7 @@ export function astroSteps(input) {
     // single recipe that does the whole job.
     const manualWithLayout = astroManual(input.options.port, input.options.projectId, layout.path);
     const configPatch = patchAstroConfig(config.source);
-    const layoutPatch = patchAstroLayout(layout.source, input.options.port, input.options.projectId);
+    const layoutPatch = patchAstroLayout(layout.source, input.options.port, input.options.projectId, input.detection.uiLibrary);
     if (configPatch.kind === PatchKind.MANUAL || layoutPatch.kind === PatchKind.MANUAL) {
         return [
             {

package/dist/init/plan.d.ts

@@ -3,7 +3,8 @@
  * contents, produce an ordered list of steps — each marked apply / manual / already / skip. The
  * runner performs the `write` side-effects; this module decides *what* should happen.
  */
-import { Framework, type Detection } from './detect.js';
+import { Framework, UiLibrary, type Detection } from './detect.js';
+import type { FoundStore } from './capabilities.js';
 import { type McpClient } from './mcp-clients.js';
 /**
  * Pin the SDK to the CLI's own version.
@@ -15,8 +16,15 @@ import { type McpClient } from './mcp-clients.js';
  * irrelevant, and a skewed pair impossible to install by accident.
  */
 export declare function pinnedPackages(packages: readonly string[], version: string | undefined): readonly string[];
-/** The dev-dependencies `reticle init` installs for a given framework — kit first, build plugin next. */
-export declare function frameworkPackages(framework: Framework): readonly string[];
+/**
+ * The dev-dependencies `reticle init` installs — kit (or sensor) first, build plugin next.
+ *
+ * `uiLibrary` matters because the framework does not always name the renderer. The rule below was
+ * already written for Nuxt, correctly, and applied only there: a Vue app on plain Vite is
+ * `Framework.VITE` and a SvelteKit app renders Svelte, and both were being handed the React kit
+ * right after `init` had detected the real UI library and said so on screen.
+ */
+export declare function frameworkPackages(framework: Framework, uiLibrary?: UiLibrary): readonly string[];
 /** Exported so the init telemetry can tell an MCP-registration failure from a dependency install. */
 export declare const MCP_TARGET = "global (claude user scope)";
 /** True when this step is what makes the app dial the daemon. */
@@ -77,6 +85,13 @@ export interface Step {
 }
 export interface Plan {
     framework: Framework;
+    /**
+     * The renderer this app actually uses, carried so every consumer agrees on WHICH packages the
+     * plan installed. The retry guard checks node_modules for exactly those names; without this it
+     * looked for `@reticlehq/react` in a Vue app that had correctly been given the sensor, decided the
+     * install had failed, and skipped every wiring step on the retry.
+     */
+    uiLibrary: UiLibrary;
     steps: Step[];
 }
 export interface PlanInput {
@@ -144,6 +159,10 @@ export interface PlanInput {
     testids?: readonly string[] | undefined;
     /** Ready-to-uncomment `registerStore` lines for the state libraries the app actually depends on. */
     storeHints?: readonly string[] | undefined;
+    /** Store instances found in the app's own source — imported and registered outright, not hinted. */
+    foundStores?: readonly FoundStore[] | undefined;
+    /** The same stores, with specifiers resolved from Next's dev-module directory instead of `src/`. */
+    nextFoundStores?: readonly FoundStore[] | undefined;
     /** Whether src/reticle-dev.ts already exists — it is the one generated file users are meant to edit. */
     viteDevModuleExists?: boolean | undefined;
     /** Whether src/hooks.client.ts already exists (SvelteKit idempotency). */
@@ -159,10 +178,19 @@ export interface PlanInput {
     pairingToken?: string;
     /** Whether .reticle.json already exists in the project root (idempotency). */
     reticleConfigExists?: boolean;
+    /**
+     * Its CONTENT, so an existing config can be checked instead of trusted.
+     *
+     * Existence alone said "a file is present" and was reported as "this is configured correctly" —
+     * see reticleConfigStep for the port that survived every re-run because of it.
+     */
+    reticleConfigSource?: string | null | undefined;
     /** Current project-root CLAUDE.md content (for the idempotent agent-rule merge), or null/undefined. */
     claudeMdContent?: string | null | undefined;
-    /** Current project-root AGENTS.md content (cross-agent fallback rule), or null/undefined. */
+    /** Current project-root AGENTS.md content (the cross-agent rule), or null/undefined. */
     agentsMdContent?: string | null | undefined;
+    /** Current project-root RETICLE.md content (the full rules), or null when absent. */
+    reticleMdContent?: string | null | undefined;
     /**
      * Current .cursor/rules/reticle.mdc content, or null when absent.
      *
@@ -175,6 +203,14 @@ export interface PlanInput {
     claudeCommandContent?: string | null | undefined;
     /** Current .cursor/commands/reticle.md content, or null when absent. */
     cursorCommandContent?: string | null | undefined;
+    /**
+     * Absolute directory the AGENT runs in, when that is not the app's directory.
+     *
+     * The rule and command files are read by the agent, not by the app, so a monorepo whose app is a
+     * directory down must still get its `/reticle` where the human's session actually stands. Absent
+     * (the single-package case) leaves every path project-relative exactly as before.
+     */
+    agentFileRoot?: string | undefined;
     options: {
         port: number | undefined;
         mcp: boolean;

package/dist/init/plan.js

@@ -8,9 +8,11 @@ import { claudeAddCommand, mcpManual } from './mcp.js';
 import { mergeCursorConfig, CursorMergeStatus, cursorServerEntry } from './cursor.js';
 import { mergeClientConfig, ClientMergeStatus, clientSnippet, clientSpec, } from './mcp-clients.js';
 import { CLAUDE_COMMAND_PATH, CURSOR_COMMAND_PATH, SLASH_COMMAND_BODY, SLASH_COMMAND_SIGNATURE, } from './slash-command.js';
-import { mergeMarkedInstruction, cursorRuleFile, AgentRuleStatus, CLAUDE_MD_PATH, AGENTS_MD_PATH, CURSOR_RULE_PATH, } from './agent-rules.js';
+import { mergeMarkedInstruction, reticleMdFile, cursorRuleFile, AgentRuleStatus, CLAUDE_MD_PATH, AGENTS_MD_PATH, RETICLE_MD_PATH, CURSOR_RULE_PATH, } from './agent-rules.js';
 import { viteSteps, nextSteps, craSteps, svelteKitSteps, nuxtSteps, astroSteps, VITE_PLUGIN_DETAIL, } from './plan-framework.js';
+import { join } from 'node:path';
 import { htmlManual, reticleConfigContent, unverifiedUiLibraryNote } from './snippets.js';
+import { devServerPortWarning, isLikelyDevServerPort } from '../cli/cli-port.js';
 // An app dev installs exactly the audience-scoped browser-side dependencies — never the retired
 // `@reticlehq/core` umbrella (which dragged the Node MCP server + ws into every app). The kit is the
 // framework adapter (it re-exports the browser sensor), paired with that framework's dev-only build
@@ -34,15 +36,40 @@ export function pinnedPackages(packages, version) {
         return packages;
     return packages.map((p) => `${p}@${version}`);
 }
-/** The dev-dependencies `reticle init` installs for a given framework — kit first, build plugin next. */
-export function frameworkPackages(framework) {
+/**
+ * Does this codebase want the React kit, or the framework-neutral sensor?
+ *
+ * The kit is what adds component identity — component names and stacks — and it is worth having
+ * wherever React or Preact is rendering (the adapter reaches Preact through `preact/compat`).
+ * Everywhere else it is a package named `@reticlehq/react`, carrying `react` in its peer
+ * dependencies, being installed into a codebase that has no React in it.
+ *
+ * UNKNOWN keeps the kit deliberately. Absence of evidence is not evidence of Vue, and guessing
+ * "sensor" on no information silently drops component identity from apps that should have it.
+ */
+function wantsReactKit(ui) {
+    return ui !== UiLibrary.VUE && ui !== UiLibrary.SVELTE;
+}
+/**
+ * The dev-dependencies `reticle init` installs — kit (or sensor) first, build plugin next.
+ *
+ * `uiLibrary` matters because the framework does not always name the renderer. The rule below was
+ * already written for Nuxt, correctly, and applied only there: a Vue app on plain Vite is
+ * `Framework.VITE` and a SvelteKit app renders Svelte, and both were being handed the React kit
+ * right after `init` had detected the real UI library and said so on screen.
+ */
+export function frameworkPackages(framework, uiLibrary = UiLibrary.UNKNOWN) {
+    const kit = wantsReactKit(uiLibrary) ? RETICLE_REACT_KIT : RETICLE_BROWSER_SDK;
     switch (framework) {
         case Framework.NEXT:
+            // Next is React by construction, so the detection cannot disagree in a way worth honouring.
             return [RETICLE_REACT_KIT, RETICLE_NEXT_PLUGIN];
         case Framework.VITE:
         case Framework.SVELTEKIT:
             // SvelteKit builds on Vite; until a dedicated Svelte kit exists it uses the Vite build plugin.
-            return [RETICLE_REACT_KIT, RETICLE_VITE_PLUGIN];
+            // The build plugin stamps `data-reticle-source` regardless of UI library, so a Vue or Svelte
+            // app still gets source pointers — it is only component identity that needs the React kit.
+            return [kit, RETICLE_VITE_PLUGIN];
         case Framework.NUXT:
             // The framework-neutral sensor, NOT the React kit. Nuxt renders Vue, and installing a package
             // named @reticlehq/react — with `react` in its peer dependencies — into a Vue codebase is the
@@ -51,14 +78,14 @@ export function frameworkPackages(framework) {
         case Framework.ASTRO:
             // Astro owns its own Vite instance and renders its own HTML, so there is no config for the
             // plugin to attach to — the kit alone, connected from a page <script> (see astroManual).
-            return [RETICLE_REACT_KIT];
+            return [kit];
         case Framework.CRA:
             // react-scripts owns its webpack config and cannot be extended without ejecting, so there is
             // no build plugin — the kit alone, imported from src/index.tsx (see cra.ts).
             return [RETICLE_REACT_KIT];
         case Framework.HTML:
             // No bundler plugin to install — just the kit; connect is wired by hand (see htmlManual).
-            return [RETICLE_REACT_KIT];
+            return [kit];
     }
 }
 /** Exported so the init telemetry can tell an MCP-registration failure from a dependency install. */
@@ -101,6 +128,19 @@ export const StepStatus = {
      */
     NOTICE: 'notice',
 };
+/**
+ * Where the agent-facing files go, which is not always where the app is.
+ *
+ * Reported from the field (#318): a repo with its app at `src/admin` got `.claude/commands/reticle.md`
+ * written into the app directory, while the human's agent session runs at the repo root — so
+ * `/reticle` did not exist for them at all until they copied it up by hand. The rule and command
+ * files are read by the AGENT, so they belong where the agent stands; the app files stay with the
+ * app. The two are the same directory in a single-package repo, which is why this went unnoticed.
+ */
+function agentFile(input, relPath) {
+    const root = input.agentFileRoot;
+    return root === undefined || 0 === root.length ? relPath : join(root, relPath);
+}
 const CLAUDE_MCP_TITLE = 'MCP server (Claude, global)';
 const CURSOR_MCP_TITLE = 'MCP server (Cursor, global)';
 function claudeMcpStep(input) {
@@ -267,32 +307,35 @@ function commandStepFor(path, present, content) {
         };
 }
 function claudeCommandStep(input) {
-    return commandStepFor(CLAUDE_COMMAND_PATH, input.claudeCli, input.claudeCommandContent);
+    return commandStepFor(agentFile(input, CLAUDE_COMMAND_PATH), input.claudeCli, input.claudeCommandContent);
 }
 function cursorCommandStep(input) {
     const present = true === input.cursorProjectPresent || (input.cursorPresent && !input.claudeCli);
-    return commandStepFor(CURSOR_COMMAND_PATH, present, input.cursorCommandContent);
+    return commandStepFor(agentFile(input, CURSOR_COMMAND_PATH), present, input.cursorCommandContent);
 }
 const AGENT_RULE_TITLE = 'Agent verification rule';
 const AGENT_RULE_DETAIL = 'teach the agent to verify features with Reticle after building them';
+const RETICLE_MD_TITLE = 'Full agent rules';
+const RETICLE_MD_DETAIL = 'the reference the always-loaded rule points at (when NOT to verify, recovery, feedback)';
 function claudeRuleStep(input) {
     if (!input.claudeCli)
         return null;
+    const path = agentFile(input, CLAUDE_MD_PATH);
     const r = mergeMarkedInstruction(input.claudeMdContent);
     if (r.status === AgentRuleStatus.ALREADY) {
         return {
             title: AGENT_RULE_TITLE,
-            target: CLAUDE_MD_PATH,
+            target: path,
             status: StepStatus.ALREADY,
             detail: 'Reticle rule already in CLAUDE.md',
         };
     }
     return {
         title: AGENT_RULE_TITLE,
-        target: CLAUDE_MD_PATH,
+        target: path,
         status: StepStatus.APPLY,
         detail: AGENT_RULE_DETAIL,
-        write: { path: CLAUDE_MD_PATH, content: r.content },
+        write: { path, content: r.content },
     };
 }
 /**
@@ -308,20 +351,21 @@ function cursorRuleStep(input) {
         return null;
     // The whole file is Reticle's — init created it — so a stale one is REWRITTEN rather than merged.
     // Comparing content is what makes the rule updatable; comparing existence made it permanent.
+    const path = agentFile(input, CURSOR_RULE_PATH);
     if (input.cursorRuleContent === cursorRuleFile()) {
         return {
             title: AGENT_RULE_TITLE,
-            target: CURSOR_RULE_PATH,
+            target: path,
             status: StepStatus.ALREADY,
             detail: 'Reticle rule already in .cursor/rules',
         };
     }
     return {
         title: AGENT_RULE_TITLE,
-        target: CURSOR_RULE_PATH,
+        target: path,
         status: StepStatus.APPLY,
         detail: AGENT_RULE_DETAIL,
-        write: { path: CURSOR_RULE_PATH, content: cursorRuleFile() },
+        write: { path, content: cursorRuleFile() },
     };
 }
 /**
@@ -365,33 +409,70 @@ function slashCommandSteps(input) {
     return stepsForAgents(input, (a) => a.commandStep);
 }
 /**
- * The behavioral rule that makes the agent actually USE Reticle. Written into the detected agent's
- * instruction file (Claude / Cursor, or both), falling back to the cross-agent AGENTS.md when neither
- * is detected. Rides with the MCP wiring — `--no-mcp` opts out of registering the tools AND the rule.
+ * `AGENTS.md`, always. It is the file every agent that is not Claude or Cursor reads.
+ *
+ * This used to be a FALLBACK, written only when no agent was detected. So a repo set up on a machine
+ * with Claude Code got `CLAUDE.md` and nothing else, and the next person to open it with Codex,
+ * Copilot, Amp, Gemini or any other agent found a fully instrumented app whose rules were addressed
+ * to somebody else's tool. The detection tells you which agent is running the install; it says
+ * nothing about which agents will open the repository afterwards.
+ */
+function agentsMdStep(input) {
+    const r = mergeMarkedInstruction(input.agentsMdContent);
+    const path = agentFile(input, AGENTS_MD_PATH);
+    if (r.status === AgentRuleStatus.ALREADY) {
+        return {
+            title: AGENT_RULE_TITLE,
+            target: path,
+            status: StepStatus.ALREADY,
+            detail: 'Reticle rule already in AGENTS.md',
+        };
+    }
+    return {
+        title: AGENT_RULE_TITLE,
+        target: path,
+        status: StepStatus.APPLY,
+        detail: AGENT_RULE_DETAIL,
+        write: { path, content: r.content },
+    };
+}
+/**
+ * `RETICLE.md`, the reference the always-loaded blocks point at.
+ *
+ * Written whole rather than merged, because `init` owns the entire file: there is no user content to
+ * preserve, and the marker dance exists only for files somebody else already writes in.
+ */
+function reticleMdStep(input) {
+    const path = agentFile(input, RETICLE_MD_PATH);
+    const content = reticleMdFile();
+    if (input.reticleMdContent === content) {
+        return {
+            title: RETICLE_MD_TITLE,
+            target: path,
+            status: StepStatus.ALREADY,
+            detail: 'full rules already current',
+        };
+    }
+    return {
+        title: RETICLE_MD_TITLE,
+        target: path,
+        status: StepStatus.APPLY,
+        detail: RETICLE_MD_DETAIL,
+        write: { path, content },
+    };
+}
+/**
+ * The behavioral rules that make the agent actually USE Reticle, and know when not to.
+ *
+ * Every detected agent's own file, plus `AGENTS.md` for the ones that will open this repo later, plus
+ * `RETICLE.md` holding the reference half. Rides with the MCP wiring: `--no-mcp` opts out of
+ * registering the tools AND of every rule file, because rules for tools the agent cannot reach are
+ * noise.
  */
 function agentRuleSteps(input) {
     if (!input.options.mcp)
         return [];
-    const detected = stepsForAgents(input, (a) => a.ruleStep);
-    if (detected.length > 0)
-        return detected;
-    const r = mergeMarkedInstruction(input.agentsMdContent);
-    return [
-        r.status === AgentRuleStatus.ALREADY
-            ? {
-                title: AGENT_RULE_TITLE,
-                target: AGENTS_MD_PATH,
-                status: StepStatus.ALREADY,
-                detail: 'Reticle rule already in AGENTS.md',
-            }
-            : {
-                title: AGENT_RULE_TITLE,
-                target: AGENTS_MD_PATH,
-                status: StepStatus.APPLY,
-                detail: AGENT_RULE_DETAIL,
-                write: { path: AGENTS_MD_PATH, content: r.content },
-            },
-    ];
+    return [...stepsForAgents(input, (a) => a.ruleStep), agentsMdStep(input), reticleMdStep(input)];
 }
 /**
  * What to say when the install command fails.
@@ -439,7 +520,7 @@ function installFailureHint(pm) {
 }
 function installStep(input) {
     const pm = input.detection.packageManager;
-    const packages = pinnedPackages(frameworkPackages(input.detection.framework), input.options.sdkVersion);
+    const packages = pinnedPackages(frameworkPackages(input.detection.framework, input.detection.uiLibrary), input.options.sdkVersion);
     const command = installCommand(pm, packages);
     if (!input.options.install) {
         return {
@@ -463,13 +544,55 @@ function installStep(input) {
         // Unpinned. pnpm resolves the newest MATURE version there, which is how a project with a
         // release-age hold gets a working install instead of no install.
         retry: {
-            ...installCommandParts(pm, frameworkPackages(input.detection.framework)),
+            ...installCommandParts(pm, frameworkPackages(input.detection.framework, input.detection.uiLibrary)),
             note: unpinnedRetryNote(input.options.sdkVersion, pm),
         },
     };
 }
+/**
+ * What is wrong with the config that is already there, if anything.
+ *
+ * Reported from the field (#317): a project carried `"port": 3000` — its own dev-server port, which
+ * is the confusion SKILL.md names as the top setup failure — and `init` printed `.reticle.json
+ * already exists` on every re-run without reading a single field of it, so the file could never be
+ * repaired by the command that wrote it. It stayed invisible because a daemon on `127.0.0.1:3000`
+ * and Vite on `[::1]:3000` split the port by address family and neither reported a conflict.
+ *
+ * Narrower than the issue asked for on purpose: `init`'s IO surface is synchronous, so this cannot
+ * probe what is LISTENING right now. `isLikelyDevServerPort` covers the framework defaults, which is
+ * where the mistake is actually made.
+ */
+function existingConfigProblem(source) {
+    if (null === source || source === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch {
+        return (`${RETICLE_CONFIG_FILE} is present but is not valid JSON, so nothing reads it — neither the ` +
+            'daemon nor the SDK. Delete it and re-run `reticle init`.');
+    }
+    if ('object' !== typeof parsed || null === parsed)
+        return undefined;
+    const port = parsed['port'];
+    if ('number' !== typeof port || !isLikelyDevServerPort(port))
+        return undefined;
+    return `${devServerPortWarning(port)} Fix it by removing the "port" field from ${RETICLE_CONFIG_FILE}.`;
+}
 function reticleConfigStep(input) {
     if (true === input.reticleConfigExists) {
+        const problem = existingConfigProblem(input.reticleConfigSource);
+        if (problem !== undefined) {
+            // `ℹ`, not `·`: the step is done and something about the result still stops things working,
+            // which is the one mark that says "there is something here to read".
+            return {
+                title: 'Reticle config',
+                target: RETICLE_CONFIG_FILE,
+                status: StepStatus.NOTICE,
+                detail: problem,
+            };
+        }
         return {
             title: 'Reticle config',
             target: RETICLE_CONFIG_FILE,
@@ -550,5 +673,5 @@ export function buildPlan(input) {
             detail: htmlManual(input.options.port, input.options.projectId, input.pairingToken),
         });
     }
-    return { framework: input.detection.framework, steps };
+    return { framework: input.detection.framework, uiLibrary: input.detection.uiLibrary, steps };
 }

package/dist/init/run.d.ts

@@ -3,6 +3,7 @@
  * plan (pure), optionally write the apply-steps, and print a human-readable report. All filesystem
  * access goes through `InitIo` so the orchestration is unit-testable with an in-memory IO.
  */
+import type { InitOutcome } from '@reticlehq/core';
 /**
  * Resolve the lockfiles set used to pick the package manager. A lockfile in the project root wins;
  * otherwise we walk UP the directory tree (monorepos keep the lockfile at the workspace root, not in
@@ -29,6 +30,23 @@ export interface InitOptions {
     app?: string;
     /** Set on the recursive call after a workspace redirect, so the search happens at most once. */
     redirected?: boolean;
+    /**
+     * Where the human ran the command, carried across a workspace redirect.
+     *
+     * The agent rule and `/reticle` command files are read by the AGENT, whose session runs where the
+     * human started it — the repo root. Writing them beside the app instead is how a repo with its app
+     * at `src/admin` ended up with no `/reticle` at all (#318).
+     */
+    agentRoot?: string;
+    /**
+     * Hand the telemetry outcome back rather than emitting it here.
+     *
+     * `init` now stays to watch for an app to connect, and whether it saw one belongs on the SAME
+     * `init_completed` event — the funnel it exists to measure would be double-counted by a second
+     * emit and unjoinable as a second event kind. Only the CLI sets this; every other caller keeps
+     * today's fire-and-forget behaviour, so no path loses its event by forgetting to report.
+     */
+    deferOutcome?: boolean;
 }
 export interface InitIo {
     /** Returns file content or null if it does not exist. Path is project-relative or absolute. */
@@ -52,10 +70,15 @@ export interface InitIo {
     probe(command: string, args: readonly string[]): boolean;
     print(line: string): void;
 }
-interface InitResult {
+export interface InitResult {
     ok: boolean;
     applied: number;
     manual: number;
+    /**
+     * The event body this run would report, handed to the caller instead of emitted, when
+     * `deferOutcome` is set. Absent on a dry run and on the exits that report for themselves.
+     */
+    outcome?: InitOutcome;
 }
 /**
  * App directories under a workspace root.
@@ -77,4 +100,3 @@ export declare function findWorkspaceApps(io: Pick<InitIo, 'exists' | 'readFile'
  */
 export declare const FEEDBACK_HINT: string;
 export declare function runInit(options: InitOptions, io: InitIo): InitResult;
-export {};