@expo/code-review-cli 0.3.0 → 0.5.0

package/build/commands/doctor.js

@@ -1,74 +1,267 @@
-import { loadReviewConfig, hasConfig } from '../config/load.js';
-import { checkProviderAuth } from '../core/auth.js';
-import { onPath, repoRoot, run } from '../core/exec.js';
-import { errorMessage } from '../core/util.js';
+import { loadReviewConfig, loadScopeConfig, loadAuthFromRoot, hasConfig, resolveConfigDir, tokenEnvMismatch, } from "../config/load.js";
+import { loadRoutingManifest, resolveScopes, scopePassesBudgetMs, formatOwnerTable, } from "../config/routing.js";
+import { checkProviderAuth } from "../core/auth.js";
+import { opencodeBinSource } from "../core/opencode.js";
+import { git, onPath, repoRoot, run } from "../core/exec.js";
+import { errorMessage } from "../core/util.js";
+import path from "node:path";
 const USAGE = `ecr doctor — check environment, config, and credentials
 
 Usage:
-  ecr doctor
+  ecr doctor [--list-scopes]
 
 Verifies: opencode + git (+ gh for \`ecr ci\`) on PATH, .expo-code-review/ config is
-valid, agent prompts resolve, and the configured model's token env is set.
+valid, agent prompts resolve, and the configured model's token env is set. When a
+routing.jsonc is present, also validates every scope, the auth singleton, scope
+ownership over tracked files, and comment-tag uniqueness.
+
+Options:
+  --list-scopes   Print the routing scope table (name, dir, paths, agents, tag)
 `;
+/**
+ * `opencode --version`, run from `binDir` if given (so the bundled CLI can be asked
+ * directly) or from PATH otherwise. Null when it can't be determined — a version we
+ * can't read is worth staying quiet about, not failing over.
+ */
+async function opencodeVersion(binDir) {
+    const command = binDir ? path.join(binDir, "opencode") : "opencode";
+    const { stdout, code } = await run(command, ["--version"], { check: false });
+    if (code !== 0) {
+        return null;
+    }
+    return stdout.trim().split("\n")[0]?.trim() || null;
+}
 /** Preflight checks so a broken setup surfaces clearly instead of silently no-opping. */
 export async function doctorCommand(argv = []) {
-    if (argv.includes('-h') || argv.includes('--help')) {
+    if (argv.includes("-h") || argv.includes("--help")) {
         process.stdout.write(USAGE);
         return;
     }
     const root = (await repoRoot()) ?? process.cwd();
+    if (argv.includes("--list-scopes")) {
+        await listScopes(root);
+        return;
+    }
     let ok = true;
     const line = (pass, message) => {
         if (!pass) {
             ok = false;
         }
-        process.stdout.write(`  ${pass ? '✓' : '✗'} ${message}\n`);
+        process.stdout.write(`  ${pass ? "✓" : "✗"} ${message}\n`);
+    };
+    const info = (message) => {
+        process.stdout.write(`  ℹ ${message}\n`);
+    };
+    const warn = (message) => {
+        process.stdout.write(`  ⚠ ${message}\n`);
     };
     process.stdout.write(`expo-code-review doctor (repo: ${root})\n`);
-    const opencodeInstalled = await onPath('opencode');
+    // When the ROOT config dir is overridden, config.jsonc AND routing.jsonc are
+    // read from the resolved dir (scope subtrees stay repo-root-relative). Surface
+    // it so a green doctor run can't hide that it checked a non-default root.
+    if (process.env.ECR_CONFIG_DIR) {
+        info(`ECR_CONFIG_DIR override active: root config.jsonc and routing.jsonc read from ${resolveConfigDir(root)} (scope subtrees stay repo-root-relative)`);
+    }
+    // The SDK spawns a bare `opencode`, so the version that actually runs is a PATH
+    // lookup. Report which one wins and whether it matches the version this package
+    // pins: a stale global install against a newer SDK rejects model ids the SDK
+    // considers valid (`ProviderModelNotFoundError`), which is otherwise a baffling
+    // failure that only reproduces on one machine. `startOpencode` prepends our own
+    // bin dir so the pinned one wins at runtime — this just makes the drift visible.
+    const bin = opencodeBinSource();
+    const opencodeInstalled = (await onPath("opencode")) || bin.pinned;
     line(opencodeInstalled, opencodeInstalled
-        ? 'opencode CLI found on PATH'
-        : 'opencode CLI NOT on PATH (install `opencode-ai`, or add node_modules/.bin to PATH)');
-    line(await onPath('git'), 'git found on PATH');
+        ? "opencode CLI available"
+        : "opencode CLI NOT found (install `opencode-ai`, or add node_modules/.bin to PATH)");
+    if (opencodeInstalled) {
+        const pinnedVersion = bin.pinned ? await opencodeVersion(bin.dir) : null;
+        const pathVersion = await opencodeVersion(null);
+        if (pinnedVersion) {
+            line(true, `opencode ${pinnedVersion} (bundled with this reviewer; used at runtime)`);
+            if (pathVersion && pathVersion !== pinnedVersion) {
+                warn(`a different opencode ${pathVersion} is first on your PATH — runs use the bundled ${pinnedVersion}, ` +
+                    `but other tooling (and \`opencode\` by hand) will use ${pathVersion}`);
+            }
+        }
+        else if (pathVersion) {
+            warn(`using opencode ${pathVersion} from PATH — this reviewer's own \`opencode-ai\` dependency could not be ` +
+                `resolved, so the CLI and SDK versions can drift (a stale CLI rejects model ids the SDK accepts)`);
+        }
+    }
+    line(await onPath("git"), "git found on PATH");
     // `gh` is only needed for `ecr ci` (posting PR comments), so treat it as
     // informational (ℹ) rather than a hard failure for local `ecr review` users.
-    const info = (message) => {
-        process.stdout.write(`  ℹ ${message}\n`);
-    };
-    if (await onPath('gh')) {
+    if (await onPath("gh")) {
         let authed = false;
         try {
-            await run('gh', ['auth', 'status'], { cwd: root });
+            await run("gh", ["auth", "status"], { cwd: root });
             authed = true;
         }
         catch {
             authed = false;
         }
         if (authed) {
-            line(true, 'gh CLI found and authenticated (used by `ecr ci`)');
+            line(true, "gh CLI found and authenticated (used by `ecr ci`)");
         }
         else {
-            info('gh CLI found but not authenticated — run `gh auth login` before `ecr ci`');
+            info("gh CLI found but not authenticated — run `gh auth login` before `ecr ci`");
         }
     }
     else {
-        info('gh CLI not on PATH — only needed for `ecr ci` (posting PR comments)');
+        info("gh CLI not on PATH — only needed for `ecr ci` (posting PR comments)");
     }
+    let rootConfig;
     if (!hasConfig(root)) {
-        line(false, `no ${'.expo-code-review'}/config.jsonc (run \`ecr init\`)`);
+        line(false, `no ${".expo-code-review"}/config.jsonc (run \`ecr init\`)`);
     }
     else {
         try {
-            const config = await loadReviewConfig(root);
-            line(true, `config valid: ${config.agents.length} agent(s) [${config.agents.map(a => a.id).join(', ')}], coordinator model ${config.coordinator.model}`);
-            line(config.agents.every(a => Boolean(a.promptText.trim())), 'all agent prompt files resolved and non-empty');
-            const readiness = checkProviderAuth(config);
+            rootConfig = await loadReviewConfig(root);
+            line(true, `config valid: ${rootConfig.agents.length} agent(s) [${rootConfig.agents.map((a) => a.id).join(", ")}], coordinator model ${rootConfig.coordinator.model}`);
+            line(rootConfig.agents.every((a) => Boolean(a.promptText.trim())), "all agent prompt files resolved and non-empty");
+            const readiness = checkProviderAuth(rootConfig);
             line(readiness.ok, `auth: ${readiness.detail}`);
+            // A suspicious-but-not-provably-broken credential: worth saying, never a failure
+            // (the shape rules are heuristics — see checkOauthTokenShape).
+            if (readiness.warning) {
+                warn(`auth: ${readiness.warning}`);
+            }
         }
         catch (error) {
             line(false, `config invalid: ${errorMessage(error)}`);
         }
     }
-    process.stdout.write(ok ? '\nAll good.\n' : '\nIssues found (see ✗ above).\n');
+    // Routing manifest checks (only when a routing.jsonc is present).
+    let manifest = null;
+    try {
+        manifest = await loadRoutingManifest(root);
+    }
+    catch (error) {
+        line(false, `routing.jsonc invalid: ${errorMessage(error)}`);
+    }
+    if (manifest && rootConfig) {
+        process.stdout.write("\nRouting manifest:\n");
+        line(true, `manifest valid: ${manifest.scopes.length} scope(s), comment mode "${manifest.comment}"`);
+        // enforceAgents must exist in the ROOT roster.
+        for (const id of manifest.defaults.enforceAgents) {
+            const present = rootConfig.agents.some((agent) => agent.id === id);
+            line(present, present
+                ? `enforced agent "${id}" found in the root roster`
+                : `enforced agent "${id}" is NOT in the root roster (defaults.enforceAgents)`);
+        }
+        for (const scope of manifest.scopes) {
+            let scopeConfig;
+            try {
+                scopeConfig = await loadScopeConfig(root, scope, manifest, rootConfig);
+            }
+            catch (error) {
+                // A scope config declaring auth/breakGlass/commentTag surfaces its Zod
+                // error HERE, before CI.
+                line(false, `scope ${scope.name}: ${errorMessage(error)}`);
+                continue;
+            }
+            line(true, `scope ${scope.name}: ${scopeConfig.agents.length} agent(s) [${scopeConfig.agents.map((a) => a.id).join(", ")}], config ${scope.config}`);
+        }
+        // Passes-budget headroom: active scopes run sequentially, so the worst case
+        // is every scope active at the per-scope floor. If scopes.length × the floor
+        // exceeds the total, runs can outlast the total budget (a ⚠, not a failure —
+        // tune budget.* or the job timeout).
+        const totalMs = manifest.budget.totalPassesMinutes * 60_000;
+        const minMs = manifest.budget.minScopeMinutes * 60_000;
+        const { overshoot } = scopePassesBudgetMs(totalMs, minMs, manifest.scopes.length);
+        if (overshoot) {
+            warn(`passes budget: ${manifest.scopes.length} scopes × ${manifest.budget.minScopeMinutes}m floor = ${manifest.scopes.length * manifest.budget.minScopeMinutes}m worst case exceeds budget.totalPassesMinutes (${manifest.budget.totalPassesMinutes}m) — raise the job timeout or trim scopes`);
+        }
+        else {
+            line(true, `passes budget: worst case ${manifest.scopes.length} scopes × ${manifest.budget.minScopeMinutes}m floor fits budget.totalPassesMinutes (${manifest.budget.totalPassesMinutes}m)`);
+        }
+        // Per-scope comment markers are always derived (`<tag>:<scope>`, unique by
+        // scope-name uniqueness) and the scope schema rejects commentTag overrides,
+        // so marker collisions are impossible by construction — nothing to check.
+        // auth singleton: exactly one honored source (defaults.auth or root config auth).
+        const auth = loadAuthFromRoot(rootConfig, manifest);
+        const hasManifestAuth = Boolean(manifest.defaults.auth);
+        line(true, `auth singleton: honored from ${hasManifestAuth ? "routing.jsonc defaults.auth" : "root config.jsonc"} ` +
+            `(${auth.map((entry) => `${entry.mode}/${entry.provider}`).join(", ")})`);
+        const expected = process.env.ECR_EXPECTED_TOKEN_ENV;
+        if (expected) {
+            const mismatch = tokenEnvMismatch(auth, expected);
+            if (mismatch) {
+                line(false, `auth: ${mismatch}`);
+            }
+        }
+        for (const entry of auth) {
+            if (entry.tokenEnv) {
+                line(Boolean(process.env[entry.tokenEnv]), `auth token env ${entry.tokenEnv} (${entry.provider}) is ${process.env[entry.tokenEnv] ? "set" : "NOT set"}`);
+            }
+        }
+        // Owner-table dry run over tracked files (graft 4).
+        try {
+            const tracked = (await git(["ls-files"], root))
+                .split("\n")
+                .map((f) => f.trim())
+                .filter(Boolean);
+            const resolution = resolveScopes(manifest, tracked);
+            const hasCatchAll = manifest.scopes.some((scope) => scope.paths.includes("**/*"));
+            line(resolution.unmatched.length === 0 || hasCatchAll, resolution.unmatched.length === 0
+                ? `scope coverage: all ${tracked.length} tracked file(s) match a scope`
+                : `scope coverage: ${resolution.unmatched.length} file(s) match no scope${hasCatchAll ? " (ok — a **/* catch-all exists)" : " (add a **/* catch-all)"}`);
+            if (resolution.overlaps.length > 0) {
+                warn(`${resolution.overlaps.length} file(s) match >1 scope (last-match wins):`);
+                for (const owner of formatOwnerTable(resolution, 20)) {
+                    process.stdout.write(`${owner}\n`);
+                }
+            }
+        }
+        catch (error) {
+            info(`scope coverage: could not run \`git ls-files\` (${errorMessage(error)})`);
+        }
+    }
+    process.stdout.write(ok ? "\nAll good.\n" : "\nIssues found (see ✗ above).\n");
+    process.exitCode = ok ? 0 : 1;
+}
+/** Print the routing scope table; exit 0/1 on manifest validity alone. */
+async function listScopes(root) {
+    let manifest;
+    try {
+        manifest = await loadRoutingManifest(root);
+    }
+    catch (error) {
+        process.stdout.write(`  ✗ routing.jsonc invalid: ${errorMessage(error)}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    if (!manifest) {
+        process.stdout.write(`No ${".expo-code-review"}/routing.jsonc — run \`ecr init --monorepo\`.\n`);
+        process.exitCode = 0;
+        return;
+    }
+    let rootConfig;
+    try {
+        rootConfig = await loadReviewConfig(root);
+    }
+    catch (error) {
+        process.stdout.write(`  ✗ root config invalid: ${errorMessage(error)}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    process.stdout.write(`Routing scopes (comment mode: ${manifest.comment}):\n\n`);
+    let ok = true;
+    for (const scope of manifest.scopes) {
+        process.stdout.write(`  ${scope.name}\n`);
+        process.stdout.write(`    config:  ${scope.config}\n`);
+        process.stdout.write(`    paths:   ${scope.paths.join(", ")}\n`);
+        try {
+            const config = await loadScopeConfig(root, scope, manifest, rootConfig);
+            process.stdout.write(`    agents:  ${config.agents.map((a) => (a.alwaysRun ? `${a.id}*` : a.id)).join(", ")}\n`);
+            process.stdout.write(`    tag:     ${config.commentTag}\n`);
+        }
+        catch (error) {
+            ok = false;
+            process.stdout.write(`    ERROR:   ${errorMessage(error)}\n`);
+        }
+        process.stdout.write("\n");
+    }
+    process.stdout.write("(* = enforced, alwaysRun)\n");
     process.exitCode = ok ? 0 : 1;
 }

package/build/commands/init.js

@@ -1,41 +1,56 @@
-import { cp, mkdir, writeFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { CONFIG_DIRNAME } from '../config/load.js';
-import { repoRoot } from '../core/exec.js';
-import { errorMessage } from '../core/util.js';
-const TEMPLATES_DIR = fileURLToPath(new URL('../../templates/', import.meta.url));
+import { cp, mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONFIG_DIRNAME } from "../config/load.js";
+import { ROUTING_FILENAME } from "../config/routing.js";
+import { RoutingScopeSchema } from "../config/schema.js";
+import { repoRoot } from "../core/exec.js";
+import { errorMessage } from "../core/util.js";
+const TEMPLATES_DIR = fileURLToPath(new URL("../../templates/", import.meta.url));
 const USAGE = `ecr init — scaffold .expo-code-review/ in the current repo
 
 Usage:
-  ecr init [--no-workflow] [--force]
+  ecr init [--no-workflow] [--force]      Scaffold the root config (+ CI workflow)
+  ecr init --monorepo [--force]           …and add a routing.jsonc (one default scope)
+  ecr init --scope <dir> [--force]        Scaffold a per-team scope under <dir> and
+                                          register it in the root routing.jsonc
 
 Options:
-  --no-workflow   Skip writing the CI workflow (.github/workflows/expo-code-review.yml)
+  --monorepo      Also write .expo-code-review/routing.jsonc (routing manifest)
+  --scope <dir>   Scaffold <dir>/.expo-code-review/ (no auth) + add a scope entry
+  --no-workflow   Skip writing the CI workflows (review, command, and dismiss
+                  under .github/workflows/)
   --force         Overwrite existing files
   -h, --help      Show this help
 `;
 export async function initCommand(argv) {
-    if (argv.includes('-h') || argv.includes('--help')) {
+    if (argv.includes("-h") || argv.includes("--help")) {
         process.stdout.write(USAGE);
         return;
     }
     try {
-        await scaffold(argv);
+        const scopeDir = parseValue(argv, "--scope");
+        if (scopeDir != null) {
+            await scaffoldScope(argv, scopeDir);
+        }
+        else {
+            await scaffold(argv);
+        }
     }
     catch (error) {
         process.stderr.write(`init failed: ${errorMessage(error)}\n`);
         process.exitCode = 2;
     }
 }
-/** Scaffold .expo-code-review/ (and optionally the CI workflow) into the repo. */
+/** Scaffold .expo-code-review/ (and optionally the CI workflow + routing manifest). */
 async function scaffold(argv) {
-    const force = argv.includes('--force');
+    const force = argv.includes("--force");
     // The CI workflow is scaffolded by default (most repos adopting this want it);
     // `--no-workflow` opts out. `--with-workflow` is still accepted as a no-op for
     // back-compat.
-    const withWorkflow = !argv.includes('--no-workflow');
+    const withWorkflow = !argv.includes("--no-workflow");
+    const monorepo = argv.includes("--monorepo");
     const root = (await repoRoot()) ?? process.cwd();
     const configDir = path.join(root, CONFIG_DIRNAME);
     // Create only the config dir; let copyInto create prompts/ so it reports
@@ -43,40 +58,235 @@ async function scaffold(argv) {
     await mkdir(configDir, { recursive: true });
     const created = [];
     const skipped = [];
-    await copyInto(path.join(TEMPLATES_DIR, 'config.jsonc'), path.join(configDir, 'config.jsonc'), force, created, skipped, root);
-    await copyInto(path.join(TEMPLATES_DIR, 'shared.md'), path.join(configDir, 'shared.md'), force, created, skipped, root);
-    await copyInto(path.join(TEMPLATES_DIR, 'coordinator.md'), path.join(configDir, 'coordinator.md'), force, created, skipped, root);
-    await copyInto(path.join(TEMPLATES_DIR, 'agents'), path.join(configDir, 'agents'), force, created, skipped, root);
-    const gitignorePath = path.join(configDir, '.gitignore');
+    await copyInto(path.join(TEMPLATES_DIR, "config.jsonc"), path.join(configDir, "config.jsonc"), force, created, skipped, root);
+    await copyInto(path.join(TEMPLATES_DIR, "shared.md"), path.join(configDir, "shared.md"), force, created, skipped, root);
+    await copyInto(path.join(TEMPLATES_DIR, "coordinator.md"), path.join(configDir, "coordinator.md"), force, created, skipped, root);
+    await copyInto(path.join(TEMPLATES_DIR, "agents"), path.join(configDir, "agents"), force, created, skipped, root);
+    const gitignorePath = path.join(configDir, ".gitignore");
     if (force || !existsSync(gitignorePath)) {
-        await writeFile(gitignorePath, '.runs/\n', 'utf8');
+        await writeFile(gitignorePath, ".runs/\n", "utf8");
         created.push(path.relative(root, gitignorePath));
     }
     else {
         skipped.push(path.relative(root, gitignorePath));
     }
+    if (monorepo) {
+        await copyInto(path.join(TEMPLATES_DIR, ROUTING_FILENAME), path.join(configDir, ROUTING_FILENAME), force, created, skipped, root);
+    }
     if (withWorkflow) {
-        const workflowDir = path.join(root, '.github', 'workflows');
+        const workflowDir = path.join(root, ".github", "workflows");
         await mkdir(workflowDir, { recursive: true });
-        await copyInto(path.join(TEMPLATES_DIR, 'workflow.yml'), path.join(workflowDir, 'expo-code-review.yml'), force, created, skipped, root);
+        // The auto (pull_request) workflow, plus the two issue_comment command
+        // workflows: `/review` (on-demand one-shot) and `/dismiss` (hide a finding).
+        await copyInto(path.join(TEMPLATES_DIR, "workflow.yml"), path.join(workflowDir, "expo-code-review.yml"), force, created, skipped, root);
+        await copyInto(path.join(TEMPLATES_DIR, "command.yml"), path.join(workflowDir, "expo-code-review-command.yml"), force, created, skipped, root);
+        await copyInto(path.join(TEMPLATES_DIR, "dismiss.yml"), path.join(workflowDir, "expo-code-review-dismiss.yml"), force, created, skipped, root);
+    }
+    reportFiles(created, skipped);
+    process.stdout.write([
+        "",
+        "Next steps:",
+        `  1. Customize ${CONFIG_DIRNAME}/agents/*.md (and shared.md, coordinator.md) for this repo.`,
+        "  2. Configure a model provider in OpenCode (or set REVIEWER_MODEL).",
+        "  3. Run `ecr doctor`, then `ecr review`.",
+        withWorkflow
+            ? "  4. Add the model-key secret referenced by the workflow, then add an `ai-review` label to a PR."
+            : "  4. (No CI workflow written — re-run without `--no-workflow` to add it.)",
+        monorepo
+            ? `  5. Add per-team scopes with \`ecr init --scope <dir>\` (see ${CONFIG_DIRNAME}/${ROUTING_FILENAME}).`
+            : `  5. Monorepo? Run \`ecr init --monorepo\` to add a routing manifest.`,
+        "",
+    ].join("\n"));
+}
+/**
+ * Scaffold a per-team scope under <dir>: <dir>/.expo-code-review/ with a no-auth
+ * config, prompts and agents, then register the scope in the root routing.jsonc.
+ */
+async function scaffoldScope(argv, scopeDirRaw) {
+    const force = argv.includes("--force");
+    const root = (await repoRoot()) ?? process.cwd();
+    const scopeDir = scopeDirRaw.replace(/\/+$/, "");
+    const routingPath = path.join(root, CONFIG_DIRNAME, ROUTING_FILENAME);
+    if (!existsSync(routingPath)) {
+        throw new Error(`no ${CONFIG_DIRNAME}/${ROUTING_FILENAME} — run \`ecr init --monorepo\` first`);
+    }
+    // Derive the scope entry and validate it BEFORE creating any files: the name must
+    // satisfy RoutingScopeSchema's kebab-case rule (derived by sanitizing the dir,
+    // apps/Foo_Bar -> apps-foo-bar), and the config path is rejected when absolute or
+    // containing ".." — validating first keeps a traversal dir (e.g. `--scope
+    // ../../outside`) from orphaning files outside the repo, and a bad name from
+    // making routing.jsonc unloadable and silently stopping every review.
+    const entry = {
+        name: scopeDir
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, "-")
+            .replace(/^-+|-+$/g, ""),
+        paths: [`${scopeDir}/**`],
+        config: scopeDir,
+    };
+    const parsed = RoutingScopeSchema.safeParse(entry);
+    if (!parsed.success) {
+        throw new Error(`scope dir "${scopeDir}" yields an invalid scope entry (${parsed.error.issues[0]?.message}); ` +
+            `rename the directory or add the scope to ${CONFIG_DIRNAME}/${ROUTING_FILENAME} manually`);
+    }
+    const configDir = path.join(root, scopeDir, CONFIG_DIRNAME);
+    await mkdir(configDir, { recursive: true });
+    const created = [];
+    const skipped = [];
+    // The scope's config.jsonc is the auth-free scope template.
+    await copyInto(path.join(TEMPLATES_DIR, "scope-config.jsonc"), path.join(configDir, "config.jsonc"), force, created, skipped, root);
+    await copyInto(path.join(TEMPLATES_DIR, "shared.md"), path.join(configDir, "shared.md"), force, created, skipped, root);
+    await copyInto(path.join(TEMPLATES_DIR, "coordinator.md"), path.join(configDir, "coordinator.md"), force, created, skipped, root);
+    await copyInto(path.join(TEMPLATES_DIR, "agents"), path.join(configDir, "agents"), force, created, skipped, root);
+    const gitignorePath = path.join(configDir, ".gitignore");
+    if (force || !existsSync(gitignorePath)) {
+        await writeFile(gitignorePath, ".runs/\n", "utf8");
+        created.push(path.relative(root, gitignorePath));
+    }
+    else {
+        skipped.push(path.relative(root, gitignorePath));
+    }
+    // Register the scope in the root routing manifest, preserving comments/formatting.
+    const raw = await readFile(routingPath, "utf8");
+    const updated = appendScopeEntry(raw, entry);
+    let manifestNote;
+    if (updated == null) {
+        manifestNote = `  ! could not locate the "scopes" array in ${CONFIG_DIRNAME}/${ROUTING_FILENAME}; add this entry manually:\n      ${JSON.stringify(entry)}`;
     }
+    else if (updated === raw) {
+        manifestNote = `  skipped  ${CONFIG_DIRNAME}/${ROUTING_FILENAME} (scope "${entry.name}" already present)`;
+    }
+    else {
+        await writeFile(routingPath, updated, "utf8");
+        manifestNote = `  updated  ${CONFIG_DIRNAME}/${ROUTING_FILENAME} (+ scope "${entry.name}")`;
+    }
+    reportFiles(created, skipped);
+    process.stdout.write(`${manifestNote}\n`);
+    process.stdout.write([
+        "",
+        "Next steps:",
+        `  1. Customize ${scopeDir}/${CONFIG_DIRNAME}/agents/*.md for this team.`,
+        `  2. Add to CODEOWNERS so only the team edits its scope:`,
+        `       /${scopeDir}/${CONFIG_DIRNAME}/ @your-team`,
+        "  3. Run `ecr doctor --list-scopes` to verify routing.",
+        "",
+    ].join("\n"));
+}
+/**
+ * Insert a scope entry before the closing ] of the "scopes" array in raw JSONC,
+ * preserving comments/formatting. Returns the new text, the original text unchanged
+ * when a scope of the same name is already present, or null when the array can't be
+ * located (caller then prints the entry for manual addition).
+ */
+export function appendScopeEntry(routingRaw, entry) {
+    const keyMatch = routingRaw.search(/"scopes"\s*:/);
+    if (keyMatch === -1) {
+        return null;
+    }
+    const arrayStart = routingRaw.indexOf("[", keyMatch);
+    if (arrayStart === -1) {
+        return null;
+    }
+    // Find the matching close bracket by depth, skipping strings and // and /* */
+    // comments, and remember the last CONTENT character inside the array — users
+    // annotate routing.jsonc with comments, so the separating comma must land
+    // after the last entry, never inside a trailing comment.
+    let depth = 0;
+    let end = -1;
+    let lastContent = -1;
+    let i = arrayStart;
+    while (i < routingRaw.length) {
+        const char = routingRaw[i];
+        if (char === "/" && routingRaw[i + 1] === "/") {
+            const newline = routingRaw.indexOf("\n", i);
+            if (newline === -1) {
+                break;
+            }
+            i = newline;
+            continue;
+        }
+        if (char === "/" && routingRaw[i + 1] === "*") {
+            const close = routingRaw.indexOf("*/", i + 2);
+            if (close === -1) {
+                break;
+            }
+            i = close + 2;
+            continue;
+        }
+        if (char === '"') {
+            i++;
+            while (i < routingRaw.length && routingRaw[i] !== '"') {
+                if (routingRaw[i] === "\\") {
+                    i++;
+                }
+                i++;
+            }
+            lastContent = i;
+            i++;
+            continue;
+        }
+        if (char === "[") {
+            depth++;
+            if (i > arrayStart) {
+                lastContent = i;
+            }
+        }
+        else if (char === "]") {
+            depth--;
+            if (depth === 0) {
+                end = i;
+                break;
+            }
+            lastContent = i;
+        }
+        else if (!/\s/.test(char)) {
+            lastContent = i;
+        }
+        i++;
+    }
+    if (end === -1) {
+        return null;
+    }
+    // Idempotent: don't add a duplicate name.
+    const inner = routingRaw.slice(arrayStart + 1, end);
+    if (new RegExp(`"name"\\s*:\\s*"${escapeRegExp(entry.name)}"`).test(inner)) {
+        return routingRaw;
+    }
+    const line = `    { "name": ${JSON.stringify(entry.name)}, "paths": ${JSON.stringify(entry.paths)}, "config": ${JSON.stringify(entry.config)} }`;
+    const hasEntries = lastContent > arrayStart;
+    const needsComma = hasEntries && routingRaw[lastContent] !== ",";
+    // Insert the comma immediately after the last entry's final character (before
+    // any trailing comment), then append the new entry line before the ']'.
+    const withComma = needsComma
+        ? `${routingRaw.slice(0, lastContent + 1)},${routingRaw.slice(lastContent + 1)}`
+        : routingRaw;
+    const endAdjusted = needsComma ? end + 1 : end;
+    const before = withComma.slice(0, endAdjusted).replace(/\s*$/, "");
+    const after = withComma.slice(endAdjusted);
+    return `${before}\n${line}\n  ${after}`;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function reportFiles(created, skipped) {
     for (const file of created) {
         process.stdout.write(`  created  ${file}\n`);
     }
     for (const file of skipped) {
         process.stdout.write(`  skipped  ${file} (exists; use --force to overwrite)\n`);
     }
-    process.stdout.write([
-        '',
-        'Next steps:',
-        `  1. Customize ${CONFIG_DIRNAME}/agents/*.md (and shared.md, coordinator.md) for this repo.`,
-        '  2. Configure a model provider in OpenCode (or set REVIEWER_MODEL).',
-        '  3. Run `ecr doctor`, then `ecr review`.',
-        withWorkflow
-            ? '  4. Add the model-key secret referenced by the workflow, then add an `ai-review` label to a PR.'
-            : '  4. (No CI workflow written — re-run without `--no-workflow` to add it.)',
-        '',
-    ].join('\n'));
+}
+/** Parse a `--flag <value>` option; returns undefined when the flag is absent. */
+function parseValue(argv, flag) {
+    const index = argv.indexOf(flag);
+    if (index === -1) {
+        return undefined;
+    }
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--")) {
+        throw new Error(`${flag} requires a value`);
+    }
+    return value;
 }
 async function copyInto(src, dest, force, created, skipped, root) {
     const existed = existsSync(dest);