@haystackeditor/cli 0.14.1 → 0.14.3

package/dist/commands/setup.js

@@ -24,7 +24,19 @@ import { trackError, trackSetupEvent } from '../utils/telemetry.js';
 // Constants
 // =============================================================================
 const HAYSTACK_API = 'https://haystackeditor.com';
+// User-level GitHub calls (repo listing, App-installation check, token
+// verification) go direct: they're scoped to the authenticated user, so OAuth
+// App Policy org restrictions don't apply to them.
 const GITHUB_API = 'https://api.github.com';
+// Per-repo reads + writes go through the auth-worker proxy, which swaps in the
+// GitHub App installation token server-side. That's what lets the config write
+// and the bootstrap PR succeed on orgs that restrict the OAuth app — the same
+// path the web onboarding wizard uses. Authenticated with the CLI's GitHub
+// token via `Authorization: Bearer` (the proxy validates it against GitHub
+// /user, then uses its own installation/OAuth token upstream). Commits + PRs
+// created this way are authored by haystack[bot], which is the intended
+// behavior for onboarding config and matches the web wizard.
+const GITHUB_PROXY = `${HAYSTACK_API}/api/github`;
 const CATEGORY_LABELS = {
     testing: 'Testing',
     style: 'Style',
@@ -33,16 +45,11 @@ const CATEGORY_LABELS = {
     docs: 'Documentation',
     other: 'Other',
 };
-const SIGNAL_TYPE_LABELS = {
-    ci_check: 'CI Check',
-    bot_review: 'Bot Review',
-    status_check: 'Status Check',
-};
-const POLICY_TYPE_LABELS = {
-    approval_count: 'Approval Count',
-    codeowner_review: 'Codeowner Review',
-    team_review: 'Team Review',
-    area_owner: 'Area Owner',
+const SEVERITY_LABELS = {
+    critical: 'Critical',
+    high: 'High',
+    medium: 'Medium',
+    low: 'Low',
 };
 async function fetchUserRepos(token) {
     const repos = [];
@@ -71,27 +78,6 @@ async function fetchUserRepos(token) {
         .filter((r) => !r.archived)
         .map((r) => r.full_name);
 }
-async function fetchExistingConfig(owner, repo, token) {
-    const response = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/contents/.haystack.json`, {
-        headers: {
-            Authorization: `Bearer ${token}`,
-            Accept: 'application/vnd.github.v3+json',
-            'User-Agent': 'Haystack-CLI',
-        },
-    });
-    if (response.status === 404)
-        return null;
-    if (!response.ok)
-        throw new Error(`Failed to fetch config: ${response.status}`);
-    const data = (await response.json());
-    const raw = Buffer.from(data.content, 'base64').toString('utf-8');
-    try {
-        return { config: JSON.parse(raw), sha: data.sha };
-    }
-    catch {
-        throw new Error('existing .haystack.json is malformed JSON — delete or fix it manually');
-    }
-}
 // Bootstrap PR constants — kept in sync with the web wizard
 // (src/features/onboarding/services/onboardingApi.ts). The branch prefix and
 // the two labels are load-bearing: the worker's bootstrap merge path
@@ -100,14 +86,19 @@ const CONFIG_COMMIT_MSG = 'chore: configure Haystack via CLI setup wizard';
 const AUTO_MERGE_LABEL = 'haystack:auto-merge';
 const ONBOARDING_BOOTSTRAP_LABEL = 'haystack:onboarding-bootstrap';
 const BOOTSTRAP_PR_TITLE = 'Configure Haystack';
-const BOOTSTRAP_PR_BODY = 'This PR was opened automatically by the Haystack CLI setup wizard because the default branch is protected.\n\n' +
+const BOOTSTRAP_PR_BODY_INTRO = 'This PR was opened automatically by the Haystack CLI setup wizard because the default branch is protected.\n\n' +
     'It adds the Haystack onboarding config:\n' +
-    '- `.haystack.json` — enables the Haystack merge queue and review automation\n' +
-    '- `.entire/settings.json` — enables AI-session trace capture (powers intent-drift triage)\n\n' +
-    'Both files are committed to this branch; `.entire/settings.json` lands in a follow-up commit ' +
-    'during setup step 7, so it may not be present the instant the PR opens.\n\n' +
-    'Haystack will bootstrap-merge this PR automatically once the labels are applied. ' +
+    '- `.haystack/pr-rules.yml` — rules Haystack enforces on every PR\n' +
+    '- `.haystack/review-policy.md` — path-scoped review policies + review instructions\n' +
+    '- `.haystack.json` — your Haystack merge-queue settings\n' +
+    '- `.entire/settings.json` — enables AI-session trace capture (powers intent-drift triage)\n\n';
+// Auto-merge ON: Haystack bootstrap-merges the PR itself once labeled.
+const BOOTSTRAP_PR_OUTRO_AUTOMERGE = 'Haystack will bootstrap-merge this PR automatically once the labels are applied. ' +
     'You can tweak the files from GitHub or re-run `haystack setup` anytime.';
+// Auto-merge OFF: the repo opted out of auto-merge, so this PR is NOT enrolled
+// (no labels). It waits for the user to review and merge it themselves.
+const BOOTSTRAP_PR_OUTRO_MANUAL = 'Auto-merge is off for this repo, so this PR is yours to review: check the files and merge it ' +
+    'whenever you\'re ready. You can tweak them from GitHub or re-run `haystack setup` anytime.';
 /**
  * Encode a branch name for use in a URL path while preserving `/`
  * separators (e.g. `release/stable`). encodeURIComponent on the whole
@@ -135,7 +126,7 @@ async function isBranchProtected(owner, repo, branch, token) {
     const headers = ghHeaders(token);
     const enc = encodeBranchPath(branch);
     // Legacy branch protection — the `protected` boolean is authoritative.
-    const branchRes = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/branches/${enc}`, { headers });
+    const branchRes = await fetch(`${GITHUB_PROXY}/repos/${owner}/${repo}/branches/${enc}`, { headers });
     if (branchRes.ok) {
         const data = (await branchRes.json());
         if (data.protected === true)
@@ -146,7 +137,7 @@ async function isBranchProtected(owner, repo, branch, token) {
     }
     // Repository rulesets — `rules/branches` collapses every active rule on
     // the branch into one list. A `pull_request` rule = "must merge via PR".
-    const rulesRes = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/rules/branches/${enc}`, { headers });
+    const rulesRes = await fetch(`${GITHUB_PROXY}/repos/${owner}/${repo}/rules/branches/${enc}`, { headers });
     if (rulesRes.ok) {
         const rules = (await rulesRes.json());
         if (rules.some((r) => r.type === 'pull_request'))
@@ -166,7 +157,7 @@ function ghHeaders(token) {
     };
 }
 async function getDefaultBranch(owner, repo, token) {
-    const res = await fetch(`${GITHUB_API}/repos/${owner}/${repo}`, { headers: ghHeaders(token) });
+    const res = await fetch(`${GITHUB_PROXY}/repos/${owner}/${repo}`, { headers: ghHeaders(token) });
     if (!res.ok) {
         throw new Error(`Failed to read repo metadata: ${res.status} — ${await res.text()}`);
     }
@@ -177,14 +168,14 @@ async function getBranchSha(owner, repo, branch, token) {
     // path — encodeURIComponent would turn `release/stable` into
     // `release%2Fstable` and 404. encodeBranchPath escapes each segment but
     // keeps the `/` separators.
-    const res = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/git/ref/heads/${encodeBranchPath(branch)}`, { headers: ghHeaders(token) });
+    const res = await fetch(`${GITHUB_PROXY}/repos/${owner}/${repo}/git/ref/heads/${encodeBranchPath(branch)}`, { headers: ghHeaders(token) });
     if (!res.ok) {
         throw new Error(`Failed to read branch ref: ${res.status} — ${await res.text()}`);
     }
     return (await res.json()).object.sha;
 }
 async function createBranch(owner, repo, branch, sha, token) {
-    const res = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/git/refs`, {
+    const res = await fetch(`${GITHUB_PROXY}/repos/${owner}/${repo}/git/refs`, {
         method: 'POST',
         headers: ghHeaders(token),
         body: JSON.stringify({ ref: `refs/heads/${branch}`, sha }),
@@ -193,11 +184,13 @@ async function createBranch(owner, repo, branch, sha, token) {
         throw new Error(`Failed to create branch: ${res.status} — ${await res.text()}`);
     }
 }
-async function createBootstrapPR(owner, repo, head, base, token) {
-    const res = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/pulls`, {
+async function createBootstrapPR(owner, repo, head, base, token, autoMergeEnabled) {
+    const body = BOOTSTRAP_PR_BODY_INTRO +
+        (autoMergeEnabled ? BOOTSTRAP_PR_OUTRO_AUTOMERGE : BOOTSTRAP_PR_OUTRO_MANUAL);
+    const res = await fetch(`${GITHUB_PROXY}/repos/${owner}/${repo}/pulls`, {
         method: 'POST',
         headers: ghHeaders(token),
-        body: JSON.stringify({ title: BOOTSTRAP_PR_TITLE, head, base, body: BOOTSTRAP_PR_BODY }),
+        body: JSON.stringify({ title: BOOTSTRAP_PR_TITLE, head, base, body }),
     });
     if (!res.ok) {
         throw new Error(`Failed to open PR: ${res.status} — ${await res.text()}`);
@@ -222,14 +215,14 @@ async function createBootstrapPR(owner, repo, head, base, token) {
 async function createCommitWithFiles(owner, repo, baseSha, files, message, token) {
     const headers = ghHeaders(token);
     // The new tree extends the base commit's tree.
-    const baseCommitRes = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/git/commits/${baseSha}`, { headers });
+    const baseCommitRes = await fetch(`${GITHUB_PROXY}/repos/${owner}/${repo}/git/commits/${baseSha}`, { headers });
     if (!baseCommitRes.ok) {
         throw new Error(`Failed to read base commit: ${baseCommitRes.status} — ${await baseCommitRes.text()}`);
     }
     const baseTreeSha = (await baseCommitRes.json()).tree.sha;
     // One blob per file.
     const treeEntries = await Promise.all(files.map(async (f) => {
-        const blobRes = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/git/blobs`, {
+        const blobRes = await fetch(`${GITHUB_PROXY}/repos/${owner}/${repo}/git/blobs`, {
             method: 'POST',
             headers,
             body: JSON.stringify({ content: f.content, encoding: 'utf-8' }),
@@ -240,7 +233,7 @@ async function createCommitWithFiles(owner, repo, baseSha, files, message, token
         const blob = (await blobRes.json());
         return { path: f.path, mode: '100644', type: 'blob', sha: blob.sha };
     }));
-    const treeRes = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/git/trees`, {
+    const treeRes = await fetch(`${GITHUB_PROXY}/repos/${owner}/${repo}/git/trees`, {
         method: 'POST',
         headers,
         body: JSON.stringify({ base_tree: baseTreeSha, tree: treeEntries }),
@@ -249,7 +242,7 @@ async function createCommitWithFiles(owner, repo, baseSha, files, message, token
         throw new Error(`Failed to create tree: ${treeRes.status} — ${await treeRes.text()}`);
     }
     const tree = (await treeRes.json());
-    const commitRes = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/git/commits`, {
+    const commitRes = await fetch(`${GITHUB_PROXY}/repos/${owner}/${repo}/git/commits`, {
         method: 'POST',
         headers,
         body: JSON.stringify({ message, tree: tree.sha, parents: [baseSha] }),
@@ -280,7 +273,7 @@ async function buildEntireSettingsContent(repoFullName, token) {
     let originalContent = '';
     let exists = false;
     let existingSha = null;
-    const getResp = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/contents/.entire/settings.json`, { headers });
+    const getResp = await fetch(`${GITHUB_PROXY}/repos/${owner}/${repo}/contents/.entire/settings.json`, { headers });
     if (getResp.ok) {
         exists = true;
         const data = (await getResp.json());
@@ -325,7 +318,7 @@ async function addBootstrapLabels(owner, repo, prNumber, prUrl, token) {
     const labels = [AUTO_MERGE_LABEL, ONBOARDING_BOOTSTRAP_LABEL];
     let lastErr = '';
     for (let attempt = 1; attempt <= 3; attempt++) {
-        const res = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/issues/${prNumber}/labels`, {
+        const res = await fetch(`${GITHUB_PROXY}/repos/${owner}/${repo}/issues/${prNumber}/labels`, {
             method: 'POST',
             headers: ghHeaders(token),
             body: JSON.stringify({ labels }),
@@ -345,28 +338,70 @@ async function addBootstrapLabels(owner, repo, prNumber, prUrl, token) {
         `Add these labels to the PR manually so Haystack picks it up: ${labels.join(', ')}. ` +
         `Don't re-run \`haystack setup\` — that opens a duplicate PR.`);
 }
+/** Wraps a contents-API write failure with its HTTP status so the caller can
+ *  distinguish a protection rejection (409/422 → PR fallback) from a genuine
+ *  error (→ surface it). */
+class GitHubWriteError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`GitHub write failed: ${status}`);
+        this.status = status;
+        this.body = body;
+        this.name = 'GitHubWriteError';
+    }
+}
+/** Read the blob SHA of an existing file (needed to update it). Non-OK (incl.
+ *  404 = file doesn't exist yet) returns null; the subsequent PUT then creates
+ *  the file, and surfaces a real error if the write itself fails. */
+async function fetchFileSha(owner, repo, path, token) {
+    const res = await fetch(`${GITHUB_PROXY}/repos/${owner}/${repo}/contents/${path}`, { headers: ghHeaders(token) });
+    if (!res.ok)
+        return null;
+    const data = (await res.json());
+    return data.sha ?? null;
+}
+/** PUT a single file to the default branch via the contents API. Throws
+ *  GitHubWriteError on any non-OK response so the caller can branch on status. */
+async function putFile(owner, repo, path, content, message, sha, token) {
+    const body = {
+        message,
+        content: Buffer.from(content).toString('base64'),
+    };
+    if (sha)
+        body.sha = sha;
+    const res = await fetch(`${GITHUB_PROXY}/repos/${owner}/${repo}/contents/${path}`, {
+        method: 'PUT',
+        headers: ghHeaders(token),
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        throw new GitHubWriteError(res.status, await res.text().catch(() => ''));
+    }
+}
 /**
- * Protected-branch fallback: build ONE commit containing both onboarding
- * files (`.haystack.json` + `.entire/settings.json`) via the Git Data API,
- * CREATE a branch ref at it, open a PR, and apply the auto-merge + bootstrap
- * labels.
+ * Protected-branch fallback: build ONE commit containing ALL the onboarding
+ * files (`configFiles` + `.entire/settings.json`) via the Git Data API, CREATE
+ * a branch ref at it, open a PR, and apply the auto-merge + bootstrap labels.
  *
- * Why both files in one commit: a ruleset whose `pull_request` rule targets
+ * Why every file in one commit: a ruleset whose `pull_request` rule targets
  * `~ALL` branches blocks ref *updates* on every branch — so you can neither
  * commit to the default branch NOR add a second commit to the onboarding
- * branch afterward. The only thing allowed is *creating* a ref. So both
- * bootstrap-critical files (`.haystack.json` enables the merge queue,
- * `.entire/settings.json` enables the trace capture intent-drift triage
- * runs on) must land in the single commit the branch is created at.
+ * branch afterward. The only thing allowed is *creating* a ref. So all the
+ * bootstrap-critical files (`.haystack/pr-rules.yml`, `.haystack/review-policy.md`,
+ * `.haystack.json` enables the merge queue, `.entire/settings.json` enables the
+ * trace capture intent-drift triage runs on) must land in the single commit the
+ * branch is created at. Mirrors the web wizard's PR-fallback path.
  */
-async function openBootstrapConfigPR(owner, repo, configContent, token, defaultBranch) {
+async function openBootstrapConfigPR(owner, repo, configFiles, token, defaultBranch, autoMergeEnabled) {
     const baseSha = await getBranchSha(owner, repo, defaultBranch, token);
     // Branch prefix MUST stay `haystack/onboarding-` — the worker keys off it.
     // The timestamp avoids collisions when setup is re-run.
     const branchName = `haystack/onboarding-${Date.now()}`;
-    const files = [
-        { path: '.haystack.json', content: configContent },
-    ];
+    const files = configFiles.map((f) => ({
+        path: f.path,
+        content: f.content,
+    }));
     // Bundle .entire/settings.json into the same commit — on a ~ALL ruleset
     // we can't add it later. It's repo-level config (independent of whether
     // this dev installs the Entire binary locally), so it rides along here.
@@ -399,137 +434,137 @@ async function openBootstrapConfigPR(owner, repo, configContent, token, defaultB
     }
     const commitSha = await createCommitWithFiles(owner, repo, baseSha, files, CONFIG_COMMIT_MSG, token);
     await createBranch(owner, repo, branchName, commitSha, token);
-    const pr = await createBootstrapPR(owner, repo, branchName, defaultBranch, token);
-    await addBootstrapLabels(owner, repo, pr.number, pr.html_url, token);
+    const pr = await createBootstrapPR(owner, repo, branchName, defaultBranch, token, autoMergeEnabled);
+    // Only enroll the PR for auto-merge when the repo hasn't opted out. Applying
+    // the labels on an auto-merge-disabled repo would force-merge a config PR the
+    // user wants to review themselves (e.g. a repo set auto-merge-off via the web
+    // wizard, then re-run through `haystack setup`). Without labels the worker
+    // never picks it up; the PR is still opened and analyzed, it just waits.
+    if (autoMergeEnabled) {
+        await addBootstrapLabels(owner, repo, pr.number, pr.html_url, token);
+    }
     return { prUrl: pr.html_url, entireSettingsBundled };
 }
 /**
- * Write `.haystack.json` to a repo. Tries a direct commit to the default
- * branch first; on a protected-branch / ruleset error, falls back to opening
- * a bootstrap PR (branch + commit + PR + labels) so setup still completes.
+ * Write the onboarding config files to a repo. Tries a direct commit per file
+ * to the default branch first; on a protected-branch / ruleset rejection
+ * (409/422 confirmed by a structured protection probe) falls back to ONE
+ * bootstrap PR containing all files. Mirrors the web wizard's
+ * writeOnboardingFiles.
  *
  * Returns `{ bootstrapPR }` when the PR fallback was used (so the caller can
- * thread the branch into step 7), `{}` on a clean direct commit.
+ * thread the branch into step 7), `{}` on clean direct commits.
  */
-async function writeConfigToRepo(owner, repo, config, existingSha, token) {
-    const content = JSON.stringify(config, null, 2) + '\n';
-    const body = {
-        message: CONFIG_COMMIT_MSG,
-        content: Buffer.from(content).toString('base64'),
-    };
-    if (existingSha)
-        body.sha = existingSha;
-    const response = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/contents/.haystack.json`, {
-        method: 'PUT',
-        headers: ghHeaders(token),
-        body: JSON.stringify(body),
-    });
-    if (response.ok)
+async function writeOnboardingFilesToRepo(owner, repo, files, autoMergeEnabled, token) {
+    // Look up existing SHAs once on the default branch so updates to files that
+    // already exist carry the right sha. Done before any write so a mid-loop
+    // failure doesn't leave us guessing.
+    const shaByPath = new Map();
+    for (const f of files) {
+        shaByPath.set(f.path, await fetchFileSha(owner, repo, f.path, token));
+    }
+    try {
+        for (const f of files) {
+            await putFile(owner, repo, f.path, f.content, f.message, shaByPath.get(f.path) ?? null, token);
+        }
         return {};
-    const err = await response.text();
-    // A 409/422 means *something* rejected the direct commit. Probe GitHub's
-    // structured protection signals to find out whether it was branch
-    // protection / a ruleset (→ open a bootstrap PR) or a genuine bad request
-    // (→ surface the error). Other statuses (auth, 404, 5xx) are never a
-    // protected-branch situation, so don't bother probing.
-    if (response.status === 409 || response.status === 422) {
+    }
+    catch (err) {
+        // Only a 409/422 can be a protection rejection. Anything else (auth, 404,
+        // 5xx, network) is a genuine error — surface it.
+        const status = err instanceof GitHubWriteError ? err.status : 0;
+        if (status !== 409 && status !== 422)
+            throw err;
+        // Probe GitHub's *structured* protection signals to decide: protection
+        // (→ PR fallback) vs. a genuine bad request / sha conflict (→ surface the
+        // error). This replaces brittle error-message substring matching.
         const defaultBranch = await getDefaultBranch(owner, repo, token);
-        if (await isBranchProtected(owner, repo, defaultBranch, token)) {
-            // Protected — open a bootstrap PR instead of failing.
-            const bootstrapPR = await openBootstrapConfigPR(owner, repo, content, token, defaultBranch);
-            return { bootstrapPR };
+        if (!(await isBranchProtected(owner, repo, defaultBranch, token))) {
+            throw err;
         }
+        const bootstrapPR = await openBootstrapConfigPR(owner, repo, files, token, defaultBranch, autoMergeEnabled);
+        return { bootstrapPR };
     }
-    throw new Error(`Failed to write config: ${response.status} — ${err}`);
 }
-// =============================================================================
-// Merge helpers
-// =============================================================================
+const SCAN_POLL_INTERVAL_MS = 1500;
+// A run still marked `running` but whose KV state hasn't been touched for this
+// long is treated as dead (CF isolate killed mid-scan). Mirrors the web's
+// RESUME_FRESHNESS window so we surface a retryable error instead of hanging.
+const SCAN_STALE_MS = 90_000;
 /**
- * Deep merge two plain objects. Arrays are replaced (not concatenated)
- * since config arrays like `rules` and `wait_for` are complete sets from
- * the wizard and should override, not append to, existing values.
+ * Run one unified onboarding scan for a single repo, returning the proposed
+ * rules / policies / instructions. Authenticated with the CLI's GitHub token
+ * (the scan endpoint validates it against GitHub /user, the same trust model as
+ * the cookie session the web uses).
  */
-function deepMerge(target, source) {
-    const result = { ...target };
-    for (const key of Object.keys(source)) {
-        const srcVal = source[key];
-        const tgtVal = result[key];
-        if (srcVal !== null &&
-            typeof srcVal === 'object' &&
-            !Array.isArray(srcVal) &&
-            tgtVal !== null &&
-            typeof tgtVal === 'object' &&
-            !Array.isArray(tgtVal)) {
-            result[key] = deepMerge(tgtVal, srcVal);
-        }
-        else {
-            result[key] = srcVal;
-        }
-    }
-    return result;
-}
-// =============================================================================
-// Onboarding scan (SSE client)
-// =============================================================================
-async function runScan(repos, scanType, token) {
-    const response = await fetch(`${HAYSTACK_API}/api/onboarding/scan`, {
+async function runUnifiedScan(repo, token) {
+    const startResp = await fetch(`${HAYSTACK_API}/api/onboarding/scan`, {
         method: 'POST',
         headers: {
             'Content-Type': 'application/json',
             Authorization: `Bearer ${token}`,
         },
-        body: JSON.stringify({ repos, scanType }),
+        body: JSON.stringify({ repo, scanType: 'unified' }),
     });
-    if (!response.ok) {
-        throw new Error(`Scan failed: ${response.status}`);
-    }
-    return parseSseStream(response);
-}
-async function parseSseStream(response) {
-    const text = await response.text();
-    const lines = text.split('\n');
-    let items = [];
-    let eventType = '';
-    const eventDataLines = [];
-    function flushEvent() {
-        if (!eventType || eventDataLines.length === 0)
-            return;
-        const eventData = eventDataLines.join('\n');
-        const parsed = JSON.parse(eventData);
-        if (eventType === 'progress') {
-            const progress = parsed;
-            process.stdout.write(`\r${chalk.dim('  ' + progress.message)}`);
-            if (progress.detail) {
-                process.stdout.write(chalk.dim(` — ${progress.detail}`));
-            }
-            process.stdout.write('\x1b[K');
+    if (!startResp.ok) {
+        const text = await startResp.text().catch(() => '');
+        throw new Error(`Scan kickoff failed: ${startResp.status}${text ? ` ${text}` : ''}`.trim());
+    }
+    const { runId } = (await startResp.json());
+    if (!runId)
+        throw new Error('Scan kickoff returned no runId');
+    let lastProgressKey = '';
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        await new Promise((resolve) => setTimeout(resolve, SCAN_POLL_INTERVAL_MS));
+        let statusResp;
+        try {
+            statusResp = await fetch(`${HAYSTACK_API}/api/onboarding/scan/status?runId=${encodeURIComponent(runId)}`, { headers: { Authorization: `Bearer ${token}` } });
         }
-        else if (eventType === 'result') {
-            items = parsed.items;
+        catch {
+            // Transient network blip — the KV state is authoritative and won't vanish
+            // from one failed poll, so keep going.
+            continue;
         }
-        else if (eventType === 'error') {
-            throw new Error(parsed.message);
+        if (statusResp.status === 404) {
+            // State expired (TTL) or runId never registered — surface, don't hang.
+            process.stdout.write('\r\x1b[K');
+            throw new Error('Scan state expired — please retry.');
         }
-        eventType = '';
-        eventDataLines.length = 0;
-    }
-    for (const line of lines) {
-        if (line.startsWith('event: ')) {
-            eventType = line.slice(7).trim();
+        if (!statusResp.ok) {
+            // Transient (5xx etc.) — back off and retry on the next tick.
+            continue;
+        }
+        const state = (await statusResp.json());
+        if (state.progress) {
+            const key = `${state.progress.message}|${state.progress.detail ?? ''}`;
+            if (key !== lastProgressKey) {
+                lastProgressKey = key;
+                process.stdout.write(`\r${chalk.dim('  ' + state.progress.message)}`);
+                if (state.progress.detail)
+                    process.stdout.write(chalk.dim(` — ${state.progress.detail}`));
+                process.stdout.write('\x1b[K');
+            }
+        }
+        if (state.status === 'done') {
+            process.stdout.write('\r\x1b[K');
+            if (!state.result)
+                throw new Error('Scan completed but returned no result.');
+            return {
+                rules: state.result.rules ?? [],
+                policies: state.result.policies ?? [],
+                instructions: state.result.instructions ?? [],
+            };
         }
-        else if (line.startsWith('data: ')) {
-            eventDataLines.push(line.slice(6));
+        if (state.status === 'error') {
+            process.stdout.write('\r\x1b[K');
+            throw new Error(state.error || 'Scan failed');
         }
-        else if (line === '') {
-            flushEvent();
+        if (state.status === 'running' && Date.now() - state.updatedAt > SCAN_STALE_MS) {
+            process.stdout.write('\r\x1b[K');
+            throw new Error('Scan stalled (no progress) — please retry.');
         }
     }
-    // Flush any remaining buffered event at EOF (stream may not end with blank line)
-    flushEvent();
-    // Clear progress line
-    process.stdout.write('\r\x1b[K');
-    return items;
 }
 // =============================================================================
 // Display helpers
@@ -544,19 +579,18 @@ function printRule(rule, index) {
     console.log(`  ${chalk.dim(`${index + 1}.`)} ${status} ${rule.name} ${cat}`);
     console.log(`     ${chalk.dim(rule.description)}`);
 }
-function printSignal(signal, index) {
-    const status = signal.enabled ? chalk.green('ON ') : chalk.dim('OFF');
-    const type = chalk.dim(`[${SIGNAL_TYPE_LABELS[signal.type] || signal.type}]`);
-    console.log(`  ${chalk.dim(`${index + 1}.`)} ${status} ${signal.name} ${type}`);
-    if (signal.pattern) {
-        console.log(`     ${chalk.dim(`Pattern: ${signal.pattern}`)}`);
-    }
-}
 function printPolicy(policy, index) {
     const status = policy.enabled ? chalk.green('ON ') : chalk.dim('OFF');
-    const type = chalk.dim(`[${POLICY_TYPE_LABELS[policy.type] || policy.type}]`);
-    console.log(`  ${chalk.dim(`${index + 1}.`)} ${status} ${policy.name} ${type}`);
-    console.log(`     ${chalk.dim(policy.description)}`);
+    const sev = chalk.dim(`[${SEVERITY_LABELS[policy.severity] || policy.severity}]`);
+    console.log(`  ${chalk.dim(`${index + 1}.`)} ${status} ${policy.name} ${sev}`);
+    if (policy.paths.length > 0) {
+        console.log(`     ${chalk.dim(`Paths: ${policy.paths.join(', ')}`)}`);
+    }
+    console.log(`     ${chalk.dim(policy.reason)}`);
+}
+function printInstruction(instruction, index) {
+    const status = instruction.enabled ? chalk.green('ON ') : chalk.dim('OFF');
+    console.log(`  ${chalk.dim(`${index + 1}.`)} ${status} ${instruction.text}`);
 }
 // =============================================================================
 // Wizard steps
@@ -745,51 +779,76 @@ async function stepSelectRepos(token) {
     console.log(chalk.green(`  ${selectedRepos.length} repo(s) selected\n`));
     return selectedRepos;
 }
-async function stepScan(repos, scanType, stepNum, token) {
-    const labels = {
-        rules: 'coding rules',
-        wait_for: 'CI/bot signals',
-        policies: 'review policies',
-    };
-    console.log(chalk.bold(`\n  Step ${stepNum}: Scanning for ${labels[scanType]}\n`));
-    try {
-        const items = await runScan(repos, scanType, token);
-        if (items.length === 0) {
-            console.log(chalk.dim(`  No ${labels[scanType]} discovered.`));
+// File paths written during onboarding (must match the web wizard + worker:
+// src/features/onboarding/services/onboardingApi.ts + the merge-queue cron's
+// ONBOARDING_ALLOWED_PATHS).
+const PR_RULES_PATH = '.haystack/pr-rules.yml';
+const REVIEW_POLICY_PATH = '.haystack/review-policy.md';
+const HAYSTACK_CONFIG_PATH = '.haystack.json';
+const RULES_COMMIT_MSG = 'chore: configure Haystack rules via CLI setup wizard';
+const POLICY_COMMIT_MSG = 'chore: add review policies via CLI setup wizard';
+/**
+ * Scan each selected repo with one unified scan and collect the proposed
+ * rules / policies / instructions per repo. A failed scan for one repo records
+ * an empty result (and a warning) rather than aborting the whole wizard.
+ */
+async function stepScanRepos(repos, token) {
+    console.log(chalk.bold('\n  Step 2: Scanning your repositories\n'));
+    console.log(chalk.dim("  Haystack reads each repo's PR history to learn its review conventions.\n"));
+    const byRepo = new Map();
+    for (const repo of repos) {
+        console.log(chalk.dim(`  Scanning ${repo}...`));
+        try {
+            const result = await runUnifiedScan(repo, token);
+            byRepo.set(repo, result);
+            const counts = [];
+            if (result.rules.length)
+                counts.push(`${result.rules.length} rule(s)`);
+            if (result.policies.length)
+                counts.push(`${result.policies.length} policy/policies`);
+            if (result.instructions.length)
+                counts.push(`${result.instructions.length} instruction(s)`);
+            console.log(counts.length
+                ? chalk.green(`  ✓ ${repo}: ${counts.join(', ')}`)
+                : chalk.dim(`  ${repo}: nothing discovered`));
         }
-        else {
-            console.log(chalk.green(`  Found ${items.length} ${labels[scanType]}`));
+        catch (err) {
+            console.log(chalk.yellow(`  ⚠ ${repo}: scan failed (${err.message})`));
+            console.log(chalk.dim('     Continuing — this repo will get a baseline config you can tune later.'));
+            byRepo.set(repo, { rules: [], policies: [], instructions: [] });
         }
-        return items;
-    }
-    catch (err) {
-        console.log(chalk.yellow(`  Scan failed: ${err.message}`));
-        console.log(chalk.dim('  Skipping this scan — you can configure manually later.\n'));
-        return [];
     }
+    return byRepo;
 }
-async function stepReview(rules, signals, policies) {
-    const totalItems = rules.length + signals.length + policies.length;
-    if (totalItems === 0) {
+/**
+ * Show the discovered rules / policies / instructions per repo and let the user
+ * toggle any off. Mutates the `enabled` flags on the items in `byRepo` in place.
+ */
+async function stepReview(byRepo) {
+    const total = [...byRepo.values()].reduce((n, r) => n + r.rules.length + r.policies.length + r.instructions.length, 0);
+    if (total === 0) {
         console.log(chalk.dim('\n  No items discovered — skipping review.\n'));
-        return { rules, signals, policies };
+        return;
     }
-    console.log(chalk.bold('\n  Step 5: Review discovered configuration\n'));
+    console.log(chalk.bold('\n  Step 3: Review discovered configuration\n'));
     console.log(chalk.dim('  Toggle items on/off. Only enabled items will be written.\n'));
-    // Show current state
-    if (rules.length > 0) {
-        printSectionHeader('Coding Rules', rules.filter((r) => r.enabled).length, rules.length);
-        rules.forEach((r, i) => printRule(r, i));
-    }
-    if (signals.length > 0) {
-        printSectionHeader('Wait-For Signals', signals.filter((s) => s.enabled).length, signals.length);
-        signals.forEach((s, i) => printSignal(s, i));
-    }
-    if (policies.length > 0) {
-        printSectionHeader('Review Policies', policies.filter((p) => p.enabled).length, policies.length);
-        policies.forEach((p, i) => printPolicy(p, i));
+    for (const [repo, result] of byRepo) {
+        if (result.rules.length + result.policies.length + result.instructions.length === 0)
+            continue;
+        console.log(`\n  ${chalk.bold.cyan(repo)}`);
+        if (result.rules.length > 0) {
+            printSectionHeader('Coding Rules', result.rules.filter((r) => r.enabled).length, result.rules.length);
+            result.rules.forEach((r, i) => printRule(r, i));
+        }
+        if (result.policies.length > 0) {
+            printSectionHeader('Review Policies', result.policies.filter((p) => p.enabled).length, result.policies.length);
+            result.policies.forEach((p, i) => printPolicy(p, i));
+        }
+        if (result.instructions.length > 0) {
+            printSectionHeader('Review Instructions', result.instructions.filter((ins) => ins.enabled).length, result.instructions.length);
+            result.instructions.forEach((ins, i) => printInstruction(ins, i));
+        }
     }
-    // Ask if they want to toggle anything
     const { wantToToggle } = await inquirer.prompt([
         {
             type: 'confirm',
@@ -798,127 +857,215 @@ async function stepReview(rules, signals, policies) {
             default: false,
         },
     ]);
-    if (wantToToggle) {
-        // Build a list of all items for toggling
-        const allItems = [];
-        if (rules.length > 0) {
-            allItems.push(new inquirer.Separator('── Coding Rules ──'));
-            rules.forEach((r) => {
-                allItems.push({
-                    name: `${r.name} ${chalk.dim(`[${CATEGORY_LABELS[r.category] || r.category}]`)}`,
-                    value: `rule:${r.id}`,
-                    checked: r.enabled,
-                });
-            });
-        }
-        if (signals.length > 0) {
-            allItems.push(new inquirer.Separator('── Wait-For Signals ──'));
-            signals.forEach((s) => {
-                allItems.push({
-                    name: `${s.name} ${chalk.dim(`[${SIGNAL_TYPE_LABELS[s.type] || s.type}]`)}`,
-                    value: `signal:${s.id}`,
-                    checked: s.enabled,
-                });
-            });
-        }
-        if (policies.length > 0) {
-            allItems.push(new inquirer.Separator('── Review Policies ──'));
-            policies.forEach((p) => {
-                allItems.push({
-                    name: `${p.name} ${chalk.dim(`[${POLICY_TYPE_LABELS[p.type] || p.type}]`)}`,
-                    value: `policy:${p.id}`,
-                    checked: p.enabled,
-                });
+    if (!wantToToggle)
+        return;
+    // NUL separates repo / kind / id in the checkbox value so it can't collide
+    // with any character in a repo slug or an item id.
+    const SEP = '\u0000';
+    const allItems = [];
+    for (const [repo, result] of byRepo) {
+        if (result.rules.length + result.policies.length + result.instructions.length === 0)
+            continue;
+        allItems.push(new inquirer.Separator(`── ${repo} ──`));
+        result.rules.forEach((r) => {
+            allItems.push({
+                name: `${r.name} ${chalk.dim(`[rule · ${CATEGORY_LABELS[r.category] || r.category}]`)}`,
+                value: `${repo}${SEP}rule${SEP}${r.id}`,
+                checked: r.enabled,
             });
-        }
-        const { enabled } = await inquirer.prompt([
-            {
-                type: 'checkbox',
-                name: 'enabled',
-                message: 'Select items to enable:',
-                choices: allItems,
-                pageSize: 20,
-            },
-        ]);
-        // Apply toggling
-        rules.forEach((r) => {
-            r.enabled = enabled.includes(`rule:${r.id}`);
         });
-        signals.forEach((s) => {
-            s.enabled = enabled.includes(`signal:${s.id}`);
+        result.policies.forEach((p) => {
+            allItems.push({
+                name: `${p.name} ${chalk.dim(`[policy · ${SEVERITY_LABELS[p.severity] || p.severity}]`)}`,
+                value: `${repo}${SEP}policy${SEP}${p.id}`,
+                checked: p.enabled,
+            });
         });
-        policies.forEach((p) => {
-            p.enabled = enabled.includes(`policy:${p.id}`);
+        result.instructions.forEach((ins) => {
+            allItems.push({
+                name: `${ins.text} ${chalk.dim('[instruction]')}`,
+                value: `${repo}${SEP}instruction${SEP}${ins.id}`,
+                checked: ins.enabled,
+            });
         });
     }
-    return { rules, signals, policies };
+    const { enabled } = await inquirer.prompt([
+        {
+            type: 'checkbox',
+            name: 'enabled',
+            message: 'Select items to enable:',
+            choices: allItems,
+            pageSize: 20,
+        },
+    ]);
+    const enabledSet = new Set(enabled);
+    for (const [repo, result] of byRepo) {
+        result.rules.forEach((r) => { r.enabled = enabledSet.has(`${repo}${SEP}rule${SEP}${r.id}`); });
+        result.policies.forEach((p) => { p.enabled = enabledSet.has(`${repo}${SEP}policy${SEP}${p.id}`); });
+        result.instructions.forEach((ins) => { ins.enabled = enabledSet.has(`${repo}${SEP}instruction${SEP}${ins.id}`); });
+    }
 }
-function buildConfig(rules, signals, policies) {
-    const config = {
-        version: 1,
+// ── Config builders ──────────────────────────────────────────────────────
+// Mirror src/features/onboarding/components/ConfirmStep.tsx (buildPrRules,
+// buildReviewPolicyMarkdown) + services/onboardingApi.ts (serializePrRulesYaml,
+// buildHaystackConfigJson) so the CLI and web wizard emit byte-identical files.
+/** Build pr-rules.yml entries from the proposed rules. Everything onboarding
+ *  surfaces is LLM-evaluated (natural-language rules extracted from review
+ *  comments), so type:'llm' and the description doubles as the prompt. */
+function buildPrRules(rules) {
+    const PROPOSED_TO_YML_CATEGORY = {
+        testing: 'patterns',
+        style: 'style',
+        security: 'security',
+        performance: 'performance',
+        docs: 'patterns',
+        other: 'patterns',
     };
-    const enabledRules = rules.filter((r) => r.enabled);
-    const enabledSignals = signals.filter((s) => s.enabled);
-    const enabledPolicies = policies.filter((p) => p.enabled);
-    if (enabledRules.length > 0) {
-        config.rules = enabledRules.map((r) => ({
-            name: r.name,
-            description: r.description,
-            category: r.category,
-        }));
-    }
-    if (enabledSignals.length > 0) {
-        config.wait_for = enabledSignals.map((s) => ({
-            name: s.name,
-            type: s.type,
-            source: s.source,
-            pattern: s.pattern,
-        }));
-    }
-    if (enabledPolicies.length > 0) {
-        config.review_policies = enabledPolicies.map((p) => ({
-            name: p.name,
-            type: p.type,
-            description: p.description,
-            config: p.config,
-        }));
-    }
-    return config;
+    return rules
+        .filter((r) => r.enabled)
+        .map((r) => ({
+        id: r.id,
+        name: r.name,
+        type: 'llm',
+        severity: 'warning',
+        message: r.description,
+        category: PROPOSED_TO_YML_CATEGORY[r.category],
+        llm: { prompt: r.description },
+    }));
 }
-async function stepConfirm(selectedRepos, rules, signals, policies, token) {
-    const config = buildConfig(rules, signals, policies);
-    const enabledRules = rules.filter((r) => r.enabled);
-    const enabledSignals = signals.filter((s) => s.enabled);
+/** Render review-policy.md from path-scoped policies + universal instructions.
+ *  Returns null when nothing is enabled (caller skips the file). */
+function buildReviewPolicyMarkdown(policies, instructions) {
     const enabledPolicies = policies.filter((p) => p.enabled);
-    const totalEnabled = enabledRules.length + enabledSignals.length + enabledPolicies.length;
-    console.log(chalk.bold('\n  Step 6: Confirm & write configuration\n'));
-    // Summary
-    const parts = [];
-    if (enabledRules.length > 0)
-        parts.push(`${enabledRules.length} rules`);
-    if (enabledSignals.length > 0)
-        parts.push(`${enabledSignals.length} signals`);
-    if (enabledPolicies.length > 0)
-        parts.push(`${enabledPolicies.length} policies`);
-    if (totalEnabled === 0) {
-        console.log(chalk.dim('  No items enabled. Config will contain version only.\n'));
+    const enabledInstructions = instructions.filter((i) => i.enabled);
+    if (enabledPolicies.length === 0 && enabledInstructions.length === 0)
+        return null;
+    const lines = ['# Review Policies', ''];
+    for (const policy of enabledPolicies) {
+        lines.push(`## ${policy.name}`);
+        lines.push(`- **Paths**: ${policy.paths.map((p) => '`' + p + '`').join(', ')}`);
+        lines.push(`- **Severity**: ${policy.severity}`);
+        lines.push(`- **Reason**: ${policy.reason}`);
+        lines.push('');
+    }
+    if (enabledInstructions.length > 0) {
+        lines.push('## Instructions');
+        for (const instr of enabledInstructions) {
+            lines.push(`- ${instr.text}`);
+        }
+        lines.push('');
     }
-    else {
-        console.log(`  ${chalk.dim('Items:')} ${parts.join(', ')}`);
-    }
-    console.log(`  ${chalk.dim('Repos:')} ${selectedRepos.join(', ')}`);
-    // Preview
-    console.log(chalk.dim('\n  ┌─ .haystack.json ─────────────────────────────────'));
-    const preview = JSON.stringify(config, null, 2);
-    preview.split('\n').forEach((line) => {
-        console.log(chalk.dim('  │ ') + chalk.white(line));
-    });
-    console.log(chalk.dim('  └─────────────────────────────────────────────────\n'));
+    return lines.join('\n');
+}
+/** `.haystack.json` enabling the merge queue, reflecting the user's auto-merge
+ *  choice. Mirrors the web wizard's buildHaystackConfigJson shape. Auto-merge is
+ *  the master switch: when off, nothing lands in the queue, so the two sub-flags
+ *  follow it. */
+function buildHaystackConfigJson(autoMerge) {
+    const config = {
+        preferences: { auto_merge: autoMerge },
+        merge_queue: {
+            merge_queue: autoMerge,
+            auto_resolve_conflicts: autoMerge,
+            auto_fix_ci_failures: autoMerge,
+        },
+    };
+    return JSON.stringify(config, null, 2) + '\n';
+}
+// Minimal YAML serializer for the pr-rules.yml shape (keeps us off a yaml dep;
+// mirrors onboardingApi.ts serializePrRulesYaml).
+function yamlScalar(s) {
+    return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+function yamlBlockOrScalar(s, indentCols) {
+    if (!s.includes('\n'))
+        return yamlScalar(s);
+    const pad = ' '.repeat(indentCols);
+    const body = s.split('\n').map((line) => `${pad}${line}`).join('\n');
+    return `|\n${body}`;
+}
+function serializePrRulesYaml(rules) {
+    if (rules.length === 0) {
+        return '# No rules configured yet. Add entries under `rules:` below.\nrules: []\n';
+    }
+    const lines = ['rules:'];
+    for (const rule of rules) {
+        lines.push(`  - id: ${yamlScalar(rule.id)}`);
+        lines.push(`    name: ${yamlScalar(rule.name)}`);
+        lines.push(`    type: ${rule.type}`);
+        lines.push(`    severity: ${rule.severity}`);
+        if (rule.category)
+            lines.push(`    category: ${yamlScalar(rule.category)}`);
+        lines.push(`    message: ${yamlScalar(rule.message)}`);
+        if (rule.llm) {
+            lines.push(`    llm:`);
+            lines.push(`      prompt: ${yamlBlockOrScalar(rule.llm.prompt, 8)}`);
+            if (rule.llm.files)
+                lines.push(`      files: ${yamlScalar(rule.llm.files)}`);
+        }
+        if (rule.pattern) {
+            lines.push(`    pattern:`);
+            lines.push(`      regex: ${yamlScalar(rule.pattern.regex)}`);
+            if (rule.pattern.files)
+                lines.push(`      files: ${yamlScalar(rule.pattern.files)}`);
+            if (rule.pattern.exclude)
+                lines.push(`      exclude: ${yamlScalar(rule.pattern.exclude)}`);
+        }
+    }
+    return lines.join('\n') + '\n';
+}
+/** Build the onboarding files to write for one repo from its (toggled) scan
+ *  result. `.haystack.json` is always written (it enables the merge queue); the
+ *  rules + policy files only when there's enabled content for them. */
+function buildOnboardingFiles(result, autoMerge) {
+    const files = [];
+    const prRules = buildPrRules(result.rules);
+    if (prRules.length > 0) {
+        files.push({ path: PR_RULES_PATH, content: serializePrRulesYaml(prRules), message: RULES_COMMIT_MSG });
+    }
+    const reviewPolicyMd = buildReviewPolicyMarkdown(result.policies, result.instructions);
+    if (reviewPolicyMd) {
+        files.push({ path: REVIEW_POLICY_PATH, content: reviewPolicyMd, message: POLICY_COMMIT_MSG });
+    }
+    files.push({ path: HAYSTACK_CONFIG_PATH, content: buildHaystackConfigJson(autoMerge), message: CONFIG_COMMIT_MSG });
+    return files;
+}
+async function stepConfirm(byRepo, token) {
+    const selectedRepos = [...byRepo.keys()];
+    console.log(chalk.bold('\n  Step 4: Confirm & write configuration\n'));
+    // Per-repo summary of what will be written.
+    for (const [repo, result] of byRepo) {
+        const enabledRules = result.rules.filter((r) => r.enabled).length;
+        const enabledPolicies = result.policies.filter((p) => p.enabled).length;
+        const enabledInstructions = result.instructions.filter((i) => i.enabled).length;
+        const parts = [];
+        if (enabledRules > 0)
+            parts.push(`${enabledRules} rule(s) → ${PR_RULES_PATH}`);
+        if (enabledPolicies + enabledInstructions > 0) {
+            parts.push(`${enabledPolicies + enabledInstructions} policy/instruction(s) → ${REVIEW_POLICY_PATH}`);
+        }
+        parts.push(`merge queue → ${HAYSTACK_CONFIG_PATH}`);
+        console.log(`  ${chalk.bold(repo)}`);
+        parts.forEach((p) => console.log(`    ${chalk.dim('•')} ${chalk.dim(p)}`));
+    }
+    console.log('');
+    // Auto-merge is the master switch. Default ON (matches the web wizard default
+    // + the repo-level preferences.auto_merge opt-in model). When off, the
+    // bootstrap PR is opened but NOT labeled, so the user merges it manually and
+    // no PRs auto-merge.
+    const { autoMerge } = await inquirer.prompt([
+        {
+            type: 'confirm',
+            name: 'autoMerge',
+            message: 'Enable auto-merge? (Haystack merges PRs automatically once they pass review)',
+            default: true,
+        },
+    ]);
     const { confirmed } = await inquirer.prompt([
         {
             type: 'confirm',
             name: 'confirmed',
-            message: `Write .haystack.json to ${selectedRepos.length} repo(s)?`,
+            message: `Write Haystack config to ${selectedRepos.length} repo(s)?`,
             default: true,
         },
     ]);
@@ -926,24 +1073,27 @@ async function stepConfirm(selectedRepos, rules, signals, policies, token) {
         console.log(chalk.yellow('\n  Setup cancelled.\n'));
         return { confirmed: false, bootstrapPRs: new Map() };
     }
-    // Write to each repo
     const failedRepos = [];
     const bootstrapPRs = new Map();
     for (const repoFullName of selectedRepos) {
         const [owner, repo] = repoFullName.split('/');
+        const result = byRepo.get(repoFullName);
+        const files = buildOnboardingFiles(result, autoMerge);
         try {
             process.stdout.write(chalk.dim(`  Writing to ${repoFullName}...`));
-            const existing = await fetchExistingConfig(owner, repo, token);
-            const mergedConfig = existing ? deepMerge(existing.config, config) : config;
-            const result = await writeConfigToRepo(owner, repo, mergedConfig, existing?.sha ?? null, token);
+            const writeResult = await writeOnboardingFilesToRepo(owner, repo, files, autoMerge, token);
             process.stdout.write('\r\x1b[K');
-            if (result.bootstrapPR) {
-                // Default branch was protected — config landed in a bootstrap PR
-                // that Haystack will auto-merge once its labels are processed.
-                // Step 7 adds .entire/settings.json to this same PR.
-                bootstrapPRs.set(repoFullName, result.bootstrapPR);
-                console.log(chalk.green(`  ✓ ${repoFullName}`) + chalk.dim(' (default branch protected — opened a PR)'));
-                console.log(chalk.dim(`    ${result.bootstrapPR.prUrl}`));
+            if (writeResult.bootstrapPR) {
+                // Default branch was protected — config landed in a bootstrap PR. With
+                // auto-merge on, Haystack merges it once its labels are processed; with
+                // auto-merge off it waits for the user. Step 7 ensures
+                // .entire/settings.json is on the same PR.
+                bootstrapPRs.set(repoFullName, writeResult.bootstrapPR);
+                const note = autoMerge
+                    ? ' (default branch protected — opened a PR)'
+                    : ' (default branch protected — opened a PR for you to review and merge)';
+                console.log(chalk.green(`  ✓ ${repoFullName}`) + chalk.dim(note));
+                console.log(chalk.dim(`    ${writeResult.bootstrapPR.prUrl}`));
             }
             else {
                 console.log(chalk.green(`  ✓ ${repoFullName}`));
@@ -996,14 +1146,12 @@ export async function setupCommand() {
     await stepEnsureAppInstalled(token);
     // Step 1: Select repos
     const selectedRepos = await stepSelectRepos(token);
-    // Steps 2-4: Scan for rules, wait-for signals, and review policies
-    const rules = (await stepScan(selectedRepos, 'rules', 2, token));
-    const signals = (await stepScan(selectedRepos, 'wait_for', 3, token));
-    const policies = (await stepScan(selectedRepos, 'policies', 4, token));
-    // Step 5: Review
-    const reviewed = await stepReview(rules, signals, policies);
-    // Step 6: Confirm & write
-    const { confirmed, bootstrapPRs } = await stepConfirm(selectedRepos, reviewed.rules, reviewed.signals, reviewed.policies, token);
+    // Step 2: Unified scan per repo (rules + policies + instructions)
+    const byRepo = await stepScanRepos(selectedRepos, token);
+    // Step 3: Review (toggle items off)
+    await stepReview(byRepo);
+    // Step 4: Confirm & write the config files
+    const { confirmed, bootstrapPRs } = await stepConfirm(byRepo, token);
     if (!confirmed)
         return;
     // Step 7: Install Entire CLI (session tracking). bootstrapPRs tells it
@@ -1125,7 +1273,7 @@ async function configureEntireSettingsViaAPI(repoFullName, token) {
     };
     if (existingSha)
         body.sha = existingSha;
-    const putResp = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/contents/.entire/settings.json`, {
+    const putResp = await fetch(`${GITHUB_PROXY}/repos/${owner}/${repo}/contents/.entire/settings.json`, {
         method: 'PUT',
         headers,
         body: JSON.stringify(body),
@@ -1204,11 +1352,12 @@ async function stepInstallEntire(selectedRepos, token, bootstrapPRs) {
                     bundled++;
                 }
                 else {
-                    // Step 6 shipped the bootstrap PR with .haystack.json only — the
-                    // optional settings read failed transiently. Don't count it as
-                    // configured; the warning was already shown in step 6.
+                    // The bootstrap PR shipped the config files but not
+                    // .entire/settings.json — its optional read failed transiently. Don't
+                    // count it as configured; the warning was already shown when the PR
+                    // was opened.
                     console.log(chalk.yellow(`  ⚠ ${repoFullName}`) +
-                        chalk.dim(' — bootstrap PR has .haystack.json only; re-run setup to add session tracking'));
+                        chalk.dim(' — bootstrap PR has config files only; re-run setup to add session tracking'));
                 }
                 continue;
             }

package/dist/index.js

@@ -19,6 +19,9 @@
  *   npx @haystackeditor/cli pr-status 123  # Show PR status in Haystack pipeline
  *   npx @haystackeditor/cli config         # Manage preferences
  */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
 import { Command } from 'commander';
 import { statusCommand } from './commands/status.js';
 import { initCommand } from './commands/init.js';
@@ -34,11 +37,23 @@ import { dismissCommand, markReviewedCommand, undismissCommand } from './command
 import { requestReviewCommand } from './commands/request-review.js';
 import { prStatusCommand } from './commands/pr-status.js';
 import { setupCommand } from './commands/setup.js';
+/** Read the published version from package.json (dist/index.js → ../package.json)
+ *  so `haystack --version` can't drift from the package version. Falls back
+ *  gracefully so the flag never throws if the file can't be read. */
+function getVersion() {
+    try {
+        const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+        return JSON.parse(readFileSync(pkgPath, 'utf8')).version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
 const program = new Command();
 program
     .name('haystack')
     .description('Haystack CLI — automated PR review, triage, and merge queue')
-    .version('0.14.1');
+    .version(getVersion());
 program
     .command('init')
     .description('Create .haystack.json configuration')

package/dist/utils/github-api.js

@@ -4,7 +4,27 @@
  * Provides functions for creating PRs, managing labels, etc.
  */
 import { resolveAuthContext } from './auth.js';
+import { trackError } from './telemetry.js';
 const GITHUB_API_BASE = 'https://api.github.com';
+// OAuth App Policy fallback. Orgs can restrict our OAuth app, which makes the
+// user's token 403 on every API call to that org — so `haystack submit` can't
+// open PRs, add labels, or request reviewers there. The auth-worker GitHub
+// proxy swaps in the GitHub App installation token server-side (the App isn't
+// subject to OAuth App Policy / SAML SSO enforcement the way the OAuth token
+// is), so on such a 403 we retry the same request through it. Direct calls are
+// tried first, so on unrestricted orgs nothing changes and PRs stay
+// user-authored; only the fallback path is performed by the App (haystack[bot]).
+const GITHUB_PROXY_BASE = 'https://haystackeditor.com/api/github';
+/**
+ * A 403 that is NOT a rate-limit is almost always OAuth App Policy or SAML SSO
+ * enforcement blocking our OAuth app on this org — exactly what the
+ * installation-token proxy can bypass. Rate-limit 403s carry
+ * `x-ratelimit-remaining: 0` and the proxy can't help with those, so we don't
+ * retry them.
+ */
+function isOAuthPolicyForbidden(response) {
+    return response.status === 403 && response.headers.get('x-ratelimit-remaining') !== '0';
+}
 // Label definitions for Haystack workflow
 export const HAYSTACK_LABELS = {
     'haystack:auto-merge': {
@@ -43,8 +63,9 @@ async function resolveToken(token, options) {
  * Make an authenticated GitHub API request
  */
 async function githubApiRequest(method, path, token, body) {
-    const url = `${GITHUB_API_BASE}${path}`;
-    const response = await fetch(url, {
+    // body is serialized to a string (not a stream), so the same init can be
+    // reused for the proxy retry below.
+    const init = {
         method,
         headers: {
             Authorization: `Bearer ${token}`,
@@ -53,8 +74,17 @@ async function githubApiRequest(method, path, token, body) {
             'User-Agent': 'Haystack-CLI',
         },
         body: body ? JSON.stringify(body) : undefined,
-    });
-    return response;
+    };
+    const direct = await fetch(`${GITHUB_API_BASE}${path}`, init);
+    if (!isOAuthPolicyForbidden(direct))
+        return direct;
+    // Org restricts our OAuth app — retry through the proxy on the App's
+    // installation token. Same `Authorization: Bearer <github-token>`; the proxy
+    // validates it, then uses its own token upstream. If the proxy can't help
+    // (e.g. the App isn't installed on this owner), fall back to the original
+    // response so handleApiError surfaces GitHub's actual "org restricted" 403.
+    const proxied = await fetch(`${GITHUB_PROXY_BASE}${path}`, init);
+    return proxied.ok ? proxied : direct;
 }
 /**
  * Handle API errors consistently
@@ -66,6 +96,16 @@ async function handleApiError(response, context) {
     if (response.status === 403) {
         const rateLimitRemaining = response.headers.get('x-ratelimit-remaining');
         if (rateLimitRemaining === '0') {
+            // Log every rate-limit hit so we can watch real-world frequency and decide
+            // whether the CLI needs its own token bucket. Routes to PostHog (and on to
+            // Slack via the ops-alert pipeline). Fire-and-forget; never blocks.
+            trackError('cli_github_rate_limited', {
+                context,
+                status: 403,
+                rate_limit_limit: response.headers.get('x-ratelimit-limit'),
+                rate_limit_reset: response.headers.get('x-ratelimit-reset'),
+                rate_limit_resource: response.headers.get('x-ratelimit-resource'),
+            });
             throw new Error('GitHub API rate limit exceeded. Please wait and try again.');
         }
         throw new Error(`Permission denied: ${context}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haystackeditor/cli",
-  "version": "0.14.1",
+  "version": "0.14.3",
   "description": "Set up Haystack for your project — automated PR review, triage, and merge queue",
   "type": "module",
   "bin": {