@reticlehq/server 2.9.0 → 2.11.0

package/dist/index.js

@@ -1,4 +1,9 @@
 import { join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { PROJECT_REGISTRY_FILE, emptyProjectRegistry, parseProjectRegistry } from '@reticlehq/core';
+import { discoverProjectConfigs } from './cli/config-discovery.js';
+import { projectCandidatesFrom, resolveArtifactRoot, } from './project/artifact-root.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { AGENT_STOPPED_NOTICE, RETICLE_DEFAULT_PORT, ReticleCommand, ReticleDir, ReticleEnv, LOOPBACK_HOST, ReplayStatus, EventType, } from '@reticlehq/core';
 import { originOf } from './session/session-manager.js';
@@ -72,6 +77,22 @@ export { ProjectStore } from './project/project-store.js';
 export { VisualStore } from './visual/visual-store.js';
 export { diffPng } from './visual/visual-diff.js';
 export { crawl } from './crawl/crawl.js';
+/**
+ * The contradiction pass, and the seam a consumer adds its own rules through.
+ *
+ * Exported because a service embedding this engine grades a recording the same way the tools do, and
+ * without these it would have to re-implement the fold — a second implementation of the one thing
+ * this product is judged on, and the one nobody dogfoods is the one that rots.
+ */
+export { findContradictions } from './events/contradictions.js';
+/**
+ * The MCP server factory, so a consumer can serve the tool surface it composed.
+ *
+ * Without this the composition seam is unreachable from outside the package: a consumer can build the
+ * list and has nothing to hand it to.
+ */
+export { createMcpServer } from './mcp/mcp.js';
+export { registerContradictionFold, registeredContradictionFolds, } from './events/contradiction-folds.js';
 export { MCP_SSE_PATH, MCP_MESSAGE_PATH } from '@reticlehq/core';
 export { BrowserPool, DEFAULT_LEASE_TTL_MS } from './pool/browser-pool.js';
 export { playwrightLauncher, resolveMaxContexts } from './pool/playwright-launcher.js';
@@ -235,6 +256,41 @@ async function resolveRealInput(options, onNavigateError, onNetworkDetail) {
     return {};
 }
 /** Start the Reticle bridge (browser WS endpoint) and, by default, the MCP stdio server. */
+/**
+ * Resolve a session's artifact root, from everything this machine knows about where projects live.
+ *
+ * Built once per daemon and closed over by every tool call. The two sources are read lazily and
+ * cheaply on each call rather than snapshotted at startup: `init` can run in another terminal while
+ * this daemon is up, and a resolution that used a startup snapshot would keep answering with a map
+ * from before the project the agent is now driving existed.
+ */
+function artifactRootResolver(daemonRoot) {
+    return (projectId) => {
+        let registry = emptyProjectRegistry();
+        try {
+            const path = join(homedir(), ReticleDir.ROOT, PROJECT_REGISTRY_FILE);
+            registry = existsSync(path)
+                ? parseProjectRegistry(JSON.parse(readFileSync(path, 'utf8')))
+                : registry;
+        }
+        catch {
+            // A cache that cannot be read is an empty cache, never an error: the daemon still resolves
+            // through discovery, and falls back to its own root exactly as it did before this existed.
+        }
+        let discovery = { found: [], searched: [] };
+        try {
+            discovery = discoverProjectConfigs(process.cwd());
+        }
+        catch {
+            // Same reasoning: a diagnostic search that throws must not take a tool call with it.
+        }
+        return resolveArtifactRoot({
+            projectId,
+            candidates: projectCandidatesFrom(discovery, registry),
+            daemonRoot,
+        });
+    };
+}
 export async function start(options = {}) {
     const port = options.port ?? RETICLE_DEFAULT_PORT;
     // Open the user's impact record before anything can connect. Not inside the MCP branch: a daemon
@@ -286,6 +342,7 @@ export async function start(options = {}) {
             project,
             fs,
             reticleRoot,
+            artifactRootFor: artifactRootResolver(reticleRoot),
             now,
             bridgePort: port,
             browserProbe: probeChromium,

package/dist/init/mcp.d.ts

@@ -11,7 +11,7 @@
  * project's `.reticle.json` in its CWD (see cli-port.ts). The port belongs to the project, not the
  * global agent config.
  */
-export declare const MCP_SERVER_NAME = "reticle";
+export { MCP_SERVER_NAME } from '@reticlehq/core';
 /**
  * The registered command is STILL bare `npx` on every platform, deliberately.
  *
@@ -76,4 +76,3 @@ export declare function claudeAvailableProbe(): {
 };
 /** Printed when the `claude` CLI isn't available — register Reticle globally once, by hand. */
 export declare function mcpManual(): string;
-export {};

package/dist/init/mcp.js

@@ -12,7 +12,10 @@
  * global agent config.
  */
 import { RETICLE_NPM_PACKAGE } from '../version/server-version.js';
-export const MCP_SERVER_NAME = 'reticle';
+// The name is a wire identity and lives in the contract; re-exported here so the registration writers
+// below (and their tests) keep reading it from the module that USES it.
+export { MCP_SERVER_NAME } from '@reticlehq/core';
+import { MCP_SERVER_NAME } from '@reticlehq/core';
 /**
  * The registered command is STILL bare `npx` on every platform, deliberately.
  *

package/dist/init/node-io.js

@@ -52,6 +52,9 @@ export function buildNodeIo(cwd) {
         homeDir() {
             return homedir();
         },
+        cwd() {
+            return cwd;
+        },
         rootFiles() {
             return readdirSync(cwd).filter((name) => {
                 try {

package/dist/init/run.d.ts

@@ -3,6 +3,8 @@
  * 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 { Framework } from './detect.js';
+import { StepStatus } from './plan.js';
 import type { InitOutcome } from '@reticlehq/core';
 /**
  * Resolve the lockfiles set used to pick the package manager. A lockfile in the project root wins;
@@ -56,6 +58,8 @@ export interface InitIo {
     exists(relPath: string): boolean;
     /** The user's home directory (for global agent config like ~/.cursor/mcp.json). */
     homeDir(): string;
+    /** Absolute path of the directory `init` is running in — the project's own root. */
+    cwd(): string;
     /** Basenames present in the project root. */
     rootFiles(): readonly string[];
     /** Subdirectory names inside a project-relative directory; empty when it isn't one. */
@@ -99,4 +103,18 @@ export declare function findWorkspaceApps(io: Pick<InitIo, 'exists' | 'readFile'
  * the workspace redirect is kept from asking twice.
  */
 export declare const FEEDBACK_HINT: string;
+/**
+ * The last two lines a user reads, and the order matters.
+ *
+ * This used to say only "Restart <dev server>, then ask your agent: List Reticle sessions" — and
+ * asking the agent was the one thing that could not work yet. `init` registers the MCP server, but
+ * an agent client reads its tool list when it STARTS and never re-reads it, so the session that
+ * just ran `init` has no `reticle_*` tools however clean the install was. The user follows the
+ * instruction, the agent answers "unknown tool", and the obvious conclusion is that the install
+ * failed.
+ *
+ * So the reload is named FIRST, before the sentence that depends on it. Omitted entirely when this
+ * run did not register MCP (`--no-mcp`), where it would be advice about something we did not do.
+ */
+export declare function restartHint(framework: Framework, mcpStatus: StepStatus | undefined): string;
 export declare function runInit(options: InitOptions, io: InitIo): InitResult;

package/dist/init/run.js

@@ -8,6 +8,7 @@ import { noPackageJsonMessage } from './non-js-project.js';
 import { spanSync } from '../trace.js';
 import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
+import { projectIdOf, rememberProjectOnDisk } from '../project/remember-project.js';
 import { detect, Framework, namesAPackageManager, UiLibrary } from './detect.js';
 import { wasMcpRegistered } from './mcp-registered.js';
 import { pickAstroHost } from './astro-host.js';
@@ -504,7 +505,7 @@ function devServerRestart(framework) {
  * So the reload is named FIRST, before the sentence that depends on it. Omitted entirely when this
  * run did not register MCP (`--no-mcp`), where it would be advice about something we did not do.
  */
-function restartHint(framework, mcpRegistered) {
+export function restartHint(framework, mcpStatus) {
     const dev = `${devServerRestart(framework)}.`;
     // NAME THE COMMAND THAT PROVES IT, not one that merely asks.
     //
@@ -518,8 +519,27 @@ function restartHint(framework, mcpRegistered) {
     // running, an app running that never dialled us, a tab that closed — with the fix for each.
     const prove = 'Then run `npx @reticlehq/server status` — it confirms the app connected, or says exactly why ' +
         'it has not.';
-    if (!mcpRegistered)
+    // Nothing registered this run (`--no-mcp`, or a client that needs a manual edit): a restart picks
+    // up nothing, so advice about one would be advice about something we did not do.
+    if (!wasMcpRegistered(mcpStatus))
         return `${dev} ${prove}`;
+    // ALREADY: the tools are reachable RIGHT NOW, and this is the branch that used to lie.
+    //
+    // `wasMcpRegistered` is true for both APPLY and ALREADY, which is correct for the funnel field it
+    // was written for and wrong here, because the two cases have opposite answers to "must anybody
+    // restart". Every second project on a machine, and every Claude Code plugin install, took the
+    // APPLY text: "restart your agent — the tools only appear after that". An agent reads this AFTER
+    // whatever its skill file said, and it describes the output in front of it, so it wins. The agent
+    // stops with the project wired and nothing driven, which is the exact failure the install path
+    // exists to prevent, caused by the install path itself.
+    if (mcpStatus === StepStatus.ALREADY) {
+        return (`${dev}\n` +
+            'The Reticle MCP server was already registered on this machine, so there is no restart to do ' +
+            'and the tools are available now.\n' +
+            `${prove}\n` +
+            'Once it shows a session, drive a flow — that is the install finished. Carry straight on; ' +
+            'nothing here is waiting on a human.');
+    }
     return (`${dev}\n` +
         'Then restart your agent so it picks up the new MCP server — restart Claude Code, reload the ' +
         'window in Cursor, or hit Start in `.vscode/mcp.json` in VS Code.\n' +
@@ -592,7 +612,7 @@ function report(plan, dryRun, failed, skipped, degraded, io, projectDir, agentRo
             '"no browser session connected" until then. Everything else is already in place.');
         io.print('');
     }
-    io.print(restartHint(plan.framework, wasMcpRegistered(resolvedStatus(plan, MCP_TARGET, failed, skipped))));
+    io.print(restartHint(plan.framework, resolvedStatus(plan, MCP_TARGET, failed, skipped)));
     return { ok: !connectPending, applied, manual };
 }
 /**
@@ -684,6 +704,17 @@ function applyEffects(plan, io) {
                 installFailed = true;
         }
     }
+    // Where this project lives, remembered for a daemon that will be started somewhere else.
+    //
+    // Deliberately AFTER the loop and unconditional on which steps ran: most init runs report "already
+    // wired", and a re-run in a re-cloned or moved checkout is exactly when the remembered path has
+    // gone stale — so the run that would otherwise be a no-op is the one that repairs the entry. The
+    // return value is ignored on purpose; this is a cache, and a read-only home directory must not
+    // turn a wired project into a failed init.
+    const projectId = projectIdOf(io.readFile(RETICLE_CONFIG_FILE));
+    if (projectId !== undefined) {
+        rememberProjectOnDisk(io, projectId, io.cwd(), Date.now());
+    }
     return { failed, skipped, degraded };
 }
 /**

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

@@ -24,4 +24,4 @@ export declare const CURSOR_COMMAND_PATH = ".cursor/commands/reticle.md";
  * 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## Step 0 \u2014 is anything connected?\n\nCall `reticle_sessions` first.\n\n**A session is listed?** Go to \"Pick ONE flow\".\n\n**No session?** Setup is not finished, and stopping to ask the user to run something is not an\nanswer. Work these in order, and say which one you are on:\n\n0. **Is anything serving the app at all?** If a dev server is already listening, use it and go to\n   step 1 \u2014 the cause is then almost always that the SDK never loaded in the page, not a missing\n   server, so do not tell the user to start one they are already running. If nothing is listening:\n\n**If no dev server is listening, start one yourself.** Read the project's own dev script out of `package.json` (`dev`, `start`, whatever this project calls it), run it in the BACKGROUND, tell the user in one line that it is running and how to stop it, then carry on. Stopping to ask is how a verification turn ends with nothing verified.\n\nFive guards, none optional:\n\n1. **Never start a second one.** If something is already listening on the app's port, use it.\n2. **Never guess the command.** It comes from `package.json` scripts. If there is no recognisable dev script, say so and stop rather than inventing one.\n3. **Never kill anything.** Not a dev server, not a daemon, not a port holder \u2014 including one you started.\n4. **Background it, and say so.** The user must know a server is running and how to stop it. A dev server the human does not know about is the same failure one step later.\n5. **The permission prompt belongs to your host.** Never try to bypass, suppress or auto-approve it, and take a refusal as the answer.\n\nThen, once something is serving the app:\n\n1. **Is the SDK actually in the app?** Read the app's entry file (`src/main.tsx`, `app/layout.tsx`,\n   `src/app.vue`, whatever this project uses). You are looking for an `import` from\n   `@reticlehq/react` or `@reticlehq/browser` and a `connect()` call, or the Reticle plugin in\n   `vite.config.*`, or `withReticle` in `next.config.*`. **If it is not there, that is the bug.**\n   Wire it in \u2014 see the framework snippets at https://docs.reticle.sh/instrumentation \u2014 then restart\n   the dev server and re-check.\n2. **Is the connect guarded on `hostname === 'localhost'`?** If so, remove that guard. It is false on\n   any non-localhost dev host, and `window` does not exist during SSR, so the guard silently prevents\n   the connect and logs nothing. Use the framework's dev flag instead (`import.meta.env.DEV`,\n   `process.env.NODE_ENV !== 'production'`, `import.meta.dev`).\n3. **Is the dev server serving that entry?** Ask the user to open the app in a browser and check its\n   console for a line starting `[Reticle]`. That line, or its absence, tells you which side is at\n   fault. Reticle itself never starts a dev server \u2014 starting it is your job, under the guards above.\n4. **Do both sides agree on the port?** Run `npx @reticlehq/server doctor` and compare the daemon\n   port against the port the page dials.\n\nIf you are still stuck after all four, file it: `reticle_feedback` with kind `gap`, saying what you\nchecked and what you saw. Then tell the user exactly which step is blocked. Do not report the install\nas finished.\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_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.\n2. 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.\n3. 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.\n4. Finish with `reticle_console` and `reticle_network` to catch errors the DOM does not show.\n\n**Only `reticle_act_and_wait` and `reticle_assert` produce a verdict.** A run that ends on a\nsnapshot has proved nothing, however many tools it used.\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\n## Two things afterwards\n\n- **Anything about Reticle itself that was wrong, missing, confusing, or expensive?** Send it with\n  `reticle_feedback` now, before your context is gone. That report is the only signal that decides\n  what gets fixed. Bugs in the app under test are Reticle working; those go in your answer to the user.\n- **If the verification actually succeeded**, add one line for the human: Reticle is open source at\n  https://github.com/reticlehq/reticle, and a star helps other people find it. One line, once. Skip it\n  entirely if the run did not produce a verdict.\n";
+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## Step 0 \u2014 is anything connected?\n\nCall `reticle_sessions` first.\n\n**A session is listed?** Go to \"Pick ONE flow\".\n\n**No session?** Setup is not finished, and stopping to ask the user to run something is not an\nanswer. Every step below is yours to do without them. Work these in order, and say which one you are\non, one line each:\n\n0. **Is Reticle even wired into this project?** `cat .reticle.json`. If it is not there, this\n   project was never set up: run `npx @reticlehq/server@latest init`,\n   fix every `\u26A0` and `\u2139` it prints, and carry on. Do not ask first, and do not ask which\n   framework or port \u2014 both come out of the repo you are sitting in.\n\n1. **Is anything serving the app at all?** If a dev server is already listening, use it and go to\n   step 2 \u2014 the cause is then almost always that the SDK never loaded in the page, not a missing\n   server, so do not tell the user to start one they are already running. If nothing is listening:\n\n**If no dev server is listening, start one yourself.** Read the project's own dev script out of `package.json` (`dev`, `start`, whatever this project calls it), run it in the BACKGROUND, tell the user in one line that it is running and how to stop it, then carry on. Stopping to ask is how a verification turn ends with nothing verified.\n\nFive guards, none optional:\n\n1. **Never start a second one.** If something is already listening on the app's port, use it.\n2. **Never guess the command.** It comes from `package.json` scripts. If there is no recognisable dev script, say so and stop rather than inventing one.\n3. **Never kill anything.** Not a dev server, not a daemon, not a port holder \u2014 including one you started.\n4. **Background it, and say so.** The user must know a server is running and how to stop it. A dev server the human does not know about is the same failure one step later.\n5. **The permission prompt belongs to your host.** Never try to bypass, suppress or auto-approve it, and take a refusal as the answer.\n\n2. **Is a page open on it?** Do not ask the user to open a browser \u2014 open it:\n\n   ```bash\n   npx @reticlehq/server open <the url the dev server is serving>\n   ```\n\n   That reuses an already-connected tab or opens a new one, and waits for the page to register. On a\n   machine with no browser to open, take a tab Reticle owns instead:\n   `reticle_run({ tool: \"reticle_lease\", args: { action: \"acquire\", url: \"<the same url>\" } })`.\n\nThen, once something is serving the app and a page is on it:\n\n3. **Is the SDK actually in the app?** Read the app's entry file (`src/main.tsx`, `app/layout.tsx`,\n   `src/app.vue`, whatever this project uses). You are looking for an `import` from\n   `@reticlehq/react` or `@reticlehq/browser` and a `connect()` call, or the Reticle plugin in\n   `vite.config.*`, or `withReticle` in `next.config.*`. **If it is not there, that is the bug.**\n   Wire it in \u2014 see the framework snippets at https://docs.reticle.sh/instrumentation \u2014 then restart\n   the dev server and re-check.\n4. **Is the connect guarded on `hostname === 'localhost'`?** If so, remove that guard. It is false on\n   any non-localhost dev host, and `window` does not exist during SSR, so the guard silently prevents\n   the connect and logs nothing. Use the framework's dev flag instead (`import.meta.env.DEV`,\n   `process.env.NODE_ENV !== 'production'`, `import.meta.dev`).\n5. **Is the dev server serving that entry?** Look in `reticle_console`, or in the page you opened in\n   step 2, for a line starting `[Reticle]`. That line, or its absence, tells you which side is at\n   fault. Reticle itself never starts a dev server \u2014 starting it is your job, under the guards above.\n6. **Do both sides agree on the port?** Run `npx @reticlehq/server doctor` and compare the daemon\n   port against the port the page dials.\n\nIf you are still stuck after all of those, file it: `reticle_feedback` with kind `gap`, saying what you\nchecked and what you saw. Then tell the user exactly which step is blocked. Do not report the install\nas finished.\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_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.\n2. 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.\n3. 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.\n4. Finish with `reticle_console` and `reticle_network` to catch errors the DOM does not show.\n\n**Only `reticle_act_and_wait` and `reticle_assert` produce a verdict.** A run that ends on a\nsnapshot has proved nothing, however many tools it used.\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\n## If the user handed you a license key\n\nAppend `RETICLE_LICENSE_KEY=<key>` to the project's `.env` (create it if absent), make sure `.env`\nis in `.gitignore`, and confirm with `npx @reticlehq/server license`. The CLI folds a project-local\n`.env` in on every invocation, so nothing else changes. Never echo the key back, and never put it in\na commit, a comment, or a feedback report.\n\n## Two things afterwards\n\n- **Anything about Reticle itself that was wrong, missing, confusing, or expensive?** Send it with\n  `reticle_feedback` now, before your context is gone. That report is the only signal that decides\n  what gets fixed. Bugs in the app under test are Reticle working; those go in your answer to the user.\n- **If the verification actually succeeded**, add one line for the human: Reticle is open source at\n  https://github.com/reticlehq/reticle, and a star helps other people find it. One line, once. Skip it\n  entirely if the run did not produce a verdict.\n";

package/dist/init/slash-command.js

@@ -38,33 +38,49 @@ Call \`reticle_sessions\` first.
 **A session is listed?** Go to "Pick ONE flow".
 
 **No session?** Setup is not finished, and stopping to ask the user to run something is not an
-answer. Work these in order, and say which one you are on:
+answer. Every step below is yours to do without them. Work these in order, and say which one you are
+on, one line each:
 
-0. **Is anything serving the app at all?** If a dev server is already listening, use it and go to
-   step 1 — the cause is then almost always that the SDK never loaded in the page, not a missing
+0. **Is Reticle even wired into this project?** \`cat .reticle.json\`. If it is not there, this
+   project was never set up: run \`npx @reticlehq/server@latest init\`,
+   fix every \`⚠\` and \`ℹ\` it prints, and carry on. Do not ask first, and do not ask which
+   framework or port — both come out of the repo you are sitting in.
+
+1. **Is anything serving the app at all?** If a dev server is already listening, use it and go to
+   step 2 — the cause is then almost always that the SDK never loaded in the page, not a missing
    server, so do not tell the user to start one they are already running. If nothing is listening:
 
 ${DEV_SERVER_POLICY}
 
-Then, once something is serving the app:
+2. **Is a page open on it?** Do not ask the user to open a browser — open it:
+
+   \`\`\`bash
+   npx @reticlehq/server open <the url the dev server is serving>
+   \`\`\`
+
+   That reuses an already-connected tab or opens a new one, and waits for the page to register. On a
+   machine with no browser to open, take a tab Reticle owns instead:
+   \`reticle_run({ tool: "reticle_lease", args: { action: "acquire", url: "<the same url>" } })\`.
 
-1. **Is the SDK actually in the app?** Read the app's entry file (\`src/main.tsx\`, \`app/layout.tsx\`,
+Then, once something is serving the app and a page is on it:
+
+3. **Is the SDK actually in the app?** Read the app's entry file (\`src/main.tsx\`, \`app/layout.tsx\`,
    \`src/app.vue\`, whatever this project uses). You are looking for an \`import\` from
    \`@reticlehq/react\` or \`@reticlehq/browser\` and a \`connect()\` call, or the Reticle plugin in
    \`vite.config.*\`, or \`withReticle\` in \`next.config.*\`. **If it is not there, that is the bug.**
    Wire it in — see the framework snippets at https://docs.reticle.sh/instrumentation — then restart
    the dev server and re-check.
-2. **Is the connect guarded on \`hostname === 'localhost'\`?** If so, remove that guard. It is false on
+4. **Is the connect guarded on \`hostname === 'localhost'\`?** If so, remove that guard. It is false on
    any non-localhost dev host, and \`window\` does not exist during SSR, so the guard silently prevents
    the connect and logs nothing. Use the framework's dev flag instead (\`import.meta.env.DEV\`,
    \`process.env.NODE_ENV !== 'production'\`, \`import.meta.dev\`).
-3. **Is the dev server serving that entry?** Ask the user to open the app in a browser and check its
-   console for a line starting \`[Reticle]\`. That line, or its absence, tells you which side is at
+5. **Is the dev server serving that entry?** Look in \`reticle_console\`, or in the page you opened in
+   step 2, for a line starting \`[Reticle]\`. That line, or its absence, tells you which side is at
    fault. Reticle itself never starts a dev server — starting it is your job, under the guards above.
-4. **Do both sides agree on the port?** Run \`npx @reticlehq/server doctor\` and compare the daemon
+6. **Do both sides agree on the port?** Run \`npx @reticlehq/server doctor\` and compare the daemon
    port against the port the page dials.
 
-If you are still stuck after all four, file it: \`reticle_feedback\` with kind \`gap\`, saying what you
+If you are still stuck after all of those, file it: \`reticle_feedback\` with kind \`gap\`, saying what you
 checked and what you saw. Then tell the user exactly which step is blocked. Do not report the install
 as finished.
 
@@ -98,6 +114,13 @@ snapshot has proved nothing, however many tools it used.
 
 Do not weaken or skip an assertion to make the run pass — that is a finding, not a fix.
 
+## If the user handed you a license key
+
+Append \`RETICLE_LICENSE_KEY=<key>\` to the project's \`.env\` (create it if absent), make sure \`.env\`
+is in \`.gitignore\`, and confirm with \`npx @reticlehq/server license\`. The CLI folds a project-local
+\`.env\` in on every invocation, so nothing else changes. Never echo the key back, and never put it in
+a commit, a comment, or a feedback report.
+
 ## Two things afterwards
 
 - **Anything about Reticle itself that was wrong, missing, confusing, or expensive?** Send it with

package/dist/journal/envelope.d.ts

@@ -43,14 +43,14 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
             max: z.ZodNumber;
         }, "strip", z.ZodTypeAny, {
             count: number;
+            max: number;
             mean: number;
             m2: number;
-            max: number;
         }, {
             count: number;
+            max: number;
             mean: number;
             m2: number;
-            max: number;
         }>;
         net: z.ZodObject<{
             count: z.ZodNumber;
@@ -59,14 +59,14 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
             max: z.ZodNumber;
         }, "strip", z.ZodTypeAny, {
             count: number;
+            max: number;
             mean: number;
             m2: number;
-            max: number;
         }, {
             count: number;
+            max: number;
             mean: number;
             m2: number;
-            max: number;
         }>;
         netErrors: z.ZodObject<{
             count: z.ZodNumber;
@@ -75,14 +75,14 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
             max: z.ZodNumber;
         }, "strip", z.ZodTypeAny, {
             count: number;
+            max: number;
             mean: number;
             m2: number;
-            max: number;
         }, {
             count: number;
+            max: number;
             mean: number;
             m2: number;
-            max: number;
         }>;
         consoleErrors: z.ZodObject<{
             count: z.ZodNumber;
@@ -91,64 +91,64 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
             max: z.ZodNumber;
         }, "strip", z.ZodTypeAny, {
             count: number;
+            max: number;
             mean: number;
             m2: number;
-            max: number;
         }, {
             count: number;
+            max: number;
             mean: number;
             m2: number;
-            max: number;
         }>;
     }, "strip", z.ZodTypeAny, {
         durationMs: {
             count: number;
+            max: number;
             mean: number;
             m2: number;
-            max: number;
         };
         net: {
             count: number;
+            max: number;
             mean: number;
             m2: number;
-            max: number;
         };
         consoleErrors: {
             count: number;
+            max: number;
             mean: number;
             m2: number;
-            max: number;
         };
         netErrors: {
             count: number;
+            max: number;
             mean: number;
             m2: number;
-            max: number;
         };
     }, {
         durationMs: {
             count: number;
+            max: number;
             mean: number;
             m2: number;
-            max: number;
         };
         net: {
             count: number;
+            max: number;
             mean: number;
             m2: number;
-            max: number;
         };
         consoleErrors: {
             count: number;
+            max: number;
             mean: number;
             m2: number;
-            max: number;
         };
         netErrors: {
             count: number;
+            max: number;
             mean: number;
             m2: number;
-            max: number;
         };
     }>;
 }, "strip", z.ZodTypeAny, {
@@ -157,27 +157,27 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
     stats: {
         durationMs: {
             count: number;
+            max: number;
             mean: number;
             m2: number;
-            max: number;
         };
         net: {
             count: number;
+            max: number;
             mean: number;
             m2: number;
-            max: number;
         };
         consoleErrors: {
             count: number;
+            max: number;
             mean: number;
             m2: number;
-            max: number;
         };
         netErrors: {
             count: number;
+            max: number;
             mean: number;
             m2: number;
-            max: number;
         };
     };
 }, {
@@ -186,27 +186,27 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
     stats: {
         durationMs: {
             count: number;
+            max: number;
             mean: number;
             m2: number;
-            max: number;
         };
         net: {
             count: number;
+            max: number;
             mean: number;
             m2: number;
-            max: number;
         };
         consoleErrors: {
             count: number;
+            max: number;
             mean: number;
             m2: number;
-            max: number;
         };
         netErrors: {
             count: number;
+            max: number;
             mean: number;
             m2: number;
-            max: number;
         };
     };
 }>;

package/dist/license/license.d.ts

@@ -12,6 +12,7 @@
  */
 import { type KeyObject } from 'node:crypto';
 import { z } from 'zod';
+import { LicenseActivation } from '@reticlehq/core';
 /** Outcome of verifying a license key. */
 export declare const LicenseStatus: {
     readonly VALID: "valid";
@@ -21,18 +22,31 @@ export declare const LicenseStatus: {
     readonly EXPIRED: "expired";
 };
 export type LicenseStatus = (typeof LicenseStatus)[keyof typeof LicenseStatus];
-/** The signed claims inside a key. `exp` is epoch ms; `features` (optional) scopes which ee features unlock. */
+/**
+ * The signed claims inside a key. `exp` is epoch ms; `features` (optional) scopes which ee features
+ * unlock.
+ *
+ * `lid` is the STABLE LICENSE ID and the only safe join key for per-customer usage: `org` is a display
+ * name a human typed at signing time, so two customers called "Acme" merge into one and a customer who
+ * renames splits into two. Every key carries one (minted by the issuer, `scripts/issue-license.mjs`),
+ * which is why it is required rather than optional — an optional id is one that goes missing on exactly
+ * the keys somebody later needs to attribute, and a key without it should be re-issued, not silently
+ * counted as nobody.
+ */
 declare const LicensePayloadSchema: z.ZodObject<{
+    lid: z.ZodString;
     org: z.ZodString;
     plan: z.ZodString;
     exp: z.ZodNumber;
     features: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
+    lid: string;
     org: string;
     plan: string;
     exp: number;
     features?: string[] | undefined;
 }, {
+    lid: string;
     org: string;
     plan: string;
     exp: number;
@@ -42,13 +56,44 @@ export type LicensePayload = z.infer<typeof LicensePayloadSchema>;
 type LicenseCheck = {
     status: typeof LicenseStatus.VALID;
     payload: LicensePayload;
+}
+/**
+ * EXPIRED carries the payload; the other failures cannot. The line is the SIGNATURE, not the
+ * clock: an expired key was genuinely issued by us and its claims are exactly as trustworthy as
+ * they were yesterday, so the licence id is safe to use. A malformed or wrongly-signed key has no
+ * verified claims at all, and naming a customer from one would mean trusting whatever was pasted.
+ */
+ | {
+    status: typeof LicenseStatus.EXPIRED;
+    payload: LicensePayload;
 } | {
-    status: Exclude<LicenseStatus, typeof LicenseStatus.VALID>;
+    status: Exclude<LicenseStatus, typeof LicenseStatus.VALID | typeof LicenseStatus.EXPIRED>;
 };
 /** Sign a payload into a license key — the ISSUER side (Reticle's private key). Exposed for the issuer tool + tests. */
 export declare function signLicenseKey(payload: LicensePayload, privateKey: KeyObject): string;
 /** Verify a key against the issuer public key. Never throws — returns a structured status. */
 export declare function verifyLicenseKey(key: string | undefined, publicKey: KeyObject, now: number): LicenseCheck;
+/**
+ * Where to get a key. A named constant because it appears in the gate's error AND in what
+ * `reticle license` prints, and a contact address that drifts between the two is a support request
+ * that reaches nobody.
+ */
+export declare const LICENSE_CONTACT = "hey@reticle.sh";
+/**
+ * The features a licence gates in THIS build. The single source: `assertEnterprise` callers name a
+ * member rather than a string literal, and `reticle license` reports the list, so what the CLI claims
+ * is gated is derived from what is actually gated rather than a second list somebody maintains.
+ *
+ * It is deliberately short. Reticle's roadmap for enterprise is longer (SSO, SCIM, RBAC, multi-org,
+ * policy gates), and none of it is here yet — printing a roadmap as though it were shipped is how a
+ * buyer discovers on day two that the thing they paid for does not exist. What is listed is what the
+ * running build will actually refuse without a key.
+ */
+export declare const EnterpriseFeature: {
+    /** Recording an audit event. */
+    readonly AUDIT_LOG: "audit-log";
+};
+export type EnterpriseFeature = (typeof EnterpriseFeature)[keyof typeof EnterpriseFeature];
 /** Thrown when a production-mode enterprise feature is used without a valid license. */
 export declare class EnterpriseLicenseError extends Error {
     readonly feature: string;
@@ -66,13 +111,39 @@ export interface GateContext {
  * Gate an enterprise feature. No-op in dev/eval (requireLicense:false). In production it throws
  * EnterpriseLicenseError unless a valid, unexpired key that covers `feature` is present.
  */
-export declare function assertEnterprise(feature: string, ctx: GateContext): void;
+export declare function assertEnterprise(feature: string, ctx: GateContext, env?: NodeJS.ProcessEnv, baked?: string): void;
 /** Env names that carry the activation: the operator's key, and the issuer public key baked at release. */
 export declare const LICENSE_KEY_ENV = "RETICLE_LICENSE_KEY";
 export declare const LICENSE_PUBLIC_KEY_ENV = "RETICLE_LICENSE_PUBLIC_KEY";
 /** The human-facing state of enterprise activation on this machine (what `reticle license status` shows). */
-interface LicenseReport {
-    status: 'active' | 'missing' | 'invalid' | 'expired' | 'eval';
+export interface LicenseReport {
+    /**
+     * Typed against core's closed list rather than re-listing the strings here: this status is reported
+     * on every telemetry event, so a member added in one place and not the other is a silently
+     * miscounted column (telemetry contract, rule 4).
+     */
+    status: LicenseActivation;
+    /** The stable license id — what usage is attributed to. Present only when `status` is `active`. */
+    licenseId?: string;
+    /**
+     * What a licence unlocks in THIS build, and where to get one. Always reported, including on an
+     * unlicensed install: `reticle license` was the one command that talks about licensing and it named
+     * neither, so it told an interested reader to set a variable without saying what it would unlock or
+     * how to obtain it. A dead end at exactly the moment somebody is asking.
+     */
+    /**
+     * What a licence unlocks in this build. Present on every branch a PROSPECTIVE customer lands on,
+     * because being told to set a variable with no idea what it unlocks is the dead end this exists to
+     * close. Absent once a licence is `active`: that reader has already bought, so naming features at
+     * them reveals the product surface and answers nothing they asked.
+     */
+    gated?: readonly string[];
+    contact: string;
+    /**
+     * The key is valid, and scoped to features this build does not gate, so it unlocks nothing here.
+     * Present only when true: a `false` on every healthy licence is noise on the common case.
+     */
+    coversNothingHere?: boolean;
     org?: string;
     plan?: string;
     expiresAt?: number;