@alwaysmeticulous/cli 2.326.1 → 2.328.0

package/dist/commands/onboard/setup-agent-integrations.d.ts

@@ -0,0 +1,43 @@
+export declare const METICULOUS_MCP_URL = "https://app.meticulous.ai/api/mcp";
+/**
+ * Registry package + pinned version for the `skills` CLI. Must never be
+ * resolved from the customer repo's node_modules (see installSkills).
+ */
+export declare const SKILLS_CLI_PACKAGE_SPEC = "skills@1.5.22";
+/** Args after the skills CLI entry — shared with the retry hint. */
+export declare const SKILLS_ADD_ARGS: readonly ["add", "alwaysmeticulous/skills", "--skill", "*", "--agent", "claude-code", "--agent", "codex", "--agent", "cursor", "--copy", "-y"];
+/** Paths the CLI may create for agent integrations — include these in the PR. */
+export declare const AGENT_INTEGRATION_PATHS: readonly [".claude/skills/", ".agents/skills/", ".cursor/skills/", "skills-lock.json", ".mcp.json", ".cursor/mcp.json", ".codex/config.toml"];
+export declare const setupAgentIntegrations: (options: {
+    projectRoot: string;
+}) => string[];
+export declare const installSkills: (projectRoot: string) => boolean;
+/**
+ * Drops env vars that can redirect Node/npm resolution or inject code into
+ * the child. The customer repo stays as cwd for install destinations, so we
+ * must not inherit hooks that run before the trusted CLI entry.
+ *
+ * Installing from a temp cwd is not enough on its own: running onboard through
+ * `npm run` / `pnpm exec` exports the repo's `.npmrc` as `npm_config_*`, which
+ * takes precedence over cwd, and prepends `node_modules/.bin` to PATH so even
+ * `npm` itself could be repo-controlled. Dropping both falls back to the
+ * developer's own user and global npm config, which is trusted.
+ */
+export declare const sanitizeSkillsInstallEnv: (env: NodeJS.ProcessEnv) => NodeJS.ProcessEnv;
+/**
+ * Installs the pinned registry `skills` package into a fresh temp prefix and
+ * returns the absolute path to its CLI entry. Callers must invoke `cleanup`
+ * (including on failure after a successful materialize).
+ */
+export declare const materializeTrustedSkillsCli: () => {
+    cliEntry: string;
+    cleanup: () => void;
+};
+/** Writes the canonical Meticulous MCP config into Claude/Cursor/Codex files. */
+export declare const ensureProjectMcp: (projectRoot: string) => void;
+/**
+ * True only when `existing` is a plain object with exactly the same keys and
+ * primitive values as `expected` (no extras, no nesting surprises).
+ */
+export declare const isExactJsonServerConfig: (existing: unknown, expected: Record<string, unknown>) => boolean;
+//# sourceMappingURL=setup-agent-integrations.d.ts.map

package/dist/commands/onboard/setup-agent-integrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-agent-integrations.d.ts","sourceRoot":"","sources":["../../../src/commands/onboard/setup-agent-integrations.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,kBAAkB,sCAAsC,CAAC;AAEtE;;;GAGG;AACH,eAAO,MAAM,uBAAuB,kBAAkB,CAAC;AAEvD,oEAAoE;AACpE,eAAO,MAAM,eAAe,gJAalB,CAAC;AAEX,iFAAiF;AACjF,eAAO,MAAM,uBAAuB,+IAQ1B,CAAC;AAEX,eAAO,MAAM,sBAAsB,YAAa;IAC9C,WAAW,EAAE,MAAM,CAAC;CACrB,KAAG,MAAM,EAuBT,CAAC;AAEF,eAAO,MAAM,aAAa,gBAAiB,MAAM,KAAG,OAwDnD,CAAC;AAMF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,QAC9B,MAAM,CAAC,UAAU,KACrB,MAAM,CAAC,UAyBT,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,QAAO;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,IAAI,CAAC;CA6CrB,CAAC;AA+BF,iFAAiF;AACjF,eAAO,MAAM,gBAAgB,gBAAiB,MAAM,KAAG,IAkDtD,CAAC;AAuFF;;;GAGG;AACH,eAAO,MAAM,uBAAuB,aACxB,OAAO,YACP,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAChC,OAcF,CAAC"}

package/dist/commands/onboard/setup-agent-integrations.js

@@ -0,0 +1,324 @@
+"use strict";
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d86e4f01-f4b3-5d15-b551-8b7f879cf289")}catch(e){}}();
+
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isExactJsonServerConfig = exports.ensureProjectMcp = exports.materializeTrustedSkillsCli = exports.sanitizeSkillsInstallEnv = exports.installSkills = exports.setupAgentIntegrations = exports.AGENT_INTEGRATION_PATHS = exports.SKILLS_ADD_ARGS = exports.SKILLS_CLI_PACKAGE_SPEC = exports.METICULOUS_MCP_URL = void 0;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const chalk_1 = __importDefault(require("chalk"));
+const cli_user_error_1 = require("../../utils/cli-user-error");
+const codex_mcp_1 = require("./codex-mcp");
+const safe_repo_fs_1 = require("./safe-repo-fs");
+exports.METICULOUS_MCP_URL = "https://app.meticulous.ai/api/mcp";
+/**
+ * Registry package + pinned version for the `skills` CLI. Must never be
+ * resolved from the customer repo's node_modules (see installSkills).
+ */
+exports.SKILLS_CLI_PACKAGE_SPEC = "skills@1.5.22";
+/** Args after the skills CLI entry — shared with the retry hint. */
+exports.SKILLS_ADD_ARGS = [
+    "add",
+    "alwaysmeticulous/skills",
+    "--skill",
+    "*",
+    "--agent",
+    "claude-code",
+    "--agent",
+    "codex",
+    "--agent",
+    "cursor",
+    "--copy",
+    "-y",
+];
+/** Paths the CLI may create for agent integrations — include these in the PR. */
+exports.AGENT_INTEGRATION_PATHS = [
+    ".claude/skills/",
+    ".agents/skills/",
+    ".cursor/skills/",
+    "skills-lock.json",
+    ".mcp.json",
+    ".cursor/mcp.json",
+    ".codex/config.toml",
+];
+const setupAgentIntegrations = (options) => {
+    console.log(chalk_1.default.bold("Setting up Meticulous agent integrations…"));
+    // Install skills for all supported agents so the onboarding PR is useful
+    // regardless of which tool teammates use later.
+    const skillsInstalled = (0, exports.installSkills)(options.projectRoot);
+    installProjectMcp(options.projectRoot);
+    const created = listExistingIntegrationPaths(options.projectRoot, skillsInstalled);
+    if (created.length > 0) {
+        console.log(chalk_1.default.dim(`  These files should be included in the onboarding PR:\n${created
+            .map((p) => `    - ${p}`)
+            .join("\n")}`));
+    }
+    console.log("");
+    return created;
+};
+exports.setupAgentIntegrations = setupAgentIntegrations;
+const installSkills = (projectRoot) => {
+    // Reject repo-seeded symlinks on every path the skills installer may write
+    // (`.claude`, `.agents`, `.cursor`, `skills-lock.json`), then create those
+    // directory roots as real dirs before handing control to the installer.
+    (0, safe_repo_fs_1.prepareSafeSkillsInstallTargets)(projectRoot);
+    // Never `npx skills` with cwd=projectRoot: npx prefers a repo-local
+    // `node_modules/.bin/skills` (or a `file:` dependency) over the registry,
+    // so an untrusted repo could run arbitrary code before any agent sandbox.
+    // Materialize the registry CLI into a throwaway prefix, then invoke it by
+    // absolute path via `node`.
+    let trustedCli = null;
+    let result;
+    try {
+        trustedCli = (0, exports.materializeTrustedSkillsCli)();
+        result = (0, child_process_1.spawnSync)(process.execPath, [trustedCli.cliEntry, ...exports.SKILLS_ADD_ARGS], {
+            cwd: projectRoot,
+            stdio: "inherit",
+            env: (0, exports.sanitizeSkillsInstallEnv)(process.env),
+        });
+    }
+    catch (error) {
+        const detail = error instanceof Error ? `: ${error.message}` : `: ${String(error)}`;
+        console.log(chalk_1.default.yellow(`  Could not install Meticulous skills${detail}. Continuing without them.`));
+        console.log(chalk_1.default.dim(`  Retry: ${skillsInstallRetryHint(projectRoot)}`));
+        (0, safe_repo_fs_1.assertSafeSkillsInstallTargets)(projectRoot);
+        return false;
+    }
+    finally {
+        trustedCli?.cleanup();
+    }
+    // Always re-check after the installer — a failed or partial install can
+    // still plant a symlink escape on a destination we pre-created.
+    (0, safe_repo_fs_1.assertSafeSkillsInstallTargets)(projectRoot);
+    if (result.error || result.status !== 0) {
+        const detail = result.error ? `: ${result.error.message}` : "";
+        console.log(chalk_1.default.yellow(`  Could not install Meticulous skills${detail}. Continuing without them.`));
+        console.log(chalk_1.default.dim(`  Retry: ${skillsInstallRetryHint(projectRoot)}`));
+        return false;
+    }
+    console.log(chalk_1.default.green("  ✓ Installed Meticulous skills"));
+    return true;
+};
+exports.installSkills = installSkills;
+/** Matches a `node_modules/.bin` PATH entry, on either path separator. */
+const isPackageBinPathEntry = (entry) => /(?:^|[\\/])node_modules[\\/]\.bin[\\/]?$/u.test(entry.trim());
+/**
+ * Drops env vars that can redirect Node/npm resolution or inject code into
+ * the child. The customer repo stays as cwd for install destinations, so we
+ * must not inherit hooks that run before the trusted CLI entry.
+ *
+ * Installing from a temp cwd is not enough on its own: running onboard through
+ * `npm run` / `pnpm exec` exports the repo's `.npmrc` as `npm_config_*`, which
+ * takes precedence over cwd, and prepends `node_modules/.bin` to PATH so even
+ * `npm` itself could be repo-controlled. Dropping both falls back to the
+ * developer's own user and global npm config, which is trusted.
+ */
+const sanitizeSkillsInstallEnv = (env) => {
+    const next = { ...env };
+    delete next.NODE_OPTIONS;
+    delete next.NODE_PATH;
+    for (const key of Object.keys(next)) {
+        if (/^npm_config_/iu.test(key)) {
+            delete next[key];
+            continue;
+        }
+        // Windows spells it `Path`, so match case-insensitively.
+        if (key.toUpperCase() !== "PATH") {
+            continue;
+        }
+        const value = next[key];
+        if (typeof value !== "string") {
+            continue;
+        }
+        next[key] = value
+            .split(path_1.delimiter)
+            .filter((entry) => entry.length > 0 && !isPackageBinPathEntry(entry))
+            .join(path_1.delimiter);
+    }
+    return next;
+};
+exports.sanitizeSkillsInstallEnv = sanitizeSkillsInstallEnv;
+/**
+ * Installs the pinned registry `skills` package into a fresh temp prefix and
+ * returns the absolute path to its CLI entry. Callers must invoke `cleanup`
+ * (including on failure after a successful materialize).
+ */
+const materializeTrustedSkillsCli = () => {
+    const tempDir = (0, fs_1.mkdtempSync)((0, path_1.join)((0, os_1.tmpdir)(), "meticulous-skills-cli-"));
+    const cleanup = () => {
+        (0, fs_1.rmSync)(tempDir, { recursive: true, force: true });
+    };
+    const install = (0, child_process_1.spawnSync)("npm", [
+        "install",
+        "--ignore-scripts",
+        "--no-save",
+        "--prefix",
+        tempDir,
+        exports.SKILLS_CLI_PACKAGE_SPEC,
+    ], {
+        // Install outside the customer repo so a local `skills` package cannot
+        // satisfy the request.
+        cwd: tempDir,
+        encoding: "utf8",
+        env: (0, exports.sanitizeSkillsInstallEnv)(process.env),
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (install.error || install.status !== 0) {
+        cleanup();
+        const stderr = (install.stderr ?? "").toString().trim();
+        const detail = install.error?.message ??
+            (stderr.length > 0 ? stderr : `npm exited ${install.status}`);
+        throw new Error(`failed to download ${exports.SKILLS_CLI_PACKAGE_SPEC}: ${detail}`);
+    }
+    const cliEntry = (0, path_1.join)(tempDir, "node_modules", "skills", "bin", "cli.mjs");
+    if (!(0, fs_1.existsSync)(cliEntry)) {
+        cleanup();
+        throw new Error(`${exports.SKILLS_CLI_PACKAGE_SPEC} installed without bin/cli.mjs at ${cliEntry}`);
+    }
+    return { cliEntry, cleanup };
+};
+exports.materializeTrustedSkillsCli = materializeTrustedSkillsCli;
+const shellQuote = (value) => `'${value.replace(/'/g, `'\\''`)}'`;
+/**
+ * Paste-able equivalent of the install above. The download must run from the
+ * temp prefix, never the repo: npm reads `.npmrc` from its cwd, so a repo one
+ * could point `skills` at a customer-controlled registry. Only the CLI entry
+ * runs from the repo, since that is where skills get written.
+ */
+const skillsInstallRetryHint = (projectRoot) => {
+    const prefix = '"$prefix"';
+    const addArgs = exports.SKILLS_ADD_ARGS.map(shellQuote).join(" ");
+    return (`prefix="${"${TMPDIR:-/tmp}"}/meticulous-skills-cli" && mkdir -p ${prefix} && ` +
+        `(cd ${prefix} && npm install --ignore-scripts --no-save --prefix ${prefix} ${exports.SKILLS_CLI_PACKAGE_SPEC}) && ` +
+        `(cd ${shellQuote(projectRoot)} && node ${prefix}/node_modules/skills/bin/cli.mjs ${addArgs})`);
+};
+const installProjectMcp = (projectRoot) => {
+    // Always attempt every MCP config file. A parse/shape failure on one must
+    // not skip the others — otherwise a poisoned `.mcp.json` can leave an
+    // attacker-controlled `command`/`args` Meticulous server in Cursor/Codex.
+    // Any failure aborts onboard (via CliUserError); silently continuing would
+    // leave unsanitized MCP config under the official name.
+    (0, exports.ensureProjectMcp)(projectRoot);
+    console.log(chalk_1.default.green("  ✓ Added project-scoped Meticulous MCP"));
+};
+/** Writes the canonical Meticulous MCP config into Claude/Cursor/Codex files. */
+const ensureProjectMcp = (projectRoot) => {
+    const failures = [];
+    const attempts = [
+        {
+            label: ".mcp.json",
+            run: () => mergeJsonMcp(projectRoot, ".mcp.json", {
+                type: "http",
+                url: exports.METICULOUS_MCP_URL,
+            }),
+        },
+        {
+            label: ".cursor/mcp.json",
+            run: () => mergeJsonMcp(projectRoot, (0, path_1.join)(".cursor", "mcp.json"), {
+                url: exports.METICULOUS_MCP_URL,
+            }),
+        },
+        {
+            label: ".codex/config.toml",
+            run: () => (0, codex_mcp_1.mergeCodexMcp)(projectRoot, (0, path_1.join)(".codex", "config.toml"), exports.METICULOUS_MCP_URL),
+        },
+    ];
+    for (const attempt of attempts) {
+        try {
+            attempt.run();
+        }
+        catch (error) {
+            failures.push(error instanceof Error
+                ? error.message
+                : `${attempt.label}: ${String(error)}`);
+        }
+    }
+    if (failures.length > 0) {
+        throw new cli_user_error_1.CliUserError([
+            "Could not safely configure the Meticulous MCP server in every agent config.",
+            "Fix or remove the failing file(s), then re-run `meticulous onboard`:",
+            ...failures.map((message) => `  - ${message}`),
+        ].join("\n"));
+    }
+};
+exports.ensureProjectMcp = ensureProjectMcp;
+const listExistingIntegrationPaths = (projectRoot, skillsInstalled) => {
+    const found = [];
+    for (const path of exports.AGENT_INTEGRATION_PATHS) {
+        if (!skillsInstalled && isPrecreatedSkillsDirPath(path)) {
+            continue;
+        }
+        const absolute = (0, path_1.join)(projectRoot, path);
+        if ((0, fs_1.existsSync)(absolute)) {
+            found.push(path);
+        }
+    }
+    return found;
+};
+const isPrecreatedSkillsDirPath = (path) => path === ".claude/skills/" ||
+    path === ".agents/skills/" ||
+    path === ".cursor/skills/";
+const mergeJsonMcp = (projectRoot, relativePath, serverConfig) => {
+    const absolutePath = (0, safe_repo_fs_1.resolveSafeWritePath)(projectRoot, relativePath);
+    let config = {};
+    if ((0, fs_1.existsSync)(absolutePath)) {
+        let parsed;
+        try {
+            parsed = JSON.parse((0, fs_1.readFileSync)(absolutePath, "utf8"));
+        }
+        catch {
+            throw new cli_user_error_1.CliUserError(`Refusing to update '${relativePath}': file is not valid JSON. ` +
+                `Fix or remove it, then re-run \`meticulous onboard\`.`);
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new cli_user_error_1.CliUserError(`Refusing to update '${relativePath}': top-level value must be a JSON object.`);
+        }
+        config = parsed;
+    }
+    const existingServers = config["mcpServers"];
+    if (existingServers !== undefined &&
+        (!existingServers ||
+            typeof existingServers !== "object" ||
+            Array.isArray(existingServers))) {
+        throw new cli_user_error_1.CliUserError(`Refusing to update '${relativePath}': mcpServers must be a JSON object.`);
+    }
+    const mcpServers = (existingServers ?? {});
+    // Only trust a pre-existing entry when it is an exact match of the
+    // canonical config. A matching `url` alone is not enough — extra fields
+    // like `command` / `args` / `env` would keep an attacker-controlled local
+    // MCP server under the official "Meticulous" name.
+    if ((0, exports.isExactJsonServerConfig)(mcpServers["Meticulous"], serverConfig)) {
+        return;
+    }
+    (0, safe_repo_fs_1.writeFileSafeSync)(projectRoot, relativePath, JSON.stringify({
+        ...config,
+        mcpServers: {
+            ...mcpServers,
+            Meticulous: serverConfig,
+        },
+    }, null, 2) + "\n");
+};
+/**
+ * True only when `existing` is a plain object with exactly the same keys and
+ * primitive values as `expected` (no extras, no nesting surprises).
+ */
+const isExactJsonServerConfig = (existing, expected) => {
+    if (!existing || typeof existing !== "object" || Array.isArray(existing)) {
+        return false;
+    }
+    const record = existing;
+    const existingKeys = Object.keys(record).sort();
+    const expectedKeys = Object.keys(expected).sort();
+    if (existingKeys.length !== expectedKeys.length ||
+        existingKeys.some((key, index) => key !== expectedKeys[index])) {
+        return false;
+    }
+    return expectedKeys.every((key) => record[key] === expected[key]);
+};
+exports.isExactJsonServerConfig = isExactJsonServerConfig;
+//# sourceMappingURL=setup-agent-integrations.js.map
+//# debugId=d86e4f01-f4b3-5d15-b551-8b7f879cf289

package/dist/commands/onboard/setup-agent-integrations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-agent-integrations.js","sources":["../../../src/commands/onboard/setup-agent-integrations.ts"],"sourceRoot":"","names":[],"mappings":"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","debugId":"d86e4f01-f4b3-5d15-b551-8b7f879cf289"}

package/dist/commands/onboard/templates/CLAUDE.md

@@ -0,0 +1,213 @@
+# Meticulous Onboard
+
+## What This Is
+
+You are installing [Meticulous](https://www.meticulous.ai) into the customer's application
+repository. The repo itself is available via the added working directory (the parent of this
+workspace, or the path named in `onboard-context.json` → `projectRoot`).
+
+Your job is to **apply** the install in the real codebase (recorder snippet, CI workflow,
+conditional fixes) and then **open a pull request** with those changes.
+
+You do pause once — to get the user's approval on a short plan (step 4) — but a plan is not the
+deliverable. Do **not** write a plan markdown file and stop. The deliverable is one or more PRs
+containing small, correct diffs in the customer repo.
+
+## How Meticulous Works
+
+Meticulous records user sessions by injecting a JavaScript recorder snippet into customer
+applications. These sessions capture user activity and network requests. When a customer makes
+a commit, Meticulous triggers a test run that replays selected sessions against the new code,
+taking screenshots at key moments. Differences between the base (before) and head (after) runs
+are surfaced to the developer via a PR comment.
+
+## Context
+
+Read `.claude/onboard-context.json` (or `onboard-context.json` in this workspace) first. It
+contains:
+
+- `orgAndProject` — Meticulous project identifier when known
+- `projectRoot` — absolute path to the customer repository to edit
+- `repoUrl` — repository URL when known
+- `ciProvider` — `"github-actions"`, `"gitlab-ci"`, `"bitbucket-pipelines"`, or `"unknown"`
+- `isGitHubIntegrationActive` / `isGitLabIntegrationActive` / `isBitbucketIntegrationActive` —
+  whether the Meticulous project is already linked to that host
+- `isMonorepo` / `selectedAppPath` / `selectedAppName` / `selectedAppAbsolutePath` — the
+  frontend app the user already selected (or `.` for a single-package repo). **Stay scoped
+  to this app** for recorder and app-level changes; put shared CI at the repo root with
+  monorepo path filters when `isMonorepo` is true.
+- `frameworkDetection` — CLI heuristic (`framework`, `rendering`, `isUnsupportedSsr`,
+  `unsupportedSsrConfidence`). When `isUnsupportedSsr` is true, the CLI warned the user and
+  they chose to continue regardless of confidence. Validate the detection during review. If
+  you confirm SSR that is **not** Next.js Pages Router SSR, say so and confirm with the user
+  before applying anything; do not silently proceed, and do not silently abort either.
+- `meticulousSettingsUrl` / `meticulousTokensUrl` / `meticulousSessionsUrl` — dashboard links.
+  **Use `meticulousTokensUrl` for both the recording token and the project API token**
+  (Project → Settings → Tokens).
+- `githubConfigureProjectsUrl` — org page to link/map the GitHub repository to this project
+- `gitlabConfigureProjectsUrl` / `bitbucketConfigureProjectsUrl` — project settings (CI →
+  Linked repository) where the GitLab / Bitbucket access token is entered
+- `secretsUrl` / `secretsUrlLabel` — where to store the API token in CI (GitHub Actions
+  secrets, GitLab CI/CD variables, or Bitbucket repository variables)
+- `agentIntegrationPaths` — repo-relative skill/MCP paths the CLI already installed. **You
+  must stage and commit every existing path in this list in the onboarding PR.**
+- `meticulousSideSetupPath` — absolute path to write if this install needs work on the
+  Meticulous side (see below). Always write and quote that absolute path.
+
+## Reference docs
+
+The specialist playbooks in `.claude/agents/` cite doc paths like
+`.claude/docs/github-actions-v2.ts`. Those files are bundled into this workspace under
+`.claude/docs/` — **read them locally; they are the authoritative source** for the recorder
+snippet (per framework, under `.claude/docs/recorder-snippets/`) and the CI YAML.
+`github-actions-v2.ts` covers all three CI providers — GitHub Actions, GitLab CI and Bitbucket
+Pipelines; use the section matching `ciProvider`, and prefer the monorepo naming section when
+`isMonorepo` is true.
+
+These files are the docs site's source: the markdown lives in template literals. Content the docs
+site pulls in from another module (the GitLab and Bitbucket linking steps, for instance) has
+already been inlined for you. A remaining `${NAME}` is a constant declared in that same file —
+read its value there and use that. Never copy a `${NAME}` placeholder into the repo or the PR
+description as if it were text.
+
+If a cited file is somehow missing, you may fetch the published page: drop the `.claude/docs/`
+prefix and the `.ts` suffix and prepend `https://app.meticulous.ai/docs/` (public, no login;
+`app.meticulous.ai` is pre-approved for fetching). Know the fetched pages' limits: the
+framework-specific recorder snippets and the GitLab/Bitbucket CI tabs are rendered client-side,
+so a fetch will not contain them — only the local files have that content. Never invent the
+recorder snippet or the CI YAML from memory; if you cannot read it, say so and ask the user
+before proceeding.
+
+## Workflow
+
+1. **Reviewer first.** Dispatch the `reviewer` agent (Task) scoped to `selectedAppPath`.
+   Wait for the structured codebase summary. Do not edit application files until review is
+   done. If review finds unsupported SSR (not Next.js Pages), raise it with the user and wait
+   for their call before continuing.
+
+2. **Monorepo app selection is already done by the CLI** when `isMonorepo` is true — use
+   `selectedAppPath` / `selectedAppName`. Do **not** re-ask unless `selectedAppPath` is
+   missing or clearly wrong; if you must ask, wait for the user's answer before dispatching
+   specialists.
+
+3. **Dispatch applicable specialists in parallel.** After the reviewer (and any app selection),
+   emit **every** applicable customer-facing specialist as Task calls **in a single assistant
+   message** (side by side). Always include at least:
+   - `recorder-installation`
+   - `ci-setup`
+   - `false-positive-prevention`
+   - `local-simulation-verification`
+
+   Conditionally include (based on the review summary):
+   - `auth-setup` — only when server-side / mixed auth needs a Meticulous bypass
+   - `csp-setup` — when CSP is present
+   - `feature-flag-setup` — when feature flags affect UI
+   - `persisted-graphql-queries` — when persisted GraphQL is used
+   - `service-worker-compatibility` / `shared-worker-compatibility` — when workers matter
+   - `session-context` / `replay-fetch-retry-compatibility` — when the review calls for them
+
+   Pass each specialist the reviewer summary and the selected app path.
+
+4. **Agree the plan before editing anything.** Post a short plan and **wait for the user to
+   approve or amend it**. Keep it skimmable — no essay, no code dumps:
+   - the app being onboarded, and the recorder approach (script tag vs npm package, which file)
+   - the CI change (workflow/job path, monorepo path filters)
+   - each conditional fix, one line each, with the file it touches and why the review called
+     for it
+   - anything that needs Meticulous-side setup (see the section below)
+   - how you intend to split the PRs (see step 6) — say "one PR" when that is right
+   - anything the user must do by hand afterwards (tokens, repo linking)
+
+   Do **not** edit files under `projectRoot` until they approve. If they amend the plan, follow
+   the amended version. If the session is non-interactive (launched with `--headless`), post
+   the plan for the record and continue without waiting.
+
+5. **Apply the install yourself.** Using the specialist guidance, edit files under
+   `projectRoot`:
+   - Install the recorder (script tag or npm package, matching the framework)
+   - Add CI workflow / job for Meticulous
+   - Apply only the conditional fixes that the review said are needed
+   - Prefer the smallest correct change; do not refactor unrelated code
+   - Confirm each edit with a static read-back (snippet is first in `<head>`, workflow YAML is
+     valid). Do **not** build, start the app, or run a simulation to verify — that is the
+     customer's post-merge step.
+
+6. **Open the pull request(s).** This is the required final output.
+   - Create a new branch off the current branch, e.g. `meticulous/install`.
+   - One PR is the default. Split only when the user approved a split in step 4 — worth
+     proposing when the install carries risky or independently reviewable changes, e.g.
+     PR 1 recorder + CI + skills/MCP (the part that must land first), PR 2 compatibility fixes
+     (auth bypass, CSP, feature flags). When splitting:
+     - keep the recorder, CI and `agentIntegrationPaths` together in the first PR
+     - stack the branches — PR 2 branches off PR 1's branch and targets it, so its diff stays
+       reviewable; note in the description that it should be retargeted once PR 1 merges
+     - cross-link them in each description ("part 1 of 2", with the other PR's URL)
+   - Stage **both**:
+     1. the application/CI files you edited under `projectRoot`, and
+     2. every path listed in `onboard-context.json` → `agentIntegrationPaths`
+        (Meticulous skills + MCP config the CLI already installed — typically
+        `.claude/skills/`, `.agents/skills/`, `.cursor/skills/`, `skills-lock.json`,
+        `.mcp.json`, `.cursor/mcp.json`, `.codex/config.toml`). These **must** be in the PR.
+   - Never stage the `.meticulous-onboard` workspace, and never commit secrets.
+   - Commit with a clear message like `Add Meticulous visual testing`.
+   - Push the branch to `origin` and open a PR using the GitHub CLI (`gh pr create`) when it
+     is available. On GitLab, use `glab mr create` if present.
+   - The PR description must list what was installed first (including skills/MCP), then end
+     with a **Next steps** section for the reviewer. That section must include direct links
+     from context:
+     - recording token + project API token: `{meticulousTokensUrl}`
+     - recording token: public, read-only — safe to put in a build-time frontend env var
+       (e.g. `NEXT_PUBLIC_*` / `VITE_*`); it is meant to ship in the client bundle
+     - project API token: secret — store only in `{secretsUrl}` / `{secretsUrlLabel}`
+     - and any remaining manual steps
+   - If `gh`/`glab` is not installed or the user is not authenticated, do NOT abort the run:
+     commit and push the branch anyway (or leave the commit local if push fails), then print
+     the exact `gh pr create` / manual "open PR" command and the compare URL so the user can
+     finish in one click.
+
+7. **Report and stop.** Print every PR URL (or the branch name + exact command to open it) and
+   the files changed. If you wrote a Meticulous-side setup file, print its absolute path here. Put any
+   remaining secrets/tokens or manual follow-ups last under next steps. This is the end of the
+   run — do not start another review/specialist/verification pass.
+
+## When Meticulous-side setup is needed
+
+Some things cannot be fixed in the customer repo and need work on the Meticulous side — for
+example WebSocket traffic, an unusual auth flow that needs a server-side bypass, backend/network
+behaviour that has to be mocked centrally, or a session-recording limitation the specialists
+flagged.
+
+When you hit one of those, write the file at the absolute path `{meticulousSideSetupPath}` from
+context — always that absolute path, never a relative one: your cwd is this workspace rather than
+the repo, so a relative path ends up somewhere the user cannot find. The file must contain:
+
+- the Meticulous project (`orgAndProject`) and the app being onboarded (`selectedAppPath`)
+- one section per item: what you found, the files/evidence it came from, and what you need
+  Meticulous to do
+- what you did and did not install in the repo because of it
+
+Then tell the user to send that file to their Meticulous contact (or support@meticulous.ai),
+quoting its full absolute path so they can find it. Mention it in the PR description too, but
+**never commit it** — the `.meticulous-onboard` workspace is gitignored and stays local.
+
+## Rules
+
+- **Single pass. Do not re-verify or re-run.** Run the reviewer once and the specialist wave
+  once, get the plan approved, apply the changes, and open the PR. After applying, do **not**
+  re-dispatch the reviewer or any specialist to "double-check", and do not loop back to earlier
+  steps. One review → one specialist wave → plan approval → apply → PR.
+- **Do not build, run, or simulate the app yourself.** Never run `npm run build` / dev servers,
+  `meticulous simulate`, or a Meticulous test run to verify your work. Recorder installs and CI
+  config are verified by the customer's own first test run after merge — that is a post-merge
+  step, not part of this run. Static checks are fine (read the file back, confirm the snippet is
+  in `<head>`); actually executing the app or a simulation is not.
+- Verification instructions (local simulation, first test run) belong **only** in the PR
+  "Next steps" section for the customer to run later — you do not perform them.
+- Edit only under `projectRoot`. Do not modify this `.meticulous-onboard` workspace except for
+  notes such as `meticulous-side-setup.md`, and never commit it.
+- Never commit secrets (`.env` with private keys, project API tokens) into the repo. The
+  recording token is public/read-only and may be set as a build-time frontend variable.
+- Do not force-push, and do not push to the default branch — always use a new branch and a PR.
+- Do not invent Meticulous product behavior; follow the agent playbooks in `.claude/agents/`.
+- If blocked (missing token, unsupported SSR, etc.), explain clearly and stop rather than
+  guessing — but still commit whatever safe changes you have made on the branch.