codebyplan 1.12.0 → 1.13.0

package/dist/cli.js

@@ -14,7 +14,7 @@ var VERSION, PACKAGE_NAME;
 var init_version = __esm({
   "src/lib/version.ts"() {
     "use strict";
-    VERSION = "1.12.0";
+    VERSION = "1.13.0";
     PACKAGE_NAME = "codebyplan";
   }
 });
@@ -978,28 +978,36 @@ var init_browser = __esm({
 });
 
 // src/oauth/device-flow.ts
-async function initiateDeviceCode(clientId) {
+async function initiateDeviceCode(clientId, scope, resource = "https://mcp.codebyplan.com/") {
+  const body = { client_id: clientId, resource };
+  if (scope !== void 0) {
+    body.scope = scope;
+  }
   const res = await fetch(deviceEndpoint(), {
     method: "POST",
     headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ client_id: clientId }),
+    body: JSON.stringify(body),
     signal: AbortSignal.timeout(1e4)
   });
   if (!res.ok) {
-    const body = await res.json().catch(() => ({}));
-    if (body.error === "invalid_client") {
+    const body2 = await res.json().catch(() => ({}));
+    if (body2.error === "invalid_client") {
       throw new OAuthInvalidClientError();
     }
-    const msg = body.error_description ?? body.error ?? `HTTP ${res.status}`;
+    const msg = body2.error_description ?? body2.error ?? `HTTP ${res.status}`;
     throw new Error(`Failed to initiate device flow: ${msg}`);
   }
-  return await res.json();
+  const dcResponse = await res.json();
+  return { ...dcResponse, resource };
 }
-async function pollOnce(deviceCode, clientId) {
+async function pollOnce(deviceCode, clientId, resource) {
   const params = new URLSearchParams();
   params.set("grant_type", "urn:ietf:params:oauth:grant-type:device_code");
   params.set("device_code", deviceCode);
   params.set("client_id", clientId);
+  if (resource !== void 0) {
+    params.set("resource", resource);
+  }
   const res = await fetch(tokenEndpoint(), {
     method: "POST",
     headers: { "Content-Type": "application/x-www-form-urlencoded" },
@@ -1023,7 +1031,11 @@ async function pollUntilSettled(opts) {
   const startMs = now();
   const expiresAtMs = startMs + opts.expiresInSec * 1e3;
   while (now() < expiresAtMs) {
-    const outcome = await pollOnce(opts.deviceCode, opts.clientId);
+    const outcome = await pollOnce(
+      opts.deviceCode,
+      opts.clientId,
+      opts.resource
+    );
     if (outcome.kind !== "pending") return outcome;
     if (opts.onTick) opts.onTick(Math.floor((now() - startMs) / 1e3));
     await sleep2(opts.intervalSec * 1e3);
@@ -1126,10 +1138,11 @@ async function fetchEmail(accessToken) {
     return null;
   }
 }
-async function runLogin() {
+async function runLogin(options = {}) {
+  const scope = options.admin ? "mcp:read mcp:write mcp:admin" : "mcp:read mcp:write";
   console.log("\n  CodeByPlan login\n");
   const { clientId, result: dc } = await ensureClientFor(
-    (id) => initiateDeviceCode(id)
+    (id) => initiateDeviceCode(id, scope)
   );
   const verificationUri = dc.verification_uri_complete ?? dc.verification_uri;
   console.log(`  Visit: ${verificationUri}`);
@@ -1143,7 +1156,8 @@ async function runLogin() {
     deviceCode: dc.device_code,
     clientId,
     intervalSec: dc.interval,
-    expiresInSec: dc.expires_in
+    expiresInSec: dc.expires_in,
+    resource: dc.resource
   });
   if (outcome.kind === "denied") {
     console.log("  Denied. Authorization request was rejected.\n");
@@ -1338,6 +1352,11 @@ async function writeCodebyplanDirectory(projectPath, selectedRepo, deviceId) {
     JSON.stringify({}, null, 2) + "\n",
     "utf-8"
   );
+  await writeFile6(
+    join6(codebyplanDir, "eslint.json"),
+    JSON.stringify({}, null, 2) + "\n",
+    "utf-8"
+  );
   const statuslinePath = join6(codebyplanDir, "statusline.json");
   let statuslineExists = false;
   try {
@@ -1355,7 +1374,7 @@ async function writeCodebyplanDirectory(projectPath, selectedRepo, deviceId) {
   await writeLocalConfig(projectPath, { device_id: deviceId });
   console.log(`  Created ${codebyplanDir}/`);
   console.log(
-    `    repo.json, server.json, git.json, shipment.json, vendor.json, e2e.json, statusline.json`
+    `    repo.json, server.json, git.json, shipment.json, vendor.json, e2e.json, eslint.json, statusline.json`
   );
   console.log(`    device.local.json (gitignored)`);
   const gitignoreAction = await ensureManagedGitignoreBlock(projectPath);
@@ -3472,7 +3491,7 @@ Run 'codebyplan round help' for usage.
 }
 function printRoundHelp() {
   process.stdout.write(
-    "\n  codebyplan round <subcommand>\n\n  Subcommands:\n    sync-approvals   Sync git diff and approvals with round/task state\n\n  sync-approvals flags:\n    --round-id <uuid>     Round UUID (required)\n    --task-id <uuid>      Task UUID (required)\n    --worktree-id <uuid>  Worktree UUID (optional; auto-resolved if absent)\n    --dry-run             Print merged payload to stdout without writing\n\n"
+    "\n  codebyplan round <subcommand>\n\n  Subcommands:\n    sync-approvals   Sync git diff and approvals with round/task state\n\n  sync-approvals flags:\n    --round-id <uuid>     Round UUID (required)\n    --task-id <uuid>      Task UUID (required)\n    --dry-run             Print merged payload to stdout without writing\n\n"
   );
 }
 function parseFlagsFromArgs(args) {
@@ -3513,10 +3532,6 @@ async function runRoundSyncApprovals(args) {
   let skipReason = null;
   let stdoutPayload = null;
   try {
-    let callerWorktreeId = flags["worktree-id"];
-    if (!callerWorktreeId) {
-      callerWorktreeId = await autoResolveWorktreeId();
-    }
     const found = await findCodebyplanConfig(process.cwd());
     const repoRoot = found ? (
       // Walk up to the directory containing .codebyplan/ or .codebyplan.json
@@ -3583,23 +3598,15 @@ async function runRoundSyncApprovals(args) {
           2
         );
       } else {
-        const roundArgs = {
+        await mcpCall("update_round", {
           round_id: roundId,
           files_changed: result.merged_files_changed
-        };
-        if (callerWorktreeId) {
-          roundArgs["caller_worktree_id"] = callerWorktreeId;
-        }
-        await mcpCall("update_round", roundArgs);
-        const taskArgs = {
+        });
+        await mcpCall("update_task", {
           task_id: taskId,
           files_changed: result.merged_files_changed,
           app_file_approval_by_user: false
-        };
-        if (callerWorktreeId) {
-          taskArgs["caller_worktree_id"] = callerWorktreeId;
-        }
-        await mcpCall("update_task", taskArgs);
+        });
         stdoutPayload = JSON.stringify(
           {
             added: result.added,
@@ -3633,42 +3640,6 @@ async function runRoundSyncApprovals(args) {
   process.stdout.write(stdoutPayload + "\n");
   process.exit(0);
 }
-async function autoResolveWorktreeId() {
-  try {
-    const projectPath = process.cwd();
-    const found = await findCodebyplanConfig(projectPath);
-    if (!found?.contents.repo_id) return void 0;
-    const repoId = found.contents.repo_id;
-    const deviceId = await getOrCreateDeviceId(projectPath);
-    let branch = "";
-    try {
-      branch = execSync2("git symbolic-ref --short HEAD", {
-        cwd: projectPath,
-        encoding: "utf-8"
-      }).trim();
-    } catch {
-    }
-    const worktreeId = await resolveWorktreeId({
-      repoId,
-      repoPath: projectPath,
-      branch,
-      deviceId
-    });
-    if (worktreeId) return worktreeId;
-    const fallbackId = await resolveWorktreeByBranch({
-      repoId,
-      deviceId,
-      branch
-    });
-    if (fallbackId) return fallbackId;
-    process.stderr.write(
-      "sync-approvals: could not resolve worktree id; proceeding without caller_worktree_id\n"
-    );
-    return void 0;
-  } catch {
-    return void 0;
-  }
-}
 var RETRY_DELAY_MS;
 var init_round = __esm({
   "src/cli/round.ts"() {
@@ -3676,8 +3647,6 @@ var init_round = __esm({
     init_api();
     init_mcp_client();
     init_flags();
-    init_resolve_worktree();
-    init_local_config();
     init_sync_approvals();
     RETRY_DELAY_MS = 1e3;
   }
@@ -4660,6 +4629,13 @@ async function runLocalMigration(projectPath) {
     "utf-8"
   );
   filesChanged.push(".codebyplan/e2e.json");
+  const eslintJson = {};
+  await writeFile10(
+    join14(projectPath, ".codebyplan", "eslint.json"),
+    JSON.stringify(eslintJson, null, 2) + "\n",
+    "utf-8"
+  );
+  filesChanged.push(".codebyplan/eslint.json");
   if (!deviceWrittenByHelper) {
     await writeFile10(
       join14(projectPath, ".codebyplan", "device.local.json"),
@@ -4895,6 +4871,7 @@ async function syncConfigToFile(repoId, projectPath, dryRun) {
   }
   const vendorPayload = {};
   const e2ePayload = {};
+  const eslintPayload = {};
   if (dryRun) {
     console.log("  Config would be updated (dry-run).");
     return;
@@ -4906,7 +4883,8 @@ async function syncConfigToFile(repoId, projectPath, dryRun) {
     { name: "git.json", payload: gitPayload },
     { name: "shipment.json", payload: shipmentPayload },
     { name: "vendor.json", payload: vendorPayload },
-    { name: "e2e.json", payload: e2ePayload, createOnly: true }
+    { name: "e2e.json", payload: e2ePayload, createOnly: true },
+    { name: "eslint.json", payload: eslintPayload, createOnly: true }
   ];
   let anyUpdated = false;
   for (const { name, payload, createOnly } of files) {
@@ -6788,8 +6766,9 @@ void (async () => {
   }
   if (arg === "login") {
     const { runLogin: runLogin2 } = await Promise.resolve().then(() => (init_login(), login_exports));
+    const admin = process.argv.includes("--admin");
     try {
-      await runLogin2();
+      await runLogin2({ admin });
       process.exit(0);
     } catch {
       process.exit(1);
@@ -6933,7 +6912,7 @@ void (async () => {
 
   Usage:
     codebyplan setup                 Interactive setup (OAuth + project init)
-    codebyplan login                 Authenticate via OAuth device-code flow
+    codebyplan login [--admin]        Authenticate via OAuth device-code flow
     codebyplan logout                Clear cached OAuth tokens
     codebyplan whoami                Show currently authenticated identity
     codebyplan upgrade-auth          Migrate legacy x-api-key MCP config to OAuth

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebyplan",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "CLI for CodeByPlan — AI-powered development planning and tracking",
   "type": "module",
   "bin": {

package/templates/hooks/README.md

@@ -228,18 +228,6 @@ Denies any `git stash` command (including `git -C <dir> stash` and `git stash po
 
 ---
 
-### `cbp-mcp-worktree-inject.sh` — PreToolUse, matcher `mcp__codebyplan__(update_task|complete_task|complete_round|update_checkpoint)`
-
-Auto-injects `caller_worktree_id` into CodeByPlan MCP mutation calls when it's missing, resolving it via `npx codebyplan resolve-worktree` (with `--fallback-from-branch`). Closes the manual worktree-pinning workaround so MCP writes pass the server-side worktree pre-guard without hand-editing every call.
-
-**Blocks vs warns**: neither — emits an `updatedInput` to add the field when resolvable, otherwise passes the call through unchanged (graceful passthrough preserves backwards-compat).
-
-**Skips when**: the call already carries `caller_worktree_id`, or no worktree can be resolved (both → clean passthrough). A no-op in repos that don't use the CodeByPlan MCP.
-
-**Opt out**: settings.json override removing this entry, or plugin disable.
-
----
-
 ### `cbp-mcp-round-sync.sh` — PostToolUse, matcher `mcp__codebyplan__complete_round`
 
 After a `complete_round` MCP call succeeds, reconciles the round's `files_changed[]` against `git status`: new files in the diff are added (unapproved), and approval records no longer in the diff are flagged `removed_from_diff` (never deleted — lifecycle preserved).
@@ -258,7 +246,7 @@ After a `complete_round` MCP call succeeds, reconciles the round's `files_change
 
 Test suite for the plugin's 10 registered hooks. Runs two passes:
 
-1. **Header check** — every registered hook (`lint-format-on-edit`, `test-coverage-gate`, `pre-commit-quality-gate`, `maestro-yaml-validate`, `notify`, `auto-test-hooks`, `mcp-migration-guard`, `validate-git-stash-deny`, `cbp-mcp-worktree-inject`, `cbp-mcp-round-sync`) carries the required `# Hook:` and `# Purpose:` header comments. `statusline` uses its own `# Claude Code Status Line` marker.
+1. **Header check** — every registered hook (`lint-format-on-edit`, `test-coverage-gate`, `pre-commit-quality-gate`, `maestro-yaml-validate`, `notify`, `auto-test-hooks`, `mcp-migration-guard`, `validate-git-stash-deny`, `cbp-mcp-round-sync`) carries the required `# Hook:` and `# Purpose:` header comments. `statusline` uses its own `# Claude Code Status Line` marker.
 2. **Functional smoke tests** — each hook is invoked with synthetic stdin matching its fast-path / graceful-degrade input; all must exit 0.
 
 Not in `hooks.json` — invoked indirectly via `auto-test-hooks.sh` on hook edits, or directly via `bash ${CLAUDE_PLUGIN_ROOT}/hooks/test-hooks.sh`.

package/templates/hooks/cbp-test-coverage-gate.sh

@@ -64,6 +64,14 @@ while IFS= read -r FILE; do
     continue
   fi
 
+  # Skip files under a __tests__/ directory — fixtures, helpers, setup, and
+  # other test infrastructure are imported by the test files that exercise
+  # them; requiring a dedicated .test.ts for a fixture is nonsensical.
+  if echo "$FILE" | grep -qE '/__tests__/'; then
+    SKIPPED=$((SKIPPED + 1))
+    continue
+  fi
+
   # Skip infrastructure / generated / config files (generic skips — harmless if user doesn't have these dirs)
   if echo "$FILE" | grep -qE '^\.claude/|^docs/|^supabase/|\.config\.|\.json$|\.md$|\.ya?ml$|\.sh$|\.scss$|\.css$'; then
     continue

package/templates/hooks/cbp-test-hooks.sh

@@ -207,48 +207,6 @@ else
   fi
 fi
 
-# --- cbp-mcp-worktree-inject.sh ---
-
-if [ ! -f "$HOOKS_DIR/cbp-mcp-worktree-inject.sh" ]; then
-  test_result "cbp-mcp-worktree-inject.sh present" "passed" "missing"
-else
-  test_result "cbp-mcp-worktree-inject.sh present" "passed" "passed"
-
-  FIRST_LINE=$(head -1 "$HOOKS_DIR/cbp-mcp-worktree-inject.sh")
-  if echo "$FIRST_LINE" | grep -q '^#!/'; then
-    test_result "cbp-mcp-worktree-inject.sh has shebang" "passed" "passed"
-  else
-    test_result "cbp-mcp-worktree-inject.sh has shebang" "passed" "missing"
-  fi
-
-  if grep -q '@scope: org-shared' "$HOOKS_DIR/cbp-mcp-worktree-inject.sh"; then
-    test_result "cbp-mcp-worktree-inject.sh has @scope: org-shared" "passed" "passed"
-  else
-    test_result "cbp-mcp-worktree-inject.sh has @scope: org-shared" "passed" "missing"
-  fi
-
-  FIXTURES_DIR="$HOOKS_DIR/__test-fixtures__/cbp-mcp-worktree-inject"
-  if [ -d "$FIXTURES_DIR" ]; then
-    # already-has-id.json — expect exit 0 (passthrough)
-    ACTUAL_EXIT=$(bash "$HOOKS_DIR/cbp-mcp-worktree-inject.sh" < "$FIXTURES_DIR/already-has-id.json" >/dev/null 2>&1; echo $?)
-    if [ "$ACTUAL_EXIT" = "0" ]; then
-      test_result "cbp-mcp-worktree-inject.sh already-has-id exits 0" "passed" "passed"
-    else
-      test_result "cbp-mcp-worktree-inject.sh already-has-id exits 0" "passed" "failed (exit $ACTUAL_EXIT)"
-    fi
-
-    # missing-id-both-empty.json — resolvers return empty (in test env), expect exit 0
-    ACTUAL_EXIT=$(bash "$HOOKS_DIR/cbp-mcp-worktree-inject.sh" < "$FIXTURES_DIR/missing-id-both-empty.json" >/dev/null 2>&1; echo $?)
-    if [ "$ACTUAL_EXIT" = "0" ]; then
-      test_result "cbp-mcp-worktree-inject.sh missing-id passthrough exits 0" "passed" "passed"
-    else
-      test_result "cbp-mcp-worktree-inject.sh missing-id passthrough exits 0" "passed" "failed (exit $ACTUAL_EXIT)"
-    fi
-  else
-    test_result "cbp-mcp-worktree-inject.sh fixtures dir present" "passed" "missing"
-  fi
-fi
-
 # --- cbp-mcp-round-sync.sh ---
 
 if [ ! -f "$HOOKS_DIR/cbp-mcp-round-sync.sh" ]; then

package/templates/hooks/hooks.json

@@ -35,15 +35,6 @@
             "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/cbp-mcp-migration-guard.sh"
           }
         ]
-      },
-      {
-        "matcher": "mcp__codebyplan__(update_task|complete_task|complete_round|update_checkpoint)",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/cbp-mcp-worktree-inject.sh"
-          }
-        ]
       }
     ],
     "PostToolUse": [

package/templates/skills/cbp-checkpoint-start/SKILL.md

@@ -57,7 +57,7 @@ This mirrors the CHK-104 hard-lock model — never wrest a checkpoint from a liv
 
 If the checkpoint is already `active` AND `worktree_id` already equals `CALLER_WT` (the Step 3 no-op row), skip this step entirely and proceed to Step 5 — nothing to write.
 
-Otherwise set the checkpoint `active` via MCP `update_checkpoint(checkpoint_id, status: "active"`, plus `worktree_id: CALLER_WT` when claiming per Step 3, plus `caller_worktree_id: CALLER_WT` so the hard-lock pre-guard accepts the call (omit `caller_worktree_id` only when `CALLER_WT` is empty). If the checkpoint was already `active` but a claim is still needed, skip the status write and only write `worktree_id`.
+Otherwise set the checkpoint `active` via MCP `update_checkpoint(checkpoint_id, status: "active"`, plus `worktree_id: CALLER_WT` when claiming per Step 3. The server resolves the caller's worktree identity from the JWT/ctx (CHK-140 TASK-3 — `caller_worktree_id` input field removed). If the checkpoint was already `active` but a claim is still needed, skip the status write and only write `worktree_id`.
 
 ### Step 5: Route
 
@@ -78,7 +78,7 @@ Show a one-line confirmation before routing:
 ## Integration
 
 - **Reads**: MCP `get_checkpoints`, `get_tasks`; `npx codebyplan resolve-worktree`
-- **Writes**: MCP `update_checkpoint` (status + worktree_id, with caller_worktree_id pre-guard)
+- **Writes**: MCP `update_checkpoint` (status + worktree_id; server resolves caller worktree from JWT/ctx)
 - **Triggered by**: `/cbp-checkpoint-plan` (auto when claimed at create), `/cbp-todo` (planned-but-pending gate), or user directly
 - **Triggers**: `/cbp-task-start` (auto when claimed), or `/cbp-checkpoint-plan` (when the checkpoint is unplanned)
 - **Never**: plans or creates tasks — that is `/cbp-checkpoint-plan`

package/templates/skills/cbp-session-start/SKILL.md

@@ -49,7 +49,7 @@ RESOLVE_JSON=$(npx codebyplan resolve-worktree --json)
 
 Extract `worktree_id` and `error_kind` from the JSON output.
 
-- `error_kind` is `null` or `"tuple_miss"` → healthy. `WORKTREE_ID` = `worktree_id` (may be `null`: a legitimate main-repo or unregistered-worktree case — proceed normally; downstream hard-lock pre-guards may reject mutations on assigned rows).
+- `error_kind` is `null` or `"tuple_miss"` → healthy. `WORKTREE_ID` = `worktree_id` (may be `null`: a legitimate main-repo or unregistered-worktree case — proceed normally; the server resolves worktree identity from the JWT/ctx, falling back to the repo main-worktree when no specific worktree is matched).
 - `error_kind` is `local_config_read_failed`, `local_config_write_failed`, `legacy_file_blocks_dir`, `api_failed`, `git_failed`, or `unhandled` → **broken local state**. Hold the `error_kind` for Step 6 to display as a distress warning. Session continues (non-blocking — unlike `/cbp-todo`, session-start does NOT hard-stop on a non-tuple-miss distress).
 
 Pass `WORKTREE_ID` to MCP tools that support it. Null `WORKTREE_ID` means the (device, path, branch) tuple is unregistered — note this for Step 6.

package/templates/skills/{cbp-e2e-setup → cbp-setup-e2e}/SKILL.md

@@ -1,6 +1,6 @@
 ---
 scope: org-shared
-name: cbp-e2e-setup
+name: cbp-setup-e2e
 description: Detect installed E2E frameworks, ask which to enable, record credentials source (gitignored env-file path + var names only, never secrets), and write/refresh .codebyplan/e2e.json. Interactive, idempotent.
 argument-hint: "[--force]"
 model: sonnet

package/templates/skills/cbp-setup-eslint/SKILL.md

@@ -0,0 +1,199 @@
+---
+scope: org-shared
+name: cbp-setup-eslint
+description: Detect each app's tech stack, resolve matching DB ESLint presets, confirm which to enable per app, run `codebyplan eslint init` to generate eslint.config.mjs, and write/refresh .codebyplan/eslint.json. Interactive, idempotent.
+argument-hint: "[--force]"
+model: sonnet
+effort: xhigh
+allowed-tools: Read, Write, Edit, Bash(cat *), Bash(jq *), Bash(test *), Bash(ls *), Bash(mkdir *), Bash(cp *), Bash(echo *), Bash(mv *), Bash(npx codebyplan eslint *), AskUserQuestion, mcp__codebyplan__get_repos, mcp__codebyplan__get_eslint_presets
+---
+
+# ESLint Setup
+
+Configure ESLint flat config (`eslint.config.mjs`) across the repo's apps: detect each
+app's tech stack, resolve the DB ESLint presets that match it, generate per-app configs via
+`codebyplan eslint init`, and record the enabled presets in `.codebyplan/eslint.json` so the
+setup is reproducible and refreshes idempotently.
+
+Invoke at any time. Already-configured apps are preserved unless `--force` is passed.
+Pass `--force` to re-ask every app and re-resolve presets from scratch.
+
+The DB ESLint presets are the source of truth for rule bodies; `.codebyplan/eslint.json`
+only records *which* presets are enabled per app (the rules live in the generated
+`eslint.config.mjs` and the DB). See `reference/*.md` for the latest official flat-config
+setup per stack — including stacks that have **no preset yet** (manual-config guidance).
+
+## Arguments
+
+Inspect `$ARGUMENTS` for `--force`. If present, set `force_mode = true`.
+Absent: idempotent mode — preserve existing `apps[*]` entries in `.codebyplan/eslint.json`,
+skip re-asking already-configured apps.
+
+## Step 1 — Detect apps + per-app tech
+
+Run two detection signals and merge:
+
+**Signal A — DB tech_stack** via `mcp__codebyplan__get_repos` (match `repo_id` from
+`.codebyplan/repo.json`). Read the repo's `tech_stack`:
+- `tech_stack.apps[]` — each `{ name, path, stack[] }` is one app/package (monorepo).
+- `tech_stack.flat[]` — the deduped repo-wide stack (single-app repos, or when `apps[]` is empty).
+
+**Signal B — Filesystem fallback** (when `apps[]` is empty or stale). Discover workspaces the
+same way `tech-detect.ts` does, then probe each app's `package.json`:
+
+```bash
+# workspace globs → app dirs that contain a package.json
+cat pnpm-workspace.yaml 2>/dev/null            # packages: [...] globs
+jq -r '.workspaces[]?' package.json 2>/dev/null # or package.json#workspaces
+```
+
+For each app dir, read `package.json` dependencies to infer the stack (next → Next.js,
+react → React, @nestjs/* → NestJS, vitest → Vitest, jest → Jest, @playwright/test →
+Playwright, tailwindcss → Tailwind, expo → Expo, etc.). A single-app repo is one target
+with `source_path: "."` and `app: "root"`.
+
+**Signal C — Read existing `.codebyplan/eslint.json`** for the idempotent merge:
+
+```bash
+cat .codebyplan/eslint.json 2>/dev/null || echo '{}'
+```
+
+An app already present under `apps[<source_path>]` is "configured"; in non-`--force` mode it
+is skipped in Step 3 (presets preserved verbatim).
+
+## Step 2 — Resolve matched presets
+
+Call `mcp__codebyplan__get_eslint_presets` with `repo_id`. The response gives:
+- `presets[]` — all system presets (base, nextjs, react, node, cli, testing, testing-react, testing-e2e).
+- `matched[]` — the subset whose `tech_match` (requires / excludes / requires_capabilities) the
+  repo's DB tech_stack satisfies. **Use this — do not re-implement the matching client-side.**
+
+`matched[]` is repo-wide. Attribute presets to apps by intersecting each app's detected tech
+with each preset's `tech_match.requires` (e.g. `nextjs` → apps with Next.js; `node`/`cli` →
+the Node/CLI packages; `testing-e2e` → apps with Playwright). The `base` preset applies to
+every TypeScript app.
+
+**Gap stacks have NO preset.** NestJS, React Native/Expo, Jest, Tailwind, and
+WebdriverIO/Mocha are real stacks with no system preset. When an app's tech includes one,
+flag it in Step 3 and point at its `reference/*.md` for manual setup — never silently drop it.
+
+## Step 3 — Confirm presets per app
+
+For each detected app NOT already configured (or every app in `--force` mode), present its
+matched presets and ask via AskUserQuestion (one batch per app, matched pre-checked):
+
+```
+App: apps/web  (Next.js + React + SCSS + Playwright + Vitest)
+Enable which ESLint presets?
+  [x] base          (TypeScript + security + Prettier)
+  [x] nextjs        (Core Web Vitals + jsx-a11y + import order)
+  [x] testing       (Vitest)
+  [x] testing-react (Testing Library + jest-dom)
+  [x] testing-e2e   (Playwright)
+Gap stacks with no preset (manual setup — see reference/):
+  · tailwind  → reference/tailwind.md   (if this app uses Tailwind)
+```
+
+Record the confirmed preset-name list per app. Toggling is allowed; an app may opt out of a
+matched preset or in to an unmatched one.
+
+## Step 4 — Generate config (`codebyplan eslint init`)
+
+Offer to run the CLI, which detects tech, resolves presets, generates each
+`eslint.config.mjs`, installs missing deps, and saves the DB config:
+
+```bash
+npx codebyplan eslint init
+```
+
+**Degrade gracefully.** The CLI is sometimes unavailable (OAuth/MCP env, stale bin). If it
+errors or is absent, do NOT hard-fail — print the command for the user to run manually and
+continue to Step 5 (the `.codebyplan/eslint.json` record is written regardless). For gap
+stacks, point the user at the matching `reference/*.md` to hand-author the config.
+
+## Step 5 — Write `.codebyplan/eslint.json`
+
+Build the payload conforming to the `EslintLocalConfig` schema
+(`packages/codebyplan-package/src/lib/types.ts`): an `apps` map keyed by `source_path`, each
+value an `EslintAppConfig` `{ app, enabled_presets[], rule_overrides?, config_path, reference_docs? }`.
+
+Idempotency rule: deep-merge the new per-app entries onto the existing `apps` map so apps
+skipped by the Step 3 gate keep their prior entry. Assemble in the shell, then write
+atomically (tmp + mv) so the file is never left partial:
+
+```bash
+EXISTING_APPS=$(jq -c '.apps // {}' .codebyplan/eslint.json 2>/dev/null || echo '{}')
+APPS_JSON=$(echo "$EXISTING_APPS" | jq -c --argjson new "$NEW_APPS_JSON" '. * $new')
+jq -n --argjson apps "$APPS_JSON" '{apps: $apps}' \
+  > .codebyplan/eslint.json.tmp && mv .codebyplan/eslint.json.tmp .codebyplan/eslint.json
+```
+
+Example populated entry:
+
+```json
+{
+  "apps": {
+    "apps/web": {
+      "app": "web",
+      "enabled_presets": ["base", "nextjs", "testing", "testing-react", "testing-e2e"],
+      "config_path": "apps/web/eslint.config.mjs",
+      "reference_docs": ["base", "nextjs", "testing-react", "e2e"]
+    }
+  }
+}
+```
+
+Only the `apps` field is written — `EslintLocalConfig` defines no other. Never store rule
+bodies here; they live in the DB presets and the generated `eslint.config.mjs`.
+
+## Step 6 — Verify and report
+
+Re-read `.codebyplan/eslint.json` and emit a per-app summary:
+
+```
+ESLint Setup — Complete
+
+App                          | Presets                              | Config              | Gaps
+---------------------------- | ------------------------------------ | ------------------- | --------
+apps/web                     | base, nextjs, testing, testing-react | apps/web/eslint…mjs | —
+packages/codebyplan-package  | base, node, cli, testing             | …/eslint.config.mjs | —
+
+eslint.json written to .codebyplan/eslint.json
+
+Per-stack setup references — see reference docs:
+  base/typescript → reference/base.md      nextjs → reference/nextjs.md
+  react           → reference/react.md      node   → reference/node.md
+  nestjs          → reference/nestjs.md      cli    → reference/cli.md
+  tailwind        → reference/tailwind.md    expo   → reference/react-native.md
+  vitest          → reference/vitest.md      jest   → reference/jest.md
+  testing-react   → reference/testing-react.md   e2e → reference/e2e.md
+```
+
+If `codebyplan eslint init` was skipped (CLI unavailable), say so and restate the manual
+command + which apps still need their `eslint.config.mjs` generated.
+
+## Key Rules
+
+- DB presets are the source of truth for rule bodies — `.codebyplan/eslint.json` records only
+  which presets are enabled per app
+- `get_eslint_presets` `matched[]` drives preset resolution — never re-implement tech matching
+- Gap stacks (NestJS, Expo, Jest, Tailwind, WebdriverIO/Mocha) have no preset — point at
+  `reference/*.md`, never silently skip
+- `codebyplan eslint init` failure is non-fatal — print the manual command and still write eslint.json
+- Atomic write (tmp + mv) — never leave eslint.json partial
+- Reference docs track the **latest official** flat-config setup and flag where CBP's DB
+  presets diverge (e.g. ESLint v10 + `eslint-plugin-react-hooks@7` bundled compiler rules)
+
+## Additional resources
+
+- TypeScript foundation (ESLint v10 flat config): [reference/base.md](reference/base.md)
+- Next.js: [reference/nextjs.md](reference/nextjs.md) · React (+ Storybook): [reference/react.md](reference/react.md)
+- Node / Hono / Express: [reference/node.md](reference/node.md) · NestJS: [reference/nestjs.md](reference/nestjs.md)
+- CLI tools: [reference/cli.md](reference/cli.md) · Tailwind CSS: [reference/tailwind.md](reference/tailwind.md)
+- React Native / Expo: [reference/react-native.md](reference/react-native.md)
+- Vitest: [reference/vitest.md](reference/vitest.md) · Jest: [reference/jest.md](reference/jest.md)
+- Testing Library + jest-dom: [reference/testing-react.md](reference/testing-react.md)
+- E2E (Playwright / WebdriverIO / Mocha): [reference/e2e.md](reference/e2e.md)
+- ESLint local-config schema: `packages/codebyplan-package/src/lib/types.ts` (`EslintLocalConfig`)
+- DB presets + generator: `mcp__codebyplan__get_eslint_presets`, `codebyplan eslint init`
+- VS Code extension lint is not yet covered by a reference doc — use `reference/base.md` + `reference/node.md`.