@agent-native/core 0.44.4 → 0.45.1

package/dist/cli/recap.js

@@ -1,26 +1,44 @@
 /**
- * `agent-native recap <scan|build-prompt|shot|comment>` — the helper surface
- * used by the PR Visual Recap GitHub Action.
+ * `agent-native recap` — the helper surface used by the PR Visual Recap GitHub
+ * Action. Run `agent-native recap help` for the full subcommand list.
  *
  * The action no longer generates the recap deterministically. Instead a coding
  * agent (Claude Code or Codex) RUNS THE REPO'S visual-recap skill against the
  * diff and publishes the plan via the plan MCP tools. These subcommands are the
  * thin, deterministic glue around that:
  *
+ *   gate          The security boundary: decide whether the recap runs at all
+ *                 (skipping drafts, forks, bots, missing secrets, an invalid
+ *                 agent/model, and PRs that touch recap-control files) and which
+ *                 normalized backend agent to use.
+ *   collect-diff  Collect the bounded base...head diff (excluding lockfiles,
+ *                 build output, snapshots), cap it at ~600KB, and classify the
+ *                 huge/tiny flags.
+ *   mcp-config    Write the plan MCP client config for the chosen backend
+ *                 (Claude Code JSON or Codex config.toml).
  *   scan          Refuse to hand a secret-leaking diff to the agent.
- *   build-prompt  Assemble the agent prompt = repo SKILL.md + a task wrapper.
+ *   build-prompt  Assemble the agent prompt = latest visual-recap skill bundle
+ *                 + a task wrapper (or repo-pinned skill with --skill-source).
  *   shot          Screenshot the published plan and upload it to the plan app's
  *                 signed public image route (for an inline PR-comment image).
+ *   usage         Parse and emit agent token-usage/cost from stdout.
  *   comment       Find the previous plan id / upsert the sticky PR comment.
+ *   check         Evaluate the recap result and set a GitHub commit status.
+ *   setup         Install the PR Visual Recap GitHub Action workflow.
+ *   doctor        Diagnose missing secrets / misconfigured workflow.
  *
  * Promoting these to the published CLI means an installed repo's workflow calls
  * `agent-native recap …` instead of copying helper scripts into the repo.
  *
  * Node built-ins only (plus an optional dynamic `playwright` import for `shot`).
  */
+import { execFileSync } from "node:child_process";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
+import { readPlanPublishAuth } from "./plan-publish-store.js";
 import { PR_VISUAL_RECAP_WORKFLOW_YML } from "./pr-visual-recap-workflow.js";
+import { BUILT_IN_APP_SKILLS, VISUAL_RECAP_SKILL_MD } from "./skills.js";
 /* -------------------------------------------------------------------------- */
 /* Arg parsing                                                                */
 /* -------------------------------------------------------------------------- */
@@ -63,6 +81,7 @@ export const PR_VISUAL_RECAP_SETUP = [
     "Optional (only if you change defaults):",
     "  OPENAI_API_KEY (secret) + VISUAL_RECAP_AGENT=codex (variable) — use Codex instead of Claude",
     "  VISUAL_RECAP_MODEL / VISUAL_RECAP_REASONING (variables) — pin the model (e.g. gpt-5.5) and reasoning depth (none|minimal|low|medium|high|xhigh; Codex only)",
+    "  VISUAL_RECAP_SKILL_SOURCE=repo (variable) — pin CI to the repo-local visual-recap skill instead of latest bundled guidance",
     "  PLAN_RECAP_APP_URL (secret) — only when self-hosting the plan app (defaults to https://plan.agent-native.com)",
 ];
 /** Write .github/workflows/pr-visual-recap.yml into a repo. */
@@ -74,6 +93,335 @@ export function writePrVisualRecapWorkflow(baseDir) {
     fs.writeFileSync(file, PR_VISUAL_RECAP_WORKFLOW_YML);
     return { path: path.relative(baseDir, file), existed };
 }
+const DEFAULT_RECAP_APP_URL = "https://plan.agent-native.com";
+export function normalizeRecapAgent(value) {
+    const agent = (value || "claude").toLowerCase();
+    if (agent === "codex")
+        return "codex";
+    if (agent === "claude")
+        return "claude";
+    throw new Error(`Unsupported recap agent "${value}" (expected "claude" or "codex").`);
+}
+export function recapRequiredSecrets(agent) {
+    return [
+        "PLAN_RECAP_TOKEN",
+        agent === "codex" ? "OPENAI_API_KEY" : "ANTHROPIC_API_KEY",
+    ];
+}
+function recapWorkflowFile(baseDir) {
+    return path.join(baseDir, ".github", "workflows", "pr-visual-recap.yml");
+}
+function stripTrailingSlash(url) {
+    return url.replace(/\/+$/, "");
+}
+function sameRecapOrigin(a, b) {
+    try {
+        return new URL(a).origin === new URL(b).origin;
+    }
+    catch {
+        return stripTrailingSlash(a) === stripTrailingSlash(b);
+    }
+}
+function planTokenFromLocalStore(appUrl) {
+    const auth = readPlanPublishAuth();
+    if (!auth)
+        return undefined;
+    return sameRecapOrigin(auth.url, appUrl) ? auth.token : undefined;
+}
+function envValue(env, key) {
+    const value = env[key]?.trim();
+    return value || undefined;
+}
+function commandForMissingSecret(name, repo) {
+    return `gh secret set ${name}${repo ? ` --repo ${repo}` : ""}`;
+}
+function commandForMissingVariable(name, value, repo) {
+    return `gh variable set ${name} --body ${JSON.stringify(value)}${repo ? ` --repo ${repo}` : ""}`;
+}
+function gh(args, input) {
+    try {
+        const stdout = execFileSync("gh", args, {
+            encoding: "utf8",
+            input,
+            stdio: input === undefined
+                ? ["ignore", "pipe", "pipe"]
+                : ["pipe", "pipe", "pipe"],
+        });
+        return { ok: true, stdout };
+    }
+    catch {
+        return { ok: false, stdout: "" };
+    }
+}
+function resolveGithubRepo(explicit) {
+    if (explicit)
+        return explicit;
+    const result = gh([
+        "repo",
+        "view",
+        "--json",
+        "nameWithOwner",
+        "--jq",
+        ".nameWithOwner",
+    ]);
+    const repo = result.stdout.trim();
+    return result.ok && repo ? repo : undefined;
+}
+function listGithubNames(kind, repo) {
+    const args = kind === "secret"
+        ? ["secret", "list", "--json", "name"]
+        : ["variable", "list", "--json", "name,value"];
+    if (repo)
+        args.push("--repo", repo);
+    const result = gh(args);
+    if (!result.ok)
+        return null;
+    try {
+        const parsed = JSON.parse(result.stdout);
+        if (!Array.isArray(parsed))
+            return null;
+        return new Set(parsed
+            .map((entry) => entry && typeof entry === "object"
+            ? entry.name
+            : undefined)
+            .filter((name) => typeof name === "string"));
+    }
+    catch {
+        return null;
+    }
+}
+function listGithubVariables(repo) {
+    const args = ["variable", "list", "--json", "name,value"];
+    if (repo)
+        args.push("--repo", repo);
+    const result = gh(args);
+    if (!result.ok)
+        return null;
+    try {
+        const parsed = JSON.parse(result.stdout);
+        if (!Array.isArray(parsed))
+            return null;
+        const out = new Map();
+        for (const entry of parsed) {
+            if (!entry || typeof entry !== "object")
+                continue;
+            const record = entry;
+            if (typeof record.name !== "string")
+                continue;
+            out.set(record.name, typeof record.value === "string" ? record.value : "");
+        }
+        return out;
+    }
+    catch {
+        return null;
+    }
+}
+function setGithubSecret(name, value, repo, dryRun) {
+    if (!value)
+        return "missing";
+    if (dryRun)
+        return "dry-run";
+    const args = ["secret", "set", name];
+    if (repo)
+        args.push("--repo", repo);
+    return gh(args, `${value}\n`).ok ? "set" : "failed";
+}
+function setGithubVariable(name, value, repo, dryRun) {
+    if (!value)
+        return "skipped";
+    if (dryRun)
+        return "dry-run";
+    const args = ["variable", "set", name, "--body", value];
+    if (repo)
+        args.push("--repo", repo);
+    return gh(args).ok ? "set" : "failed";
+}
+export function buildRecapSetupPlan(input) {
+    const env = input.env ?? process.env;
+    const appUrl = stripTrailingSlash(input.appUrl || env.PLAN_RECAP_APP_URL || DEFAULT_RECAP_APP_URL);
+    const agent = normalizeRecapAgent(input.agent || env.VISUAL_RECAP_AGENT);
+    const requiredSecrets = recapRequiredSecrets(agent);
+    const planToken = envValue(env, "PLAN_RECAP_TOKEN") ?? planTokenFromLocalStore(appUrl);
+    const llmSecretName = agent === "codex" ? "OPENAI_API_KEY" : "ANTHROPIC_API_KEY";
+    const variableValues = {};
+    if (agent !== "claude")
+        variableValues.VISUAL_RECAP_AGENT = agent;
+    for (const key of [
+        "VISUAL_RECAP_MODEL",
+        "VISUAL_RECAP_REASONING",
+        "VISUAL_RECAP_SKILL_SOURCE",
+    ]) {
+        const value = envValue(env, key);
+        if (value)
+            variableValues[key] = value;
+    }
+    return {
+        agent,
+        appUrl,
+        repo: input.repo,
+        workflowPath: path.relative(input.baseDir, recapWorkflowFile(input.baseDir)),
+        workflowExists: fs.existsSync(recapWorkflowFile(input.baseDir)),
+        requiredSecrets,
+        variableValues,
+        secretValues: {
+            PLAN_RECAP_TOKEN: planToken,
+            [llmSecretName]: envValue(env, llmSecretName),
+            PLAN_RECAP_APP_URL: appUrl === DEFAULT_RECAP_APP_URL ? undefined : appUrl,
+        },
+    };
+}
+function flagArg(args, key) {
+    return args[key] === true || args[key] === "true";
+}
+function runSetup(args) {
+    const baseDir = process.cwd();
+    const dryRun = flagArg(args, "dry-run");
+    const skipSecrets = flagArg(args, "skip-secrets");
+    const repo = resolveGithubRepo(optionalArg(args, "repo"));
+    const plan = buildRecapSetupPlan({
+        baseDir,
+        appUrl: optionalArg(args, "app-url"),
+        agent: optionalArg(args, "agent"),
+        repo,
+    });
+    const lines = ["PR Visual Recap setup", ""];
+    if (dryRun) {
+        lines.push(`Workflow: would write ${plan.workflowPath}.`);
+    }
+    else {
+        const written = writePrVisualRecapWorkflow(baseDir);
+        lines.push(`Workflow: ${written.existed ? "refreshed" : "wrote"} ${written.path}.`);
+    }
+    lines.push(`Plan app: ${plan.appUrl}.`);
+    lines.push(`Backend: ${plan.agent}.`);
+    lines.push(repo
+        ? `GitHub repo: ${repo}.`
+        : "GitHub repo: not detected; pass --repo owner/name or run from a GitHub checkout.");
+    if (skipSecrets) {
+        lines.push("");
+        lines.push("GitHub secrets/variables: skipped.");
+    }
+    else {
+        lines.push("");
+        lines.push("GitHub secrets/variables:");
+        const secretNames = [
+            ...plan.requiredSecrets,
+            ...(plan.secretValues.PLAN_RECAP_APP_URL ? ["PLAN_RECAP_APP_URL"] : []),
+        ];
+        for (const name of secretNames) {
+            const status = setGithubSecret(name, plan.secretValues[name], repo, dryRun);
+            if (status === "set") {
+                lines.push(`  ${name}: set.`);
+            }
+            else if (status === "dry-run") {
+                lines.push(`  ${name}: would set.`);
+            }
+            else if (status === "missing") {
+                lines.push(`  ${name}: missing value.`);
+                if (name === "PLAN_RECAP_TOKEN") {
+                    lines.push(`    Run agent-native connect ${plan.appUrl} --client codex, then rerun this setup.`);
+                }
+                lines.push(`    Or set manually: ${commandForMissingSecret(name, repo)}`);
+            }
+            else {
+                lines.push(`  ${name}: could not set with gh.`);
+                lines.push(`    Set manually: ${commandForMissingSecret(name, repo)}`);
+            }
+        }
+        for (const [name, value] of Object.entries(plan.variableValues)) {
+            const status = setGithubVariable(name, value, repo, dryRun);
+            if (status === "set") {
+                lines.push(`  ${name}: set to ${value}.`);
+            }
+            else if (status === "dry-run") {
+                lines.push(`  ${name}: would set to ${value}.`);
+            }
+            else if (status === "failed") {
+                lines.push(`  ${name}: could not set with gh.`);
+                lines.push(`    Set manually: ${commandForMissingVariable(name, value, repo)}`);
+            }
+        }
+    }
+    lines.push("");
+    lines.push(`Next: commit ${plan.workflowPath}, then run agent-native recap doctor.`);
+    process.stdout.write(`${lines.join("\n")}\n`);
+}
+function runDoctor(args) {
+    const baseDir = process.cwd();
+    const repo = resolveGithubRepo(optionalArg(args, "repo"));
+    const variables = listGithubVariables(repo);
+    const agent = normalizeRecapAgent(optionalArg(args, "agent") ??
+        variables?.get("VISUAL_RECAP_AGENT") ??
+        process.env.VISUAL_RECAP_AGENT);
+    const plan = buildRecapSetupPlan({
+        baseDir,
+        appUrl: optionalArg(args, "app-url"),
+        agent,
+        repo,
+    });
+    const lines = ["PR Visual Recap doctor", ""];
+    let ok = true;
+    const workflowFile = recapWorkflowFile(baseDir);
+    if (!fs.existsSync(workflowFile)) {
+        ok = false;
+        lines.push(`[missing] Workflow missing: ${plan.workflowPath}.`);
+        lines.push("  Run agent-native skills add visual-plan --with-github-action.");
+    }
+    else {
+        const current = fs.readFileSync(workflowFile, "utf-8");
+        if (current === PR_VISUAL_RECAP_WORKFLOW_YML) {
+            lines.push(`[ok] Workflow installed: ${plan.workflowPath}.`);
+        }
+        else {
+            ok = false;
+            lines.push(`[missing] Workflow differs from the bundled template: ${plan.workflowPath}.`);
+            lines.push("  Run agent-native recap setup to refresh it.");
+        }
+    }
+    if (plan.secretValues.PLAN_RECAP_TOKEN) {
+        lines.push("[ok] Local Plans publish token found.");
+    }
+    else {
+        lines.push("[warn] Local Plans publish token not found.");
+        lines.push(`  Run agent-native connect ${plan.appUrl} --client codex to mint one.`);
+    }
+    if (repo) {
+        lines.push(`[ok] GitHub repo detected: ${repo}.`);
+    }
+    else {
+        ok = false;
+        lines.push("[missing] GitHub repo not detected.");
+        lines.push("  Pass --repo owner/name or run from a GitHub checkout with gh auth.");
+    }
+    const secretNames = listGithubNames("secret", repo);
+    if (!secretNames) {
+        ok = false;
+        lines.push("[missing] Could not read GitHub Actions secrets with gh.");
+        lines.push("  Run gh auth status, or pass --repo owner/name.");
+    }
+    else {
+        for (const name of plan.requiredSecrets) {
+            if (secretNames.has(name)) {
+                lines.push(`[ok] GitHub secret configured: ${name}.`);
+            }
+            else {
+                ok = false;
+                lines.push(`[missing] GitHub secret missing: ${name}.`);
+                lines.push(`  Set it with: ${commandForMissingSecret(name, repo)}`);
+            }
+        }
+    }
+    if (!variables) {
+        lines.push("[warn] Could not read GitHub Actions variables with gh.");
+    }
+    else {
+        const configuredAgent = variables.get("VISUAL_RECAP_AGENT") || "claude";
+        lines.push(`[ok] Recap backend variable: ${configuredAgent}.`);
+    }
+    process.stdout.write(`${lines.join("\n")}\n`);
+    if (!ok)
+        process.exitCode = 1;
+}
 /* -------------------------------------------------------------------------- */
 /* Secret scan — defense-in-depth before any LLM sees the diff                */
 /* -------------------------------------------------------------------------- */
@@ -116,6 +464,277 @@ export function diffContainsSecret(diffText) {
     return false;
 }
 /* -------------------------------------------------------------------------- */
+/* Bounded diff collection — was the workflow's "Collect bounded diff" step    */
+/* -------------------------------------------------------------------------- */
+/** ~600KB byte cap for the diff handed to the recap agent. */
+export const RECAP_DIFF_BYTE_CAP = 614400;
+/** The footer appended when a diff is truncated at the byte cap. */
+export const RECAP_DIFF_TRUNCATED_FOOTER = "\n\n[diff truncated at 600KB for the recap agent]\n";
+/**
+ * The pathspecs the bounded diff excludes — lockfiles, build output, and
+ * snapshots are noise for a visual recap. Kept as array args (not a shell
+ * string) so the `:(exclude)` pathspecs are never mangled by a shell.
+ */
+const RECAP_DIFF_PATHSPECS = [
+    ".",
+    ":(exclude)pnpm-lock.yaml",
+    ":(exclude)**/dist/**",
+    ":(exclude)**/*.snap",
+    ":(exclude)**/*.lock",
+];
+/**
+ * Classify a bounded diff into the `huge` / `tiny` flags the workflow consumes.
+ *
+ * - huge: BYTES over the ~600KB cap. The agent is told to summarize AND the
+ *   diff file is physically truncated so it can't overflow the prompt budget.
+ * - tiny: <= 1 changed file AND <= 8 changed lines. Uses ORIGINAL line count
+ *   (captured before any truncation) so a large diff is never misclassified as
+ *   tiny after the byte cap drops most of its lines.
+ *
+ * Pure (no I/O) so the classification can be unit-tested without invoking git.
+ */
+export function classifyDiff(input) {
+    return {
+        huge: input.bytes > RECAP_DIFF_BYTE_CAP,
+        tiny: input.changed <= 1 && input.originalLines <= 8,
+    };
+}
+/**
+ * Truncate a diff to the ~600KB byte cap at a COMPLETE LINE boundary, then
+ * append the truncated footer. Dropping the last (possibly-partial) line is the
+ * equivalent of the original `head -c 614400 | sed '$d'`: it guarantees the cap
+ * never cuts a multi-byte UTF-8 char or a diff line mid-way and corrupts the
+ * agent's input. Pure (string in, string out) so it can be unit-tested.
+ */
+export function truncateDiffAtLineBoundary(text) {
+    const capped = Buffer.from(text, "utf8")
+        .subarray(0, RECAP_DIFF_BYTE_CAP)
+        .toString("utf8");
+    const lastNewline = capped.lastIndexOf("\n");
+    // Drop everything after the last newline (the last, possibly-partial line),
+    // mirroring `sed '$d'`. If there is no newline at all, drop the whole partial
+    // line (empty body) — the footer still makes the truncation explicit.
+    const body = lastNewline >= 0 ? capped.slice(0, lastNewline) : "";
+    return body + RECAP_DIFF_TRUNCATED_FOOTER;
+}
+/**
+ * Count lines that begin with `+` or `-` (added/removed diff lines), excluding
+ * the `+++ b/file` / `--- a/file` unified-diff header lines. Without this
+ * exclusion a single-file change loses ~2 "real" lines from the 8-line tiny
+ * threshold, incorrectly classifying a small-but-meaningful change as tiny.
+ */
+export function countDiffLines(diffText) {
+    let count = 0;
+    for (const line of diffText.split("\n")) {
+        if (line.startsWith("+++") || line.startsWith("---"))
+            continue;
+        if (line.startsWith("+") || line.startsWith("-"))
+            count += 1;
+    }
+    return count;
+}
+/**
+ * Run `git diff <base>...<head> -- <pathspecs>` and return its stdout plus a
+ * `failed` flag. A non-zero exit that still produces stdout is treated as a
+ * partial result (same as the original `... || true`). A non-zero exit with
+ * empty stdout is a genuine failure (broken ref, missing object, etc.) and
+ * sets `failed: true` so `runCollectDiff` can exit with a distinct error
+ * instead of silently classifying the empty output as a tiny diff.
+ *
+ * Array args — NOT a shell string — so the `:(exclude)` pathspecs survive.
+ */
+function gitDiffRaw(base, head, extraArgs) {
+    const args = [
+        "diff",
+        "--no-color",
+        ...extraArgs,
+        `${base}...${head}`,
+        "--",
+        ...RECAP_DIFF_PATHSPECS,
+    ];
+    try {
+        const stdout = execFileSync("git", args, {
+            encoding: "utf8",
+            maxBuffer: 256 * 1024 * 1024,
+        });
+        return { stdout, failed: false };
+    }
+    catch (err) {
+        // Recover whatever stdout git wrote before failing.
+        const raw = err && typeof err.stdout === "string"
+            ? err.stdout
+            : err && Buffer.isBuffer(err.stdout)
+                ? err.stdout.toString("utf8")
+                : "";
+        // An empty stdout from a non-zero exit means a broken ref / missing
+        // object — not a legitimate empty diff. Signal failure.
+        return { stdout: raw, failed: raw.trim() === "" };
+    }
+}
+/**
+ * `recap collect-diff` — the bounded-diff collection that used to be ~60 lines
+ * of inline bash. Writes recap.diff + recap.stat, classifies huge/tiny, and
+ * emits the same `bytes/changed/huge/tiny` outputs the workflow expects:
+ * appended to $GITHUB_OUTPUT when set, AND printed as JSON to stdout (so it runs
+ * and is testable outside GitHub Actions).
+ *
+ * Exits non-zero when git itself fails (broken SHA / missing object) so the
+ * CI workflow treats it as a real failure instead of silently classifying an
+ * empty diff as "tiny" and skipping the recap with no diagnostic.
+ */
+function runCollectDiff(args) {
+    const base = stringArg(args, "base");
+    const head = stringArg(args, "head");
+    const outPath = optionalArg(args, "out") ?? "recap.diff";
+    const statPath = optionalArg(args, "stat") ?? "recap.stat";
+    // The unified diff and the --stat summary (both excluding lockfiles/noise).
+    const diffResult = gitDiffRaw(base, head, []);
+    if (diffResult.failed) {
+        process.stderr.write(`recap collect-diff: git diff failed for ${base}...${head} — ` +
+            `the SHAs may be missing (shallow clone?) or invalid.\n` +
+            `Make sure the workflow checks out with fetch-depth: 0 or at least ` +
+            `enough history to resolve both refs.\n`);
+        process.exit(1);
+    }
+    let diff = diffResult.stdout;
+    const stat = gitDiffRaw(base, head, ["--stat"]).stdout;
+    fs.writeFileSync(path.resolve(statPath), stat);
+    // ORIGINAL line count — captured BEFORE any byte-cap truncation so a large
+    // diff is never misclassified as tiny after truncation.
+    const originalLines = countDiffLines(diff);
+    // Changed-file count from `--name-only` over the same excludes.
+    const names = gitDiffRaw(base, head, ["--name-only"]).stdout;
+    const changed = names.split("\n").filter((line) => line.length > 0).length;
+    // Write the (possibly truncated) diff and compute the on-disk byte length.
+    const bytesBefore = Buffer.byteLength(diff, "utf8");
+    const { huge } = classifyDiff({ bytes: bytesBefore, changed, originalLines });
+    if (huge)
+        diff = truncateDiffAtLineBoundary(diff);
+    fs.writeFileSync(path.resolve(outPath), diff);
+    const bytes = fs.statSync(path.resolve(outPath)).size;
+    const { tiny } = classifyDiff({ bytes: bytesBefore, changed, originalLines });
+    // Preserve the existing steps.diff.outputs.{bytes,changed,huge,tiny} contract.
+    const githubOutput = process.env.GITHUB_OUTPUT;
+    if (githubOutput) {
+        fs.appendFileSync(githubOutput, `bytes=${bytes}\nchanged=${changed}\nhuge=${huge}\ntiny=${tiny}\n`);
+    }
+    process.stdout.write(`${JSON.stringify({ bytes, changed, huge, tiny })}\n`);
+}
+/* -------------------------------------------------------------------------- */
+/* MCP config writers — were the two `node -e` one-liners in the agent steps   */
+/* -------------------------------------------------------------------------- */
+/**
+ * The Claude Code MCP config the recap agent loads: a single HTTP `plan` server
+ * pointing at the app's `/_agent-native/mcp` endpoint, authorized with the
+ * PLAN_RECAP_TOKEN. Pure (returns the JSON string) so it can be unit-tested.
+ */
+export function buildRecapClaudeMcpConfig(appUrl, token) {
+    const url = appUrl.replace(/\/$/, "") + "/_agent-native/mcp";
+    return JSON.stringify({
+        mcpServers: {
+            plan: {
+                type: "http",
+                url,
+                headers: { Authorization: "Bearer " + token },
+            },
+        },
+    });
+}
+/**
+ * The Codex `config.toml` the recap agent loads. JSON.stringify the URL value so
+ * a stray quote/newline in the app URL can't break out of the TOML basic string
+ * (TOML shares JSON's escaping); the key and env-var name stay literal. Pure so
+ * it can be unit-tested.
+ */
+export function buildRecapCodexMcpConfig(appUrl) {
+    const url = appUrl.replace(/\/$/, "") + "/_agent-native/mcp";
+    return ("[mcp_servers.plan]\n" +
+        "url = " +
+        JSON.stringify(url) +
+        "\n" +
+        'bearer_token_env_var = "PLAN_RECAP_TOKEN"\n');
+}
+/**
+ * `recap mcp-config` — write the plan MCP client config for the chosen backend,
+ * replacing the two `node -e '...'` one-liners that previously lived inline in
+ * the agent steps. PLAN_RECAP_TOKEN is read from the environment (claude only),
+ * exactly as before.
+ */
+function runMcpConfig(args) {
+    const agent = stringArg(args, "agent").toLowerCase();
+    const appUrl = stringArg(args, "app-url");
+    const force = Boolean(args["force"]);
+    if (agent === "claude") {
+        const token = process.env.PLAN_RECAP_TOKEN;
+        if (!token) {
+            process.stderr.write(`recap mcp-config: PLAN_RECAP_TOKEN is not set.\n` +
+                `Set it in the workflow environment before running this step.\n`);
+            process.exit(1);
+        }
+        const out = stringArg(args, "out");
+        fs.writeFileSync(path.resolve(out), buildRecapClaudeMcpConfig(appUrl, token));
+        process.stdout.write(`${JSON.stringify({ ok: true, agent, out })}\n`);
+        return;
+    }
+    if (agent === "codex") {
+        const out = optionalArg(args, "out") ??
+            path.join(os.homedir(), ".codex", "config.toml");
+        const absOut = path.resolve(out);
+        fs.mkdirSync(path.dirname(absOut), { recursive: true });
+        const newEntry = buildRecapCodexMcpConfig(appUrl);
+        const SECTION_MARKER = "[mcp_servers.plan]";
+        // If the file already exists and is non-empty, merge rather than overwrite.
+        let existing = "";
+        try {
+            const raw = fs.readFileSync(absOut, "utf8");
+            if (raw.trim())
+                existing = raw;
+        }
+        catch {
+            /* file absent — write fresh */
+        }
+        if (existing) {
+            if (existing.includes(SECTION_MARKER)) {
+                // Section already present — skip unless --force was passed.
+                if (!force) {
+                    process.stdout.write(`${JSON.stringify({ ok: true, agent, out, skipped: true, reason: "plan entry already present; pass --force to overwrite" })}\n`);
+                    return;
+                }
+                // --force: replace the existing [mcp_servers.plan] block.
+                // Remove lines from the section header until the next `[` header or EOF.
+                const lines = existing.split("\n");
+                const startIdx = lines.findIndex((l) => l.trim() === SECTION_MARKER);
+                let endIdx = lines.length;
+                for (let i = startIdx + 1; i < lines.length; i++) {
+                    if (lines[i].trimStart().startsWith("[")) {
+                        endIdx = i;
+                        break;
+                    }
+                }
+                const without = [
+                    ...lines.slice(0, startIdx),
+                    ...lines.slice(endIdx),
+                ].join("\n");
+                const merged = (without.trimEnd() ? without.trimEnd() + "\n\n" : "") + newEntry;
+                fs.writeFileSync(absOut, merged, { mode: 0o600 });
+            }
+            else {
+                // Append the new section to the existing config.
+                const separator = existing.endsWith("\n") ? "\n" : "\n\n";
+                fs.writeFileSync(absOut, existing + separator + newEntry, {
+                    mode: 0o600,
+                });
+            }
+        }
+        else {
+            fs.writeFileSync(absOut, newEntry);
+        }
+        process.stdout.write(`${JSON.stringify({ ok: true, agent, out })}\n`);
+        return;
+    }
+    throw new Error(`Unknown --agent "${agent}" (expected "claude" or "codex")`);
+}
+/* -------------------------------------------------------------------------- */
 /* Prompt builder — repo SKILL.md + task wrapper                              */
 /* -------------------------------------------------------------------------- */
 /**
@@ -138,15 +757,80 @@ export function readRepoSkillMd(cwd = process.cwd()) {
     }
     throw new Error("Could not find visual-recap/SKILL.md. Run `agent-native skills add visual-plan` first.");
 }
+function listRecapSkillReferenceFiles(skillDir) {
+    const out = {};
+    const walk = (current, prefix = "") => {
+        for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+            const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+            const abs = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                walk(abs, rel);
+                continue;
+            }
+            if (!entry.isFile() || rel === "SKILL.md")
+                continue;
+            if (rel === "agent-native-skill.json")
+                continue;
+            out[rel] = fs.readFileSync(abs, "utf8");
+        }
+    };
+    if (fs.existsSync(skillDir))
+        walk(skillDir);
+    return out;
+}
+function recapSkillBundleText(skillMd, referenceFiles) {
+    const refs = Object.keys(referenceFiles).sort();
+    if (refs.length === 0)
+        return skillMd;
+    const lines = [skillMd.trim(), "", "# Bundled visual-recap reference files"];
+    lines.push("These files live next to visual-recap/SKILL.md in a normal install. Treat them as part of the skill instructions.");
+    for (const rel of refs) {
+        lines.push("", `## ${rel}`, "", referenceFiles[rel].trim());
+    }
+    return lines.join("\n");
+}
+function readRepoSkillBundle(cwd = process.cwd()) {
+    const skill = readRepoSkillMd(cwd);
+    const skillDir = path.dirname(path.resolve(cwd, skill.source));
+    return {
+        text: recapSkillBundleText(skill.text, listRecapSkillReferenceFiles(skillDir)),
+        source: skill.source,
+    };
+}
+function latestVisualRecapSkillBundle() {
+    const planSkill = BUILT_IN_APP_SKILLS["visual-plans"];
+    const references = "extraFiles" in planSkill
+        ? (planSkill.extraFiles?.["visual-recap"] ?? {})
+        : {};
+    return {
+        text: recapSkillBundleText(VISUAL_RECAP_SKILL_MD, references),
+        source: "bundled:@agent-native/core/visual-recap",
+    };
+}
+export function readVisualRecapSkillBundle(cwd = process.cwd(), mode = "auto") {
+    if (mode === "latest" || mode === "auto") {
+        return latestVisualRecapSkillBundle();
+    }
+    return readRepoSkillBundle(cwd);
+}
 export function buildRecapPrompt(input) {
     const appUrl = input.appUrl.replace(/\/$/, "");
+    const localDir = input.localDir ?? path.join("plans", `pr-${input.pr}-visual-recap`);
     const lines = [];
-    lines.push("# Task: publish a Visual Recap of this pull request");
+    lines.push(input.localFiles
+        ? "# Task: create a DB-free local Visual Recap of this pull request"
+        : "# Task: publish a Visual Recap of this pull request");
     lines.push("");
-    lines.push(`You are running non-interactively in CI. Follow the **visual-recap skill** included verbatim below to turn this PR's diff into a grounded Agent-Native Plan, then publish it.`);
+    lines.push(input.localFiles
+        ? `You are running non-interactively in local-files privacy mode. Follow the **visual-recap skill** included verbatim below to turn this PR's diff into a grounded Agent-Native Plan MDX folder, but do not publish it or call any Plan MCP/action write tool.`
+        : `You are running non-interactively in CI. Follow the **visual-recap skill** included verbatim below to turn this PR's diff into a grounded Agent-Native Plan, then publish it.`);
     lines.push("");
     lines.push("## Inputs (read them from disk with your Read tool)");
     lines.push(`- PR number: **#${input.pr}**`);
+    if (input.repo) {
+        lines.push(`- Repository: **${input.repo}**`);
+        lines.push(`- Pull request URL: https://github.com/${input.repo}/pull/${input.pr}`);
+    }
     if (input.head)
         lines.push(`- Head commit: \`${input.head}\``);
     lines.push(`- Unified diff: \`${input.diffPath}\` (read this file)`);
@@ -156,16 +840,30 @@ export function buildRecapPrompt(input) {
         lines.push(`- The diff is LARGE — produce a **summarized** recap (top files + schema/API deltas), not an exhaustive one.`);
     }
     lines.push("");
-    lines.push("## Publish (this is the only way to produce output)");
-    lines.push(`The \`plan\` MCP server is configured for you. Call its tools by name (your host may expose them as \`create-visual-recap\` or \`mcp__plan__create-visual-recap\` — same tool).`);
-    lines.push(`1. Call the **create-visual-recap** tool on the \`plan\` MCP server with grounded MDX derived ONLY from the real diff${input.prevPlanId
-        ? `, passing \`planId: "${input.prevPlanId}"\` so this REPLACES the existing recap plan`
-        : ""}.`);
-    lines.push(`2. Call the **set-resource-visibility** tool on the \`plan\` MCP server with \`{ resourceType: "plan", resourceId: <the returned plan id>, visibility: "org" }\` so the recap is login-gated to the org, never public.`);
-    lines.push(`3. Write the plan URL to a file named \`recap-url.txt\` at the repo root, containing exactly one line: \`${appUrl}/recaps/<the returned plan id>\`. This file is the workflow's only hand-off — do not print anything else as the deliverable.`);
+    if (input.localFiles) {
+        lines.push("## Local-Files Output (this is the only way to produce output)");
+        lines.push("Do NOT call the `plan` MCP server, `create-visual-recap`, `import-visual-plan-source`, `update-visual-plan`, `export-visual-plan`, or any hosted Plan action. This mode exists so the recap data never goes to a Plan app database.");
+        lines.push(`1. Create or replace the local MDX folder \`${localDir}\` with \`plan.mdx\` and optional \`canvas.mdx\`, \`prototype.mdx\`, and \`.plan-state.json\` derived ONLY from the real diff. Set \`kind: "recap"\` and \`localOnly: true\` in source metadata/state.`);
+        lines.push(`2. Run \`agent-native plan local preview --dir ${JSON.stringify(localDir)} --kind recap --out ${JSON.stringify(path.join(localDir, "preview.html"))}\` to validate the folder and generate the local preview.`);
+        lines.push("3. Write the returned `url` from that command to `recap-url.txt` at the repo root, containing exactly one line. This file is the workflow's only hand-off.");
+    }
+    else {
+        lines.push("## Publish (this is the only way to produce output)");
+        lines.push(`The \`plan\` MCP server is configured for you. Call its tools by name (your host may expose them as \`get-plan-blocks\` / \`create-visual-recap\` or \`mcp__plan__get-plan-blocks\` / \`mcp__plan__create-visual-recap\` — same tools).`);
+        lines.push("First call `get-plan-blocks`, then call `create-visual-recap`. If `create-visual-recap` is available but `get-plan-blocks` is not, the Plan MCP is connected but the workflow/tool allowlist is stale. Report that `.github/workflows/pr-visual-recap.yml` must allow `mcp__plan__get-plan-blocks`; do not describe that case as a disconnected Plan MCP.");
+        lines.push(`1. Call the **create-visual-recap** tool on the \`plan\` MCP server with grounded MDX derived ONLY from the real diff, passing \`visibility: "org"\` so the recap is published org-scoped (never public) server-side${input.prevPlanId
+            ? `, and also passing \`planId: "${input.prevPlanId}"\` so this REPLACES the existing recap plan`
+            : ""}.`);
+        lines.push(`2. Write the plan URL to a file named \`recap-url.txt\` at the repo root, containing exactly one line: \`${appUrl}/recaps/<the returned plan id>\`. This file is the workflow's only hand-off — do not print anything else as the deliverable.`);
+        lines.push(`3. (Fallback only — skip if step 1 succeeded) If \`create-visual-recap\` does not accept a \`visibility\` parameter (older server), call the **set-resource-visibility** tool with \`{ resourceType: "plan", resourceId: <the returned plan id>, visibility: "org" }\` after publishing.`);
+    }
     lines.push("");
     lines.push("Do not invent file names, schema fields, or endpoints. Redact anything that looks like a secret. If the diff has no reviewable substance, still publish a minimal recap and write recap-url.txt.");
     lines.push("");
+    lines.push("## Depth preflight");
+    lines.push("Before authoring the recap, read the diff/stat and make a quick private inventory of changed files, routes/actions, rendered UI surfaces, popovers/dialogs, role/access states, empty/error states, and shared abstractions. The published recap must cover each meaningful item with a structured block or intentionally omit it because it is tiny, redundant, or not user-visible.");
+    lines.push("For UI PRs, do not stop at one before/after. Show the entry point, the changed interaction surface, and the resulting/destination state; add role/access or empty/error states when the diff implements them. Then include the key file-tree and key-change diff tabs.");
+    lines.push("");
     lines.push("---");
     lines.push("");
     lines.push("# visual-recap skill (follow this exactly)");
@@ -178,6 +876,7 @@ export function buildRecapPrompt(input) {
 /* GitHub comment helpers                                                     */
 /* -------------------------------------------------------------------------- */
 const MARKER = "<!-- pr-visual-recap -->";
+const RECAP_IMAGE_URL_PATH_PATTERN = /\/_agent-native\/recap-image\/[0-9a-f]{32,128}\.png$/;
 function repoParts(repoFullName) {
     const [owner, repo] = repoFullName.split("/");
     if (!owner || !repo)
@@ -265,8 +964,15 @@ function originOf(url) {
 }
 /** Build the sticky comment body from the workflow's environment. */
 export function buildCommentBody(env = process.env) {
-    const headShort = (env.HEAD_SHA || "").slice(0, 7);
     const lines = [MARKER];
+    // Short head SHA for the "as of" freshness line.
+    const headSha = (env.HEAD_SHA || "").trim();
+    const headShort = headSha ? headSha.slice(0, 7) : "";
+    // Last-known plan id threaded from the previous run (supplied via PREV_PLAN_ID
+    // when the comment is rebuilt from scratch, or parsed from the env on upsert).
+    // We always emit the plan-id marker when any plan id is known so that a
+    // transient failure does not orphan the plan.
+    const prevPlanId = (env.PREV_PLAN_ID || "").trim() || null;
     if (env.SUPPRESSED === "true") {
         let reason = "potential secret in diff";
         try {
@@ -281,7 +987,11 @@ export function buildCommentBody(env = process.env) {
         lines.push("");
         lines.push("The recap was **suppressed** because the diff matched a secret/credential pattern. No plan was published.");
         lines.push("");
-        lines.push(`Reason: \`${reason}\`. Updated for \`${headShort}\`.`);
+        lines.push(`Reason: \`${reason}\`.`);
+        if (headShort)
+            lines.push("", `_As of \`${headShort}\`_`);
+        if (prevPlanId)
+            lines.push("", `<!-- plan-id: ${prevPlanId} -->`);
         return lines.join("\n");
     }
     // Tiny diffs aren't worth a recap. Refresh an existing sticky comment to this
@@ -291,8 +1001,10 @@ export function buildCommentBody(env = process.env) {
         lines.push("### Visual recap — skipped (diff too small)");
         lines.push("");
         lines.push("The change in this push is too small to be worth a visual recap. This is informational only and does **not** block the PR.");
-        lines.push("");
-        lines.push(`Updated for \`${headShort}\`.`);
+        if (headShort)
+            lines.push("", `_As of \`${headShort}\`_`);
+        if (prevPlanId)
+            lines.push("", `<!-- plan-id: ${prevPlanId} -->`);
         return lines.join("\n");
     }
     const planUrl = (env.PLAN_URL || "").trim();
@@ -307,12 +1019,25 @@ export function buildCommentBody(env = process.env) {
     const sameOriginOk = appUrl === "" || sameOrigin(planUrl, appUrl);
     const base = (appUrl || originOf(planUrl)).replace(/\/$/, "");
     const safeUrl = planId && base && sameOriginOk ? `${base}/recaps/${planId}` : "";
+    // The plan id to embed in the marker — prefer the freshly-published one when
+    // the origin is trusted, fall back to the previous run's id so the next push
+    // can still replace in-place. Never use a plan id extracted from a bad-origin
+    // URL as the marker (it would mask the last-good known id).
+    const trustedPlanId = planId && sameOriginOk ? planId : null;
+    const markerPlanId = trustedPlanId ?? prevPlanId;
     if (!safeUrl) {
         lines.push("### Visual recap — generation failed");
         lines.push("");
         lines.push("The visual recap could not be generated for this push. This is informational only and does **not** block the PR.");
-        lines.push("");
-        lines.push(`Updated for \`${headShort}\`.`);
+        if (headShort)
+            lines.push("", `_As of \`${headShort}\`_`);
+        // Keep a link to the last-good recap so reviewers are not left in the dark.
+        if (prevPlanId && base) {
+            const prevSafeUrl = `${base}/recaps/${prevPlanId}`;
+            lines.push("", `Previous recap (from an earlier push): [Open recap](${prevSafeUrl})`);
+        }
+        if (markerPlanId)
+            lines.push("", `<!-- plan-id: ${markerPlanId} -->`);
         return lines.join("\n");
     }
     // The image URL is produced by our own recap-image route, but validate it is
@@ -321,10 +1046,10 @@ export function buildCommentBody(env = process.env) {
     const imageUrlRaw = (env.RECAP_IMAGE_URL || "").trim();
     const imageUrl = imageUrlRaw &&
         sameOrigin(imageUrlRaw, base) &&
-        /\/_agent-native\/recap-image\/[0-9a-f]+\.png$/.test(imageUrlRaw)
+        RECAP_IMAGE_URL_PATH_PATTERN.test(imageUrlRaw)
         ? imageUrlRaw
         : "";
-    lines.push("### Visual recap — review at a higher altitude");
+    lines.push("### Visual recap");
     lines.push("");
     if (imageUrl) {
         lines.push(`[![Visual recap](${imageUrl})](${safeUrl})`);
@@ -335,10 +1060,9 @@ export function buildCommentBody(env = process.env) {
         lines.push("");
         lines.push("> Large diff — this recap is a **summarized** view (top files + schema/API deltas).");
     }
-    lines.push("");
-    lines.push(`Updated for \`${headShort}\`.`);
-    lines.push("");
-    lines.push(`<!-- plan-id: ${planId} -->`);
+    if (headShort)
+        lines.push("", `_As of \`${headShort}\`_`);
+    lines.push("", `<!-- plan-id: ${planId} -->`);
     return lines.join("\n");
 }
 /* -------------------------------------------------------------------------- */
@@ -355,21 +1079,75 @@ function runScan(args) {
     }
 }
 function runBuildPrompt(args) {
-    const skill = readRepoSkillMd();
+    const skillSource = optionalArg(args, "skill-source") ??
+        process.env.VISUAL_RECAP_SKILL_SOURCE ??
+        "auto";
+    if (skillSource !== "auto" &&
+        skillSource !== "latest" &&
+        skillSource !== "repo") {
+        throw new Error("--skill-source must be auto, latest, or repo.");
+    }
+    const skill = readVisualRecapSkillBundle(process.cwd(), skillSource);
     const prompt = buildRecapPrompt({
         skillMd: skill.text,
         pr: stringArg(args, "pr"),
+        repo: optionalArg(args, "repo") ?? process.env.GITHUB_REPOSITORY,
         head: optionalArg(args, "head"),
         appUrl: optionalArg(args, "app-url") ?? "https://plan.agent-native.com",
         diffPath: optionalArg(args, "diff") ?? "recap.diff",
         statPath: optionalArg(args, "stat"),
         prevPlanId: optionalArg(args, "prev-plan-id"),
         huge: args.huge === true || args.huge === "true",
+        localFiles: args["local-files"] === true || args["local-files"] === "true",
+        localDir: optionalArg(args, "local-dir"),
     });
     const out = optionalArg(args, "out") ?? "recap-prompt.md";
     fs.writeFileSync(path.resolve(out), prompt);
     process.stdout.write(`${JSON.stringify({ ok: true, out, skillSource: skill.source, bytes: prompt.length })}\n`);
 }
+function delay(ms) {
+    return ms > 0
+        ? new Promise((resolve) => setTimeout(resolve, ms))
+        : Promise.resolve();
+}
+/**
+ * Confirm GitHub can fetch the uploaded image anonymously before we embed it.
+ *
+ * Default budget: 8 attempts with capped exponential backoff (1s, 2s, 3s, …
+ * capped at 4s) → ~20s total. This is enough to survive a cold-start CDN
+ * propagation delay that would otherwise cause `uploadRecapImage` to return a
+ * URL that the GitHub PR comment can't display.
+ *
+ * The `attempts` and `delayMs` overrides remain for unit tests and for callers
+ * that need a tighter or looser budget.
+ */
+export async function waitForPublicRecapImage(input) {
+    const attempts = Math.max(1, input.attempts ?? 8);
+    const delayMs = Math.max(0, input.delayMs ?? 1000);
+    const fetchFn = input.fetchFn ?? fetch;
+    const MAX_DELAY_MS = 4000;
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+        try {
+            const res = await fetchFn(input.imageUrl, {
+                method: "GET",
+                headers: { accept: "image/png" },
+                redirect: "follow",
+            });
+            const contentType = res.headers.get("content-type")?.toLowerCase() ?? "";
+            if (res.ok && contentType.split(";")[0]?.trim() === "image/png") {
+                const bytes = await res.arrayBuffer().catch(() => new ArrayBuffer(0));
+                if (bytes.byteLength > 0)
+                    return true;
+            }
+        }
+        catch {
+            /* retry below */
+        }
+        if (attempt < attempts)
+            await delay(Math.min(delayMs * attempt, MAX_DELAY_MS));
+    }
+    return false;
+}
 /** Upload a PNG to the plan app's signed public image route; returns its URL. */
 async function uploadRecapImage(input) {
     try {
@@ -396,6 +1174,13 @@ async function uploadRecapImage(input) {
             process.stderr.write(`[recap shot] image upload returned no imageUrl (status ${res.status})\n`);
             return null;
         }
+        const publiclyReadable = await waitForPublicRecapImage({
+            imageUrl: json.imageUrl,
+        });
+        if (!publiclyReadable) {
+            process.stderr.write(`[recap shot] uploaded image was not publicly readable as image/png: ${json.imageUrl}\n`);
+            return null;
+        }
         return json.imageUrl;
     }
     catch (err) {
@@ -501,7 +1286,7 @@ async function runShot(args) {
         // Zoom out slightly so more content fits. Keep the plan title (h1) in frame:
         // the recap reads better led by its own title than cropped to the body.
         await page.evaluate(() => {
-            document.documentElement.style.zoom = "80%";
+            document.documentElement.style.zoom = "90%";
         });
         await page.screenshot({ path: out });
         captured = true;
@@ -554,6 +1339,408 @@ async function runComment(args, sub) {
     }
     throw new Error("Usage: agent-native recap comment <find-plan-id|upsert> --repo owner/name --issue n --token token");
 }
+/**
+ * Files that, if a PR touches them, would let that PR rewrite what the trusted
+ * recap job runs (the workflow itself, the skill, the local CLI, or any agent
+ * config the runner loads) — so the whole job is skipped, not just the agent
+ * step, to keep untrusted PR code away from the publish/API secrets.
+ *
+ * The `packages/core/**` rule is scoped to the BuilderIO/agent-native monorepo
+ * (where packages/core IS the recap CLI source) so that consumer repos with an
+ * unrelated `packages/core/` directory are not silently gated. Pass the
+ * `repository` ("owner/name") to apply that scoping; omit it to match the old
+ * unconditional behaviour (safe for the gate's self-test).
+ */
+export function isRecapSensitivePath(p, repository) {
+    if (p === ".github/workflows/pr-visual-recap.yml" ||
+        /(^|\/)skills\/visual-(recap|plan|plans)\//.test(p) ||
+        /(^|\/)\.claude\//.test(p) ||
+        /(^|\/)CLAUDE\.md$/.test(p) ||
+        /(^|\/)AGENTS\.md$/.test(p) ||
+        /(^|\/)\.mcp\.json$/.test(p)) {
+        return true;
+    }
+    // packages/core is the recap-CLI source only in the agent-native monorepo.
+    // In consumer repos an unrelated packages/core/ must not gate recaps.
+    const isAgentNativeMonorepo = !repository || repository === "BuilderIO/agent-native";
+    if (isAgentNativeMonorepo && /(^|\/)packages\/core\//.test(p)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * The pure gate decision: given the PR payload, secret-presence flags, the
+ * configured backend/model, and the PR's changed files, decide whether the
+ * visual recap should run, which (normalized) agent to use, and — when skipped —
+ * the human-readable reasons. This is the security boundary; it replicates the
+ * inline github-script gate bit-for-bit. No I/O so it can be unit-tested.
+ */
+export function evaluateRecapGate(input) {
+    const { pr } = input;
+    const reasons = [];
+    if (!pr)
+        reasons.push("no pull_request payload");
+    if (pr && pr.draft)
+        reasons.push("draft PR");
+    // Fork PRs: head repo differs from this repo. Plain pull_request runs fork
+    // code with NO secrets, so publishing would fail anyway — skip.
+    const headRepo = pr && pr.head && pr.head.repo && pr.head.repo.full_name;
+    if (pr && headRepo && headRepo !== input.repository) {
+        reasons.push(`fork PR (${headRepo})`);
+    }
+    // Skip noisy automated authors.
+    const login = ((pr && pr.user && pr.user.login) || "").toLowerCase();
+    const botAuthors = [
+        "dependabot[bot]",
+        "dependabot",
+        "renovate[bot]",
+        "renovate",
+    ];
+    if (botAuthors.includes(login))
+        reasons.push(`bot author (${login})`);
+    if (pr && pr.user && pr.user.type === "Bot")
+        reasons.push("bot author (type=Bot)");
+    // Publish secret must be configured — otherwise this is a no-op so the
+    // workflow can be merged before secrets exist.
+    if (!input.hasPlan)
+        reasons.push("PLAN_RECAP_TOKEN not configured");
+    // The chosen backend's API key must be present. Normalize the agent value once
+    // here and validate it: an unknown or mis-cased value (e.g. "Claude", "gpt")
+    // must NOT silently pass the gate and then match neither agent step.
+    const agent = (input.agentRaw || "claude").toLowerCase();
+    if (agent !== "claude" && agent !== "codex") {
+        reasons.push(`unsupported VISUAL_RECAP_AGENT "${input.agentRaw}" (expected "claude" or "codex")`);
+    }
+    else if (agent === "codex") {
+        if (!input.hasOpenai)
+            reasons.push("OPENAI_API_KEY not configured (codex backend)");
+    }
+    else {
+        if (!input.hasAnthropic)
+            reasons.push("ANTHROPIC_API_KEY not configured (claude backend)");
+    }
+    // Validate VISUAL_RECAP_MODEL if set — an unchecked value could be injected by
+    // a repo settings writer and passed straight to the agent CLI.
+    const model = input.model || "";
+    if (model && !/^[a-zA-Z0-9._-]{1,80}$/.test(model)) {
+        reasons.push("invalid VISUAL_RECAP_MODEL value (must match [a-zA-Z0-9._-]{1,80})");
+    }
+    // Self-modifying guard: if this PR changes the workflow, the
+    // visual-recap/visual-plan skill, the local CLI (packages/core), or any agent
+    // config the runner would load (.claude/**, CLAUDE.md, .mcp.json), skip the
+    // ENTIRE job — not just the agent — so a PR can never rewrite what runs
+    // (skill, hooks, settings, CLI) and exfiltrate the publish/API secrets.
+    const hits = input.changedFiles.filter((p) => isRecapSensitivePath(p, input.repository));
+    if (hits.length) {
+        reasons.push(`PR modifies recap-control files (${hits.slice(0, 3).join(", ")}${hits.length > 3 ? ", …" : ""}) — skipping so untrusted PR code never runs with secrets`);
+    }
+    return { run: reasons.length === 0, agent, reasons };
+}
+/**
+ * Page through `GET /repos/{owner}/{repo}/pulls/{n}/files`, following the
+ * `Link` rel="next" header, and return every changed filename. Uses the same
+ * api.github.com base + auth headers as `githubRequest`; reads the `Link`
+ * header (which `githubRequest` discards) so it can paginate. Throws on any
+ * non-2xx so the caller can fail CLOSED — exactly like the inline gate did when
+ * `github.paginate(listFiles)` rejected.
+ */
+async function listPullRequestFiles(input) {
+    const filenames = [];
+    let url = `https://api.github.com/repos/${encodeURIComponent(input.owner)}/${encodeURIComponent(input.repo)}/pulls/${input.pull}/files?per_page=100`;
+    while (url) {
+        const res = await fetch(url, {
+            headers: {
+                accept: "application/vnd.github+json",
+                authorization: `Bearer ${input.token}`,
+                "x-github-api-version": "2022-11-28",
+            },
+        });
+        if (!res.ok) {
+            const detail = await res.text().catch(() => "");
+            throw new Error(`GitHub request failed ${res.status} ${res.statusText}: ${detail.slice(0, 500)}`);
+        }
+        const page = (await res.json());
+        for (const f of page) {
+            if (typeof f.filename === "string")
+                filenames.push(f.filename);
+        }
+        // Follow Link rel="next" for the next page; absent => done.
+        const link = res.headers.get("link") || "";
+        const next = link.match(/<([^>]+)>\s*;\s*rel="next"/);
+        url = next ? next[1] : null;
+    }
+    return filenames;
+}
+/**
+ * `recap gate` — the I/O wrapper around `evaluateRecapGate`. Reads the PR
+ * payload from GITHUB_EVENT_PATH, the secret-presence/agent/model signals from
+ * the environment, and the PR's changed files from the GitHub REST API (paged,
+ * with GH_TOKEN/GITHUB_TOKEN). Writes `run` + the normalized `agent` to
+ * $GITHUB_OUTPUT and logs the run/skip summary. Fails CLOSED on any file-list
+ * error so an untrusted PR can never run the agent with secrets.
+ */
+async function runGate() {
+    const repository = process.env.GITHUB_REPOSITORY;
+    // Read the pull_request object out of the event payload, tolerating a
+    // missing/unreadable file (degrades to the "no pull_request payload" reason).
+    let pr = null;
+    const eventPath = process.env.GITHUB_EVENT_PATH;
+    if (eventPath) {
+        try {
+            const payload = JSON.parse(fs.readFileSync(eventPath, "utf8"));
+            pr = payload && payload.pull_request ? payload.pull_request : null;
+        }
+        catch {
+            pr = null;
+        }
+    }
+    // Fetch the PR's changed files for the self-modifying guard. Any error here is
+    // turned into a skip reason (fail-closed), mirroring the inline gate's
+    // try/catch around github.paginate(listFiles).
+    const changedFiles = [];
+    let fileListError = null;
+    if (pr && typeof pr.number === "number" && repository) {
+        const token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN || "";
+        try {
+            const { owner, repo } = repoParts(repository);
+            const files = await listPullRequestFiles({
+                token,
+                owner,
+                repo,
+                pull: pr.number,
+            });
+            changedFiles.push(...files);
+        }
+        catch (e) {
+            fileListError = e instanceof Error ? e.message : String(e);
+        }
+    }
+    const decision = evaluateRecapGate({
+        pr,
+        repository,
+        hasPlan: process.env.HAS_PLAN === "true",
+        hasAnthropic: process.env.HAS_ANTHROPIC === "true",
+        hasOpenai: process.env.HAS_OPENAI === "true",
+        agentRaw: process.env.AGENT,
+        model: process.env.VISUAL_RECAP_MODEL,
+        changedFiles,
+    });
+    // If listing PR files failed, append the same fail-closed reason the inline
+    // gate used and force run=false.
+    let { run } = decision;
+    const reasons = [...decision.reasons];
+    if (fileListError !== null) {
+        reasons.push(`could not list PR files for the self-modifying guard (${fileListError}); skipping to be safe`);
+        run = false;
+    }
+    // Preserve the github-script contract: write `run` + the NORMALIZED agent to
+    // $GITHUB_OUTPUT so the recap job's step conditions match case-insensitively.
+    const githubOutput = process.env.GITHUB_OUTPUT;
+    if (githubOutput) {
+        fs.appendFileSync(githubOutput, `run=${run ? "true" : "false"}\nagent=${decision.agent}\n`);
+    }
+    // eslint-disable-next-line no-console
+    console.log(run
+        ? `Visual recap will run (${decision.agent}).`
+        : `Visual recap skipped: ${reasons.join("; ")}`);
+}
+/* -------------------------------------------------------------------------- */
+/* Check run — the "Visual Recap" GitHub check (was two inline github-script    */
+/* steps in the workflow's recap job).                                          */
+/* -------------------------------------------------------------------------- */
+/**
+ * Canonicalize the agent-written plan URL into a trusted recap URL, or "".
+ *
+ * recap-url.txt is produced by the (LLM) agent, so the raw URL is untrusted.
+ * This rebuilds a canonical `${origin}${base}/recaps/<id>` link from the TRUSTED
+ * app URL plus a strictly-validated plan id, enforcing the app origin and
+ * honoring a path-prefixed mount (e.g. https://host/agent-native). Returns ""
+ * for a wrong origin or an unrecognized path. Pure so it can be unit-tested —
+ * SAME impl as the workflow's previous inline `canonicalRecapUrl`.
+ */
+export function canonicalRecapUrl(rawUrl, appUrl) {
+    try {
+        const parsed = new URL(rawUrl);
+        const trusted = new URL(appUrl || "https://plan.agent-native.com");
+        if (parsed.origin !== trusted.origin)
+            return "";
+        // Honor a path-prefixed mount (e.g. https://host/agent-native): strip the
+        // trusted base path before matching /plans|recaps/<id>.
+        const base = trusted.pathname.replace(/\/$/, "");
+        let rest = parsed.pathname;
+        if (base && rest.startsWith(base))
+            rest = rest.slice(base.length);
+        const match = rest.match(/^\/(?:plans|recaps)\/([A-Za-z0-9_-]+)\/?$/);
+        return match ? `${trusted.origin}${base}/recaps/${match[1]}` : "";
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Map the workflow's terminal recap state to the completed check's
+ * conclusion/title/summary/text/details_url. Pure so it can be unit-tested —
+ * reproduces the workflow's previous inline branch logic EXACTLY:
+ *
+ * - default → neutral "Visual recap not generated"
+ * - planOk + valid recapUrl → success "Visual recap ready" (huge → "summarized"
+ *   summary), Open-recap link as text, details_url = recapUrl
+ * - planOk + invalid url → neutral "Visual recap published" (see the comment)
+ * - else tiny → skipped "Visual recap skipped"
+ * - else suppressed → skipped "Visual recap suppressed" (reason from scan JSON)
+ */
+export function recapCheckOutcome(input) {
+    let conclusion = "neutral";
+    let title = "Visual recap not generated";
+    let summary = "The visual recap did not produce a plan URL. This is informational only and does not block the PR.";
+    let text = "";
+    let detailsUrl = input.workflowUrl;
+    if (input.planOk) {
+        const recapUrl = canonicalRecapUrl(input.planUrl, input.appUrl);
+        if (recapUrl) {
+            conclusion = "success";
+            title = "Visual recap ready";
+            summary = input.huge
+                ? "A summarized visual recap was generated for this large PR."
+                : "A visual code-review recap was generated for this PR.";
+            detailsUrl = recapUrl;
+            text = `**[Open visual recap](${recapUrl})**`;
+        }
+        else {
+            // Agent reported success but the URL didn't validate against the trusted
+            // plan origin — don't claim "not generated"; the recap is linked in the
+            // sticky comment.
+            title = "Visual recap published";
+            summary =
+                "A recap was published; see the visual recap comment on this PR for the link.";
+        }
+    }
+    else if (input.tiny) {
+        conclusion = "skipped";
+        title = "Visual recap skipped";
+        summary = "The diff is too small to need a visual recap.";
+    }
+    else if (input.suppressed) {
+        let reason = "potential secret in diff";
+        try {
+            const parsed = JSON.parse(input.suppressedJson || "{}");
+            if (parsed && typeof parsed.reason === "string")
+                reason = parsed.reason;
+        }
+        catch {
+            // Keep the default reason.
+        }
+        conclusion = "skipped";
+        title = "Visual recap suppressed";
+        summary = `No recap was published because ${reason}.`;
+    }
+    return { conclusion, title, summary, text, detailsUrl };
+}
+function boolFlag(args, key) {
+    return args[key] === true || args[key] === "true";
+}
+/**
+ * `recap check start` — create the in-progress "Visual Recap" GitHub check run
+ * and write its id to $GITHUB_OUTPUT (check_run_id). Best-effort: on any API
+ * error, warn on stderr and exit 0 (don't fail the job) without emitting an id.
+ * Replaces the workflow's inline "Start visual recap check" github-script step.
+ */
+async function runCheckStart(args) {
+    const repo = optionalArg(args, "repo") ?? process.env.GITHUB_REPOSITORY ?? "";
+    const sha = optionalArg(args, "sha") ?? process.env.HEAD_SHA ?? "";
+    const token = optionalArg(args, "token") ||
+        process.env.GH_TOKEN ||
+        process.env.GITHUB_TOKEN ||
+        "";
+    const workflowUrl = optionalArg(args, "workflow-url") ?? "";
+    const emit = (id) => {
+        const githubOutput = process.env.GITHUB_OUTPUT;
+        if (githubOutput) {
+            fs.appendFileSync(githubOutput, `check_run_id=${id}\n`);
+        }
+    };
+    try {
+        const { owner, repo: name } = repoParts(repo);
+        const created = await githubRequest(token, `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/check-runs`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                name: "Visual Recap",
+                head_sha: sha,
+                status: "in_progress",
+                started_at: new Date().toISOString(),
+                details_url: workflowUrl,
+                output: {
+                    title: "Visual recap in progress",
+                    summary: "Generating a visual code-review recap for this pull request.",
+                },
+            }),
+        });
+        emit(String(created.id));
+    }
+    catch (err) {
+        process.stderr.write(`[recap check] could not create Visual Recap check run: ${String(err)}\n`);
+        // Best-effort: don't fail the job and don't emit a check_run_id.
+    }
+}
+/**
+ * `recap check complete` — PATCH the "Visual Recap" check run to completed with
+ * the computed conclusion/title/summary/text/details_url. Best-effort: on any
+ * API error, warn on stderr and exit 0. Replaces the workflow's inline
+ * "Complete visual recap check" github-script step.
+ */
+async function runCheckComplete(args) {
+    const repo = optionalArg(args, "repo") ?? process.env.GITHUB_REPOSITORY ?? "";
+    const token = optionalArg(args, "token") ||
+        process.env.GH_TOKEN ||
+        process.env.GITHUB_TOKEN ||
+        "";
+    const checkRunId = optionalArg(args, "check-run-id") ?? "";
+    const outcome = recapCheckOutcome({
+        planOk: boolFlag(args, "plan-ok"),
+        planUrl: optionalArg(args, "plan-url") ?? "",
+        appUrl: optionalArg(args, "app-url") ?? process.env.PLAN_RECAP_APP_URL ?? "",
+        huge: boolFlag(args, "huge"),
+        tiny: boolFlag(args, "tiny"),
+        suppressed: boolFlag(args, "suppressed"),
+        suppressedJson: optionalArg(args, "suppressed-json") ?? "",
+        workflowUrl: optionalArg(args, "workflow-url") ?? "",
+    });
+    try {
+        const { owner, repo: name } = repoParts(repo);
+        await githubRequest(token, `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/check-runs/${encodeURIComponent(checkRunId)}`, {
+            method: "PATCH",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                status: "completed",
+                conclusion: outcome.conclusion,
+                completed_at: new Date().toISOString(),
+                details_url: outcome.detailsUrl,
+                output: {
+                    title: outcome.title,
+                    summary: outcome.summary,
+                    text: outcome.text,
+                },
+            }),
+        });
+    }
+    catch (err) {
+        process.stderr.write(`[recap check] could not update Visual Recap check run: ${String(err)}\n`);
+        // Best-effort: don't fail the job.
+    }
+}
+/** `recap check <start|complete>` dispatcher. */
+async function runCheck(args, sub) {
+    if (sub === "start") {
+        await runCheckStart(args);
+        return;
+    }
+    if (sub === "complete") {
+        await runCheckComplete(args);
+        return;
+    }
+    throw new Error("Usage: agent-native recap check <start|complete> [flags] (see `recap help`)");
+}
 /** Parse the last top-level JSON object from a possibly-noisy stdout dump. */
 function parseLastJsonObject(text) {
     const trimmed = text.trim();
@@ -728,16 +1915,63 @@ async function runUsage(args) {
 const HELP = `agent-native recap — PR visual recap helpers (used by the GitHub Action)
 
 Usage:
+  agent-native recap setup [--repo owner/name] [--agent claude|codex] [--app-url <url>] [--skip-secrets] [--dry-run]
+  agent-native recap doctor [--repo owner/name] [--agent claude|codex] [--app-url <url>]
+  agent-native recap collect-diff --base <baseSha> --head <headSha> [--out recap.diff] [--stat recap.stat]
+  agent-native recap mcp-config --agent claude|codex --app-url <url> [--out <path>]
   agent-native recap scan --diff <path>
-  agent-native recap build-prompt --pr <n> [--head <sha>] [--app-url <url>] [--diff <path>] [--stat <path>] [--prev-plan-id <id>] [--huge] [--out <path>]
+  agent-native recap build-prompt --pr <n> [--repo owner/name] [--head <sha>] [--app-url <url>] [--diff <path>] [--stat <path>] [--prev-plan-id <id>] [--huge] [--local-files] [--local-dir <folder>] [--skill-source auto|latest|repo] [--out <path>]
   agent-native recap shot --url <planUrl> [--token <planToken>] [--app-url <url>] [--out recap.png]
   agent-native recap usage --plan-url <planUrl> --result-file <path> --app-url <url> --token <planToken> [--agent claude|codex] [--model <id>]
   agent-native recap comment <find-plan-id|upsert> --repo owner/name --issue <n> --token <github-token>
+  agent-native recap check start [--repo owner/name] [--sha <headSha>] [--token <github-token>] [--workflow-url <url>]
+    Create the in-progress "Visual Recap" GitHub check run and write its id to
+    $GITHUB_OUTPUT (check_run_id). repo/sha/token default to GITHUB_REPOSITORY /
+    HEAD_SHA / GH_TOKEN (or GITHUB_TOKEN). Best-effort: warns and exits 0 on any
+    API error without emitting an id.
+  agent-native recap check complete --check-run-id <id> [--repo owner/name] [--token <github-token>] [--plan-ok <bool>] [--plan-url <url>] [--app-url <url>] [--suppressed <bool>] [--suppressed-json <json>] [--huge <bool>] [--tiny <bool>] [--workflow-url <url>]
+    Mark the "Visual Recap" check run completed with a computed
+    conclusion/title/summary/text/details_url (success when the agent published a
+    plan whose URL validates against --app-url; neutral/skipped otherwise).
+    repo/token/app-url default to GITHUB_REPOSITORY / GH_TOKEN / PLAN_RECAP_APP_URL.
+    Best-effort: warns and exits 0 on any API error.
+  agent-native recap gate
+    The PR Visual Recap security gate. Decides whether to run the recap at all
+    and which (normalized) backend agent to use. Reads the pull_request payload
+    from $GITHUB_EVENT_PATH, the secret-presence/agent/model signals from the
+    environment (HAS_PLAN / HAS_ANTHROPIC / HAS_OPENAI === 'true', AGENT,
+    VISUAL_RECAP_MODEL), the repo from $GITHUB_REPOSITORY, and the PR's changed
+    files from the GitHub REST API (paged, with GH_TOKEN/GITHUB_TOKEN). Skips
+    drafts, forks, bot authors, the missing-secret case, an invalid agent/model,
+    and any PR that touches recap-control files (the workflow, the skill,
+    packages/core, .claude/**, CLAUDE.md, AGENTS.md, .mcp.json) — failing CLOSED
+    on any file-list error. Writes run=<true|false> and agent=<claude|codex> to
+    $GITHUB_OUTPUT.
+  agent-native recap setup
+    Write/refresh .github/workflows/pr-visual-recap.yml, then configure GitHub
+    Actions secrets and variables with gh when values are available from env or
+    the local Plans publish-token store. Missing values are printed as exact next
+    commands; secret values are sent to gh through stdin, never argv.
+  agent-native recap doctor
+    Check workflow presence/drift, local Plans publish-token availability, gh
+    repo access, and required GitHub Actions secrets for the selected backend.
 `;
 export async function runRecap(argv) {
     const [sub, ...rest] = argv;
     const args = parseArgs(rest);
     switch (sub) {
+        case "setup":
+            runSetup(args);
+            return;
+        case "doctor":
+            runDoctor(args);
+            return;
+        case "collect-diff":
+            runCollectDiff(args);
+            return;
+        case "mcp-config":
+            runMcpConfig(args);
+            return;
         case "scan":
             runScan(args);
             return;
@@ -753,6 +1987,12 @@ export async function runRecap(argv) {
         case "comment":
             await runComment(parseArgs(rest.slice(1)), rest[0] ?? "");
             return;
+        case "check":
+            await runCheck(parseArgs(rest.slice(1)), rest[0] ?? "");
+            return;
+        case "gate":
+            await runGate();
+            return;
         case "help":
         case "--help":
         case "-h":