@haystackeditor/cli 0.30.2 → 0.31.0

package/dist/commands/crawl-report.js

@@ -74,12 +74,10 @@ export function brokenCopy(view) {
 }
 /** What `haystack verify` says first of a broken copy. */
 export const BROKEN_COPY_HEADLINE = "We couldn't test your change: the app copy is broken.";
-/** What the coding agent does about a broken copy: the app's own setup says what the errors need; until a broken copy updates its
- * setup (onboarding amendment 38 updates it only from a check that could not start the app), that is sent to the Haystack team
- * (`haystack feedback`), and the user is told the change was not tested. */
+/** What the coding agent does about a broken copy: explain the missing setup in run notes, then ask for the check again. */
 export const BROKEN_COPY_STEPS = [
     "Find what these errors point to in the repository's own setup (docker compose files, env examples, docs): the services, settings and data the app needs to run.",
-    'Send what you found with `haystack feedback "<what the app needs to run>"`: a copy that starts but is broken does not update its setup yet.',
+    'Write what the app needs in a JSON notes file, for example { "run": "<missing services, packages, toolchains or settings>" }, then run `haystack init --notes <file>` and `haystack verify` again. Haystack uses the notes to repair the existing setup and reruns the check when the repair is ready.',
     'Tell your user this check did not test the change; do not read it as passing.',
 ];
 /** Text that reads as an error, for the lines a broken copy's start screen shows (every one is in --raw). */

package/dist/commands/init-summary.js

@@ -0,0 +1,115 @@
+/**
+ * How `haystack init` ends: a short checklist of what is done and what is left, then exactly one next step (Akshay,
+ * 2026-10-07: init as a wizard for coding agents, with no new commands). Codex setting up langgenius/dify got the test copy's
+ * setup, production telemetry's questions and hundreds of telemetry candidates in one output, and could not tell when setup
+ * was finished. What agent-facing CLIs do (doctor-style checklists, one actionable next step, never a prompt): init does all
+ * it can in one run, and stops only when it needs a person, needs to wait, or is done; running it again picks up from there.
+ *
+ * The next step is one of: a command the coding agent runs itself (`run`), something only its user can do or answer
+ * (`ask-user`, the text says what to ask), a long step to wait out (`wait`), or nothing left (`none`).
+ */
+import chalk from 'chalk';
+const TELEMETRY_HINT = 'optional: it needs the app\'s owner. Ask your user whether to track how real users use the app; if they '
+    + 'want it, run `haystack init --telemetry`';
+function onboardingCheck(onboarding) {
+    const item = 'Test copy of the app';
+    if (onboarding === null)
+        return { item, state: 'todo', detail: 'not started yet' };
+    switch (onboarding.state) {
+        case 'ready': return { item, state: 'done', detail: 'ready' };
+        case 'onboarding': return { item, state: 'running', detail: 'being set up' };
+        case 'blocked': return { item, state: 'todo', detail: onboarding.block?.ask?.question ? 'needs an answer from your user' : 'blocked' };
+        case 'not-started': return { item, state: 'todo', detail: 'not started yet' };
+        default: return { item, state: 'todo', detail: 'stopped before finishing' };
+    }
+}
+function telemetryChecks(telemetry) {
+    if (telemetry === null)
+        return [{ item: 'Tracking real users', state: 'optional', detail: TELEMETRY_HINT }];
+    const part = (item, value) => value.status === 'unsupported'
+        ? { item, state: 'skipped', detail: `not supported here: ${value.why}` }
+        : value.status === 'installed'
+            ? value.received === null ? { item, state: 'todo', detail: 'set up in the code; nothing received from the live app yet' }
+                : { item, state: 'done', detail: `working; last received ${value.received.lastSeenAt}` }
+            : { item, state: 'todo', detail: 'needs a step' };
+    return [part('Tracking in the browser', telemetry.report.capture), part('Tracking on the server', telemetry.report.server)];
+}
+/** Tracking is finished when every part this app supports is set up and Haystack has received its data from the live app. The
+ * report's steps stay listed after that (the token, production's environment, the off switches), as standing advice, never as a
+ * next step: an agent running init until Ready would otherwise never reach it (Bugbot on #4224). */
+function trackingDone(report) {
+    return [report.capture, report.server].every(part => part.status === 'unsupported' || (part.status === 'installed' && part.received !== null));
+}
+/** Tracking's first step for the person while it is not finished: a manual part's first step, else the first of the report's
+ * steps, with the indented lines that continue it. */
+function firstTelemetryStep(telemetry) {
+    if (trackingDone(telemetry.report))
+        return null;
+    for (const value of [telemetry.report.capture, telemetry.report.server]) {
+        if (value.status === 'manual' && value.steps.length)
+            return value.steps[0];
+    }
+    const at = telemetry.steps.findIndex(step => !step.startsWith('  '));
+    if (at < 0)
+        return null;
+    const continued = telemetry.steps.slice(at + 1);
+    const end = continued.findIndex(step => !step.startsWith('  '));
+    return [telemetry.steps[at], ...(end < 0 ? continued : continued.slice(0, end)).map(step => step.trim())].join(' ');
+}
+function nextStep(input) {
+    if (input.status === 'login-required') {
+        return { kind: 'run', text: 'Run `haystack login`: it gives your user a link to sign in with. Then run `haystack init` again.', command: 'haystack login' };
+    }
+    if (input.status === 'planned') {
+        // Notes save the most time before the app's setup starts; for an app already set up they change nothing.
+        const notesHelp = input.notes === null && input.onboarding !== null && input.onboarding.state !== 'ready' && input.onboarding.state !== 'onboarding'
+            ? ' The app is not set up yet: add `--notes <file>` with what you know about how it runs, signs people in and is used '
+                + '(see `haystack init --help`), so its setup does not have to work that out.' : '';
+        return { kind: 'run', text: `Nothing was changed yet. Run \`${input.rerunWithYes}\` to make the changes above.${notesHelp}`, command: input.rerunWithYes };
+    }
+    if (input.status === 'app-required') {
+        return { kind: 'ask-user', text: `Ask your user to install the Haystack GitHub App on ${input.owner}: ${input.installUrl} . Then run \`haystack init\` again.`,
+            command: null };
+    }
+    const onboarding = input.onboarding;
+    if (onboarding.state === 'blocked') {
+        const block = onboarding.block;
+        const ask = block?.ask ?? null;
+        if (ask?.question) {
+            return { kind: 'ask-user', text: `Ask your user: ${ask.message} (one of: ${ask.question.choices.map(choice => JSON.stringify(choice)).join(', ')}). `
+                    + `File their answer with \`haystack verify answer ${ask.question.id} "<their answer>"\`, then run \`haystack init\` again.`,
+                command: `haystack verify answer ${ask.question.id} "<their answer>"` };
+        }
+        if (ask?.command)
+            return { kind: 'run', text: `${ask.message} Run \`${ask.command}\`, then \`haystack init\` again.`, command: ask.command };
+        return { kind: 'none', text: `Setup is blocked and nothing you can run changes that yet${block ? `: ${block.reason}` : ''}. Tell your user, `
+                + 'and say what happened with `haystack feedback "<what happened>"`.', command: null };
+    }
+    if (onboarding.state !== 'ready' && onboarding.state !== 'onboarding') {
+        return { kind: 'run', text: 'Setting up the test copy stopped before finishing. Run `haystack init` again to start it again.', command: 'haystack init' };
+    }
+    // Something the person can do now comes before waiting.
+    const tracking = input.telemetry === null ? null : firstTelemetryStep(input.telemetry);
+    if (tracking !== null)
+        return { kind: 'ask-user', text: `For tracking: ${tracking}`, command: null };
+    if (onboarding.state === 'onboarding') {
+        return { kind: 'wait', text: 'The test copy is being set up. Run `haystack verify onboarding --wait` to follow its progress, then run `haystack init` again. '
+                + 'Ctrl-C stops waiting; setup keeps running.', command: 'haystack verify onboarding --wait' };
+    }
+    return { kind: 'none', text: 'Ready. After each change, run `haystack verify`.', command: null };
+}
+export function initSummary(input) {
+    const checkout = input.changes.length === 0 ? { item: 'This checkout', state: 'done', detail: 'already set up' }
+        : input.made ? { item: 'This checkout', state: 'done', detail: `updated ${input.changes.join(', ')}` }
+            : { item: 'This checkout', state: 'todo', detail: `${input.changes.join(', ')} not changed yet` };
+    const notes = input.notes === null ? []
+        : [{ item: 'Your notes', state: input.status === 'done' ? 'done' : 'todo', detail: `${input.status === 'done' ? 'saved' : 'not saved yet'} (${input.notes.join(', ')})` }];
+    const checklist = [checkout, ...notes, onboardingCheck(input.onboarding), ...telemetryChecks(input.telemetry)];
+    return { ready: input.status === 'done' && input.onboarding?.state === 'ready', checklist, next: nextStep(input) };
+}
+const MARKS = { done: chalk.green('✓'), running: chalk.cyan('…'), todo: chalk.yellow('✗'), skipped: chalk.dim('–'),
+    optional: chalk.dim('○') };
+export function formatInitSummary(summary) {
+    return [chalk.bold('Checklist'), ...summary.checklist.map(check => `  ${MARKS[check.state]} ${check.item}: ${check.detail}`), '',
+        chalk.bold(`Next: ${summary.next.text}`)];
+}

package/dist/commands/init.js

@@ -10,11 +10,14 @@
  *      .git/info/exclude), when Claude Code is in use here;
  *   2. a short marked block in AGENTS.md (and in CLAUDE.md when the repository
  *      keeps one) telling coding agents to run `haystack verify` after a change.
- *   3. telemetry (init-telemetry.ts, CAPTURE-V1 rule 8): the app's server instrumentation and the CLI dependency it needs,
- *      the settings proposal and the browser tag, once the user's answers (which app, its origins, consent) are given;
- *      until then only the telemetry report stops, saying what to ask.
+ *   3. with --telemetry only (or one of its answers: --app, --origin, --consent, --url-rewrites), telemetry
+ *      (init-telemetry.ts, CAPTURE-V1 rule 8): the app's server instrumentation and the CLI dependency it needs, the
+ *      settings proposal and the browser tag, once the user's answers are given; until then only the telemetry report
+ *      stops, saying what to ask. It needs the app's owner (their yes, production's origins, a token, a deploy), so a
+ *      plain init never plans it.
  * It then starts onboarding the app at the base `haystack verify` would use, so
- * the app is usually ready by the first verify. With --notes, the coding agent's
+ * the app is usually ready by the first verify. Every run ends with a short checklist and exactly one next step
+ * (init-summary.ts): init does all it can in one run and stops only when it needs a person, needs to wait, or is done. With --notes, the coding agent's
  * notes on how the app runs, signs people in and is used (onboarding-notes.ts)
  * become the repository's onboarding notes first, so onboarding plans from them. Running it again changes only
  * what is missing or out of date and shows where onboarding is.
@@ -36,7 +39,8 @@ import { findGitRoot } from '../utils/hooks.js';
 import { assertNoSymlinkOnPath } from '../utils/safe-write.js';
 import { CLAUDE_LOCAL_SETTINGS, CLAUDE_SHARED_SETTINGS, HAYSTACK_PRECOMPUTE_HOOK_COMMAND, claudeEntries, claudeSettingsPath, isCLIInstalled, isGitIgnored, isInstalledGlobally, isPrecomputeCommand, readClaudeSettings, } from './install-session-hooks.js';
 import { NOTE_FIELDS, readNotes } from './onboarding-notes.js';
-import { formatOnboarding, reportOnboardingState, startOnboarding, writeOnboardingNotes } from './verify-onboarding.js';
+import { formatOnboarding, readOnboardingStatus, reportOnboardingState, startOnboarding, writeOnboardingNotes } from './verify-onboarding.js';
+import { formatInitSummary, initSummary } from './init-summary.js';
 import { deriveBaseSha, EXPLICIT_WALL_MS, resolveOriginRepository } from './verify-precompute.js';
 const NOTE_BEGIN = '<!-- haystack:begin -->';
 const NOTE_END = '<!-- haystack:end -->';
@@ -332,6 +336,8 @@ function applyAll(gitRoot, changes, say) {
     }
 }
 const errorText = (error) => (error instanceof Error ? error.message : String(error));
+/** A value as one shell word: as it is when plain, else single-quoted. */
+const shellWord = (value) => (/^[\w@%+=:,./-]+$/u.test(value) ? value : `'${value.replace(/'/gu, `'\\''`)}'`);
 function applyChange(gitRoot, planned) {
     const inside = relative(gitRoot, planned.target);
     if (!inside.startsWith('..') && !isAbsolute(inside))
@@ -395,18 +401,24 @@ export async function initCommand(options) {
     // Read before anything else, so notes that cannot be used stop init with nothing done.
     const notes = options.notes === undefined ? null : readNotes(options.notes);
     const plan = planInit(gitRoot);
-    // Telemetry is part of onboarding (CAPTURE-V1 rule 8): planned on every run; a missing answer stops only it. It never fails
-    // init: whatever goes wrong with it (a file it cannot read, a package manager that fails, Haystack not answering) puts its
-    // own files back and leaves it manual with what happened, and the rest of init goes on.
+    // Telemetry (CAPTURE-V1 rule 8) only when asked for: --telemetry, or one of its answers. It needs the app's owner, so a plain
+    // init, which a coding agent finishes alone, never plans it (Codex on langgenius/dify, 2026-10-07, got its questions and
+    // hundreds of candidates in the test copy's setup). A missing answer stops only it. It never fails init: whatever goes
+    // wrong with it (a file it cannot read, a package manager that fails, Haystack not answering) puts its own files back and
+    // leaves it manual with what happened, and the rest of init goes on.
+    const wantTelemetry = options.telemetry === true || options.app !== undefined || (options.origin?.length ?? 0) > 0
+        || options.consent !== undefined || options.urlRewrites !== undefined;
     const telemetryModule = await import('./init-telemetry.js');
     const telemetryOptions = { app: options.app, origins: options.origin ?? [], consent: options.consent, urlRewrites: options.urlRewrites };
     let telemetryFailure = null;
     let telemetryPlan = telemetryModule.emptyTelemetryPlan();
-    try {
-        telemetryPlan = await telemetryModule.planTelemetry(gitRoot, repository, telemetryOptions);
-    }
-    catch (error) {
-        telemetryFailure = errorText(error);
+    if (wantTelemetry) {
+        try {
+            telemetryPlan = await telemetryModule.planTelemetry(gitRoot, repository, telemetryOptions);
+        }
+        catch (error) {
+            telemetryFailure = errorText(error);
+        }
     }
     const telemetryFrom = plan.changes.length;
     plan.changes.push(...telemetryPlan.changes);
@@ -423,16 +435,32 @@ export async function initCommand(options) {
     const report = () => (telemetryFailure !== null ? telemetryModule.failedTelemetry(telemetryPlan, telemetryFailure)
         : telemetry ?? telemetryModule.previewTelemetry(telemetryPlan, repository, notes));
     const showPreview = () => {
+        if (!wantTelemetry)
+            return;
         const preview = report();
         for (const line of telemetryModule.formatTelemetry(preview.telemetry, preview.steps))
             say(line);
         say('');
     };
+    // This run's command again with --yes: what a run that only showed its changes asks for.
+    const rerunWithYes = ['haystack init --yes', ...(options.notes === undefined ? [] : [`--notes ${shellWord(options.notes)}`]),
+        ...(options.telemetry ? ['--telemetry'] : []), ...(options.app === undefined ? [] : [`--app ${shellWord(options.app)}`]),
+        ...(options.origin ?? []).map(value => `--origin ${shellWord(value)}`), ...(options.consent === undefined ? [] : [`--consent ${shellWord(options.consent)}`]),
+        ...(options.urlRewrites === undefined ? [] : [`--url-rewrites ${shellWord(options.urlRewrites)}`])].join(' ');
+    let made = false;
     const finish = (status, onboarding, exitCode) => {
+        const shown = wantTelemetry ? report() : null;
+        const summary = initSummary({ status, owner: origin.owner, changes: plan.changes.map(planned => planned.path), made,
+            notes: notes === null ? null : NOTE_FIELDS.filter(field => notes[field] !== ''), onboarding,
+            telemetry: shown === null ? null : { report: shown.telemetry, steps: shown.steps }, rerunWithYes, installUrl: HAYSTACK_APP_INSTALL_URL });
+        say('');
+        for (const line of formatInitSummary(summary))
+            say(line);
         if (options.json) {
             const changes = plan.changes.map(({ path, action, reason, diff }) => ({ path, action, reason, diff }));
-            process.stdout.write(`${JSON.stringify(withSchema('init', { status, repository, changes, notices: plan.notices, notes: notesWritten,
-                onboarding, telemetry: report().telemetry, telemetrySteps: report().steps }), null, 2)}\n`);
+            process.stdout.write(`${JSON.stringify(withSchema('init', { status, repository, ready: summary.ready, checklist: summary.checklist,
+                next: summary.next, changes, notices: plan.notices, notes: notesWritten, onboarding, telemetry: shown?.telemetry ?? null,
+                telemetrySteps: shown?.steps ?? [] }), null, 2)}\n`);
         }
         process.exitCode = exitCode;
     };
@@ -460,22 +488,34 @@ export async function initCommand(options) {
         if (!(error instanceof NotLoggedInError))
             throw error;
         showPreview();
-        say(chalk.yellow('Not logged in, so nothing was changed. Run `haystack login`, then `haystack init` again.'));
+        say(chalk.yellow('Not logged in, so nothing was changed.'));
         finish('login-required', null, EXIT_CODES['login-required']);
         return;
     }
     if (plan.changes.length > 0 && !options.yes) {
-        const interactive = !options.json && process.stdin.isTTY === true && process.stdout.isTTY === true;
+        // Never a prompt for a coding agent, even in a terminal it drives (Claude Code sets CLAUDECODE; agents share AI_AGENT):
+        // the run stops and names the flag instead.
+        const agent = Boolean(process.env.CLAUDECODE) || Boolean(process.env.AI_AGENT);
+        const interactive = !options.json && !agent && process.stdin.isTTY === true && process.stdout.isTTY === true;
         if (!interactive || !await confirmed()) {
             showPreview();
-            say('Nothing was changed. Run `haystack init --yes` to make these changes.');
-            finish('planned', null, EXIT_CODES.planned);
+            // Where the app stands, read without starting anything, so the checklist says it and an agent writes notes only for an
+            // app that is not set up yet (Codex on langgenius/dify, 2026-10-07, wrote notes for an app already set up).
+            let standing = null;
+            try {
+                standing = await readOnboardingStatus(repository, deriveBaseSha(gitRoot, Date.now() + EXPLICIT_WALL_MS), token);
+            }
+            catch {
+                // Unread (the GitHub App not installed, Haystack not answering): the checklist says it has not started, as before.
+            }
+            finish('planned', standing, EXIT_CODES.planned);
             return;
         }
     }
     // Init's own changes (the agent instructions, the Stop hook) first, all or nothing: a failure there is init's.
     try {
         applyAll(gitRoot, plan.changes.slice(0, telemetryFrom), say);
+        made = true;
     }
     catch (error) {
         throw new Error(`${errorText(error)} Every file init changed was restored; nothing was changed.`);
@@ -485,7 +525,7 @@ export async function initCommand(options) {
     // without capture's, when it is refused).
     const approved = options.yes === true || plan.changes.length > 0;
     let capture = null;
-    if (telemetryFailure === null) {
+    if (wantTelemetry && telemetryFailure === null) {
         try {
             capture = telemetryPlan.captureRegistration
                 ? await telemetryModule.prepareCapture(telemetryPlan.captureRegistration, token, say, approved) : null;
@@ -527,27 +567,28 @@ export async function initCommand(options) {
     }
     catch (error) {
         if (error instanceof HaystackApiError && error.code === INSTALLATION_REQUIRED_CODE) {
-            say(chalk.yellow(`Haystack needs its GitHub App on ${origin.owner} to read the repository. Install it at`));
-            say(`  ${HAYSTACK_APP_INSTALL_URL}`);
-            say('then run `haystack init` again.');
+            say(chalk.yellow(`Haystack needs its GitHub App on ${origin.owner} to read the repository.`));
             finish('app-required', null, EXIT_CODES['app-required']);
             return;
         }
         const done = plan.changes.length > 0 ? 'The changes above were made, but onboarding' : 'Onboarding';
         throw new Error(`${done} could not start: ${error instanceof Error ? error.message : String(error)} Run \`haystack init\` again to start it.`);
     }
-    // New notes for an app that is already set up change nothing about its setup (rule 2, amendment 34: each app is set up once).
-    // Said in words, and in --json's notices for the coding agent, which otherwise reads "notes: written" as a new onboarding
-    // (Codex on langgenius/dify, 2026-10-07).
+    // Notes inform an incremental repair when the next check finds a broken setup; init itself does not rebuild the app.
     if (notesWritten === 'written' && onboarding.state === 'ready') {
-        const notice = 'The app is already set up, so these notes do not change its setup: Haystack sets each app up once and keeps the notes.';
-        plan.notices.push(notice);
-        say(chalk.dim(notice));
+        // This init call only saved the notes. The check, not init, starts an incremental repair when one is needed.
+        const notices = [
+            'The app is already set up, so these notes do not change its setup: Haystack sets each app up once and keeps the notes.',
+            'Run `haystack verify` again: if its copy is broken, Haystack uses the saved notes to repair the existing setup and rerun the check.',
+        ];
+        plan.notices.push(...notices);
+        for (const notice of notices)
+            say(chalk.dim(notice));
     }
     reportOnboardingState(onboarding);
     say(formatOnboarding(onboarding));
     say('');
-    if (telemetryFailure === null) {
+    if (wantTelemetry && telemetryFailure === null) {
         try {
             telemetry = await telemetryModule.telemetryReport(telemetryPlan, { repository, token, onboarding, notes });
         }
@@ -557,15 +598,10 @@ export async function initCommand(options) {
             telemetry = { telemetry: preview.telemetry, steps: [...preview.steps, `Run \`haystack init --json\` again to read what telemetry Haystack has received (it could not: ${errorText(error)}).`] };
         }
     }
-    const shown = report();
-    for (const line of telemetryModule.formatTelemetry(shown.telemetry, shown.steps))
-        say(line);
-    say('');
-    if (onboarding.state === 'ready')
-        say(chalk.green('Ready. After your next change, run `haystack verify`.'));
-    else if (onboarding.state === 'onboarding') {
-        say(chalk.green('Haystack is preparing the app in the background; the first time can take half an hour.'));
-        say('Keep working: `haystack verify` waits for it when needed, and `haystack verify onboarding --wait` follows it.');
+    if (wantTelemetry) {
+        const shown = report();
+        for (const line of telemetryModule.formatTelemetry(shown.telemetry, shown.steps))
+            say(line);
     }
     finish('done', onboarding, setUpExitCode(onboarding));
 }

package/dist/commands/verify-onboarding.js

@@ -117,6 +117,8 @@ export function parseOnboardingStatus(value, expected) {
     const recordUpdate = value.recordUpdate;
     if (!(recordUpdate === null || (ready && isRecord(recordUpdate) && typeof recordUpdate.of === 'string' && SHA256.test(recordUpdate.of)
         && typeof recordUpdate.crawlRunId === 'string' && (recordUpdate.side === 'base' || recordUpdate.side === 'head')
+        && (recordUpdate.cause === undefined || recordUpdate.cause === 'world-build-failed' || recordUpdate.cause === 'app-broken')
+        && (recordUpdate.cause !== 'app-broken' || recordUpdate.side === 'base')
         && typeof recordUpdate.workCommit === 'string' && COMMIT.test(recordUpdate.workCommit)
         && Array.isArray(recordUpdate.changes) && recordUpdate.changes.every(change => isRecord(change) && typeof change.field === 'string'
         && (change.name === null || typeof change.name === 'string') && (change.kind === 'added' || change.kind === 'changed')
@@ -125,6 +127,8 @@ export function parseOnboardingStatus(value, expected) {
     const update = value.update;
     if (!(update === null || (ready && isRecord(update) && typeof update.onboardRunId === 'string' && ONBOARD_RUN_ID.test(update.onboardRunId)
         && (update.side === 'base' || update.side === 'head') && typeof update.crawlRunId === 'string'
+        && (update.cause === 'world-build-failed' || update.cause === 'app-broken')
+        && (update.cause !== 'app-broken' || update.side === 'base')
         && (update.state === 'updating' || update.state === 'blocked' || update.state === 'stopped')
         && (update.state === 'blocked') === (update.block !== null))))
         invalid('its update');
@@ -349,18 +353,19 @@ export function formatOnboarding(status) {
  * line each, and a blocked update's block (what it needs, and what to tell Haystack). */
 export function updateLines(status) {
     const lines = [];
-    const failed = (side) => side === 'base' ? 'the app did not start at its base commit' : 'the change did not start';
+    const failed = (side, cause) => cause === 'app-broken'
+        ? 'the app copy was broken' : side === 'base' ? 'the app did not start at its base commit' : 'the change did not start';
     if (status.recordUpdate) {
         const changes = status.recordUpdate.changes.map(change => `${change.kind} ${change.field === 'env' ? 'variable' : change.field}`
             + `${change.name === null ? '' : ` ${change.name}`}${change.evidence.length ? ` (from ${change.evidence.join(', ')})` : ''}`);
-        lines.push(`Its setup was updated in place after check ${status.recordUpdate.crawlRunId}, where ${failed(status.recordUpdate.side)}`
+        lines.push(`Its setup was updated in place after check ${status.recordUpdate.crawlRunId}, where ${failed(status.recordUpdate.side, status.recordUpdate.cause)}`
             + `${changes.length ? `: ${changes.join('; ')}` : ''}.`);
     }
     const update = status.update;
     if (update === null)
         return lines;
     if (update.state === 'updating') {
-        lines.push(`Updating the setup (${update.onboardRunId}): check ${update.crawlRunId} found ${failed(update.side)}. The check runs `
+        lines.push(`Updating the setup (${update.onboardRunId}): check ${update.crawlRunId} found ${failed(update.side, update.cause)}. The check runs `
             + 'again on the updated setup when it is ready.');
     }
     else if (update.state === 'stopped') {
@@ -370,7 +375,7 @@ export function updateLines(status) {
     else {
         lines.push(update.side === 'head'
             ? chalk.bold(`Finding: check ${update.crawlRunId}'s change does not start, and no change to the setup started it.`)
-            : chalk.bold(`Haystack could not update the setup for check ${update.crawlRunId}, where the app did not start at its base commit.`));
+            : chalk.bold(`Haystack could not update the setup for check ${update.crawlRunId}, where ${failed(update.side, update.cause)}.`));
         if (update.block)
             lines.push(...blockLines(update.block));
     }

package/dist/index.js

@@ -89,7 +89,8 @@ program
     .description('Set this repository up for `haystack verify` and start onboarding the app')
     .option('-y, --yes', 'Make the changes without asking')
     .option('--notes <file>', 'A JSON file (- for stdin) of what you know about running the app; see below')
-    .option('--app <dir>', 'The app whose telemetry init sets up, when the repository has several; see below')
+    .option('--telemetry', 'Also set up tracking of how real users use the live app (optional; needs the app\'s owner); see below')
+    .option('--app <dir>', 'With --telemetry: the app whose telemetry init sets up, when the repository has several')
     .option('--origin <url>', 'A production origin of the app (repeat for several): browser capture accepts events only from these', (value, previous = []) => [...previous, value])
     .option('--consent <choice>', 'How the site asks visitors for consent: its consent platform, or not-required when your user decided so')
     .option('--url-rewrites <answer>', 'When init asks: none, or hidden-segment:<name> when the app\'s middleware adds a leading [<name>] segment to page paths')
@@ -105,12 +106,19 @@ it with --yes (or a yes at the prompt):
   • a short note in AGENTS.md (and CLAUDE.md when the repository keeps one)
     telling coding agents to run \`haystack verify\` after a change
 Then it starts onboarding the app, so it is usually ready by the first
-\`haystack verify\`. Running it again changes only what is missing and shows
-where onboarding is (\`haystack verify onboarding\` shows that too).
+\`haystack verify\`.
+
+Every run does all it can, then ends with a short checklist and exactly one
+"Next:" line: a command to run, a question to ask your user, a wait, or
+"Ready". Keep running what Next says until it says Ready; running init again
+changes only what is missing and picks up where it stopped. It never asks a
+yes/no question when a coding agent runs it: it shows the changes and says to
+run it again with --yes.
 
 --notes tells onboarding what a coding agent working here already knows, so it
 does not have to work it out (a wrong guess at the start command can cost half
-an hour). The file is JSON with any of three notes, each plain text:
+an hour). Run \`haystack init\` without --yes first: it changes nothing and says
+whether the app is already set up, when notes are not needed. The file is JSON with any of three notes, each plain text:
   run       how production installs, builds and starts the app: the commands
             and their directory, the port, the databases and services and their
             versions, migrations, the environment variables it needs (names and
@@ -123,10 +131,13 @@ onboarding (an onboarding that stopped on a question starts again with them);
 after it, the next check that cannot start the app uses them to update the
 setup in place.
 
-Every run also plans telemetry for the app: --app names it when the repository
-has several (init never picks one), --origin its production origins and
---consent the consent choice; until they are given, only telemetry waits and
-its report says what to ask. Server telemetry: a Next.js app's next.config
+--telemetry (optional, after the app is ready) also sets up tracking of how
+real users use the live app. It needs the app's owner: their yes, the app's
+live web address, a token and a deploy, so a plain init never does it. --app
+names the app when the repository has several (init never picks one), --origin
+its production origins and --consent the consent choice (each implies
+--telemetry); until they are given, only telemetry waits and Next says what
+to ask. Server telemetry: a Next.js app's next.config
 gains the withHaystackTelemetry wrapper in its own export form; a Node server
 whose build ends in a \`tsc\` compile gains \`haystack telemetry instrument\`
 after it; the CLI becomes a checked, exact-version dependency through the
@@ -134,10 +145,11 @@ app's package manager; \`haystack telemetry settings --propose\` writes a
 settings proposal that only your user approves (\`--approve\`). Each is a
 change shown first like the others, and a failed install restores every file.
 init never mints the ingest token: a repository admin runs
-\`haystack telemetry token\` themselves. \`--json\` reports \`telemetry\`
-(each part installed, manual or unsupported, and what Haystack last received)
-and \`telemetrySteps\` (what the person does next, including the off switch
-HAYSTACK_TELEMETRY=0).
+\`haystack telemetry token\` themselves. With --telemetry, \`--json\` reports
+\`telemetry\` (each part installed, manual or unsupported, and what Haystack
+last received) and \`telemetrySteps\` (what the person does next, including
+the off switch HAYSTACK_TELEMETRY=0); \`--json\` always reports \`ready\`,
+\`checklist\` and \`next\`.
 
 Browser capture: --consent is cookiebot, onetrust:<category id>, not-required
 or manual. init adds the self-hosted tag, its consent wiring and the build
@@ -159,6 +171,7 @@ Examples:
   haystack init
   haystack init --yes
   haystack init --yes --json --notes haystack-notes.json
+  haystack init --telemetry
 `)
     .action(options => runPublicCommand(() => initCommand(options), options.json));
 const verify = program
@@ -215,9 +228,11 @@ own setup, its own requests failing in both builds), the crawl could not test
 your change, and it says so first: "We couldn't test your change: the app copy
 is broken.", why, what the start screen showed, the requests that failed and
 the console errors, and what to do: find what those errors need in the
-repository's own setup (docker compose files, env examples, docs), send that
-with \`haystack feedback\` (a copy that starts but is broken does not update its
-setup yet), and tell your user the change was not tested. What the crawl
+repository's own setup (docker compose files, env examples, docs), write that
+in the "run" field of a JSON notes file, then run \`haystack init --notes <file>\`
+and \`haystack verify\` again. Haystack repairs the existing setup with those
+notes and reruns the check when ready. Tell your user this check did not test
+the change. What the crawl
 found in the broken copy is listed after it, marked as such.
 
 The first verify on a base the service has not onboarded yet prepares the app

package/dist/schema.js

@@ -17,7 +17,7 @@ export const SCHEMA_VERSIONS = {
     'verify-raw': '1.3.0',
     'verify-answer': '1.0.1',
     'verify-onboarding': '1.0.0',
-    init: '1.0.2',
+    init: '2.0.0',
     login: '1.0.0',
     feedback: '1.0.0',
     error: '1.0.0',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haystackeditor/cli",
-  "version": "0.30.2",
+  "version": "0.31.0",
   "description": "haystack verify: run your app with and without a change, and see what the change broke",
   "type": "module",
   "bin": {

package/schemas/init.v2.json

@@ -0,0 +1,299 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://docs.haystackeditor.com/cli/schemas/init.v2.json",
+  "title": "Haystack init: this repository's setup for `haystack verify`",
+  "description": "Machine-readable output of `haystack init --json`. `changes` are the project-local changes init planned (made when status is done); `onboarding` is the base's OnboardingStatusV1 (onboarding_contracts.ts, APP-ONBOARDING-V1) as POST /api/agent/cloud-verifier/onboarding returns it, null unless status is done. `notes` says what became of `--notes`: \"written\" (the repository's onboarding notes are now these), \"unchanged\" (they already were), null without `--notes` or when init stopped before writing them. Exit codes: 0 done (onboarding running or ready), 1 failed (the error envelope), 2 planned (nothing written; run with --yes), 3 done but onboarding blocked, 4 login-required, 5 app-required (install the Haystack GitHub App), 6 done but onboarding stopped before finishing (run init again). `telemetry` (CAPTURE-V1 rule 8e, InitTelemetryReport in capture_contracts.ts) is what telemetry does (status done) or will do (planned, login-required: the same report before anything is written, every `received` null because nothing was checked): per part (`capture`, the browser tag; `server`, server telemetry) `installed`, `manual` with the exact `steps`, or `unsupported` with `why`, and `received`, the newest telemetry Haystack holds for this application (null when none; `stale` past 24 hours), plus `dbProfileCommand`, the `haystack db profile` command for the user to run with production read access (null when the app's database is not one it profiles). `telemetrySteps` is what the person does next for telemetry to arrive, in order, including the off switches; [] without telemetry. 2.0.0 (2026-10-07): every run ends with `ready`, a `checklist` and exactly one `next` step; telemetry is planned only with --telemetry (or one of its answers), so `telemetry` is null and `telemetrySteps` empty without it.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "status",
+    "repository",
+    "ready",
+    "checklist",
+    "next",
+    "changes",
+    "notices",
+    "notes",
+    "onboarding",
+    "telemetry",
+    "telemetrySteps"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": "2.0.0"
+    },
+    "status": {
+      "enum": [
+        "done",
+        "planned",
+        "login-required",
+        "app-required"
+      ]
+    },
+    "repository": {
+      "type": "string"
+    },
+    "ready": {
+      "type": "boolean",
+      "description": "The test copy of the app is set up: run `haystack verify` after each change."
+    },
+    "checklist": {
+      "type": "array",
+      "description": "What is done and what is left, in order.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "item",
+          "state",
+          "detail"
+        ],
+        "properties": {
+          "item": {
+            "type": "string"
+          },
+          "state": {
+            "enum": [
+              "done",
+              "running",
+              "todo",
+              "skipped",
+              "optional"
+            ]
+          },
+          "detail": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "next": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind",
+        "text",
+        "command"
+      ],
+      "description": "Exactly one next step: run (a command the coding agent runs), ask-user (only the user can do or answer it; text says what to ask), wait (a long step to wait out, then run `command`), none (nothing left, or nothing that can be run).",
+      "properties": {
+        "kind": {
+          "enum": [
+            "run",
+            "ask-user",
+            "wait",
+            "none"
+          ]
+        },
+        "text": {
+          "type": "string"
+        },
+        "command": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "changes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "path",
+          "action",
+          "reason",
+          "diff"
+        ],
+        "properties": {
+          "path": {
+            "type": "string"
+          },
+          "action": {
+            "enum": [
+              "create",
+              "update",
+              "delete"
+            ]
+          },
+          "reason": {
+            "type": "string"
+          },
+          "diff": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "notices": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "notes": {
+      "oneOf": [
+        {
+          "type": "null"
+        },
+        {
+          "enum": [
+            "written",
+            "unchanged"
+          ]
+        }
+      ]
+    },
+    "onboarding": {
+      "oneOf": [
+        {
+          "type": "null"
+        },
+        {
+          "$ref": "verify.v1.json#/$defs/onboardingStatus"
+        }
+      ]
+    },
+    "telemetry": {
+      "description": "Null unless telemetry was asked for (--telemetry or one of its answers).",
+      "anyOf": [
+        {
+          "type": "null"
+        },
+        {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "capture",
+                "server",
+                "dbProfileCommand"
+              ],
+              "properties": {
+                "capture": {
+                  "$ref": "#/$defs/telemetryPart"
+                },
+                "server": {
+                  "$ref": "#/$defs/telemetryPart"
+                },
+                "dbProfileCommand": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                }
+              }
+            }
+          ]
+        }
+      ]
+    },
+    "telemetrySteps": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "$defs": {
+    "telemetryPart": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "status",
+            "received"
+          ],
+          "properties": {
+            "status": {
+              "const": "installed"
+            },
+            "received": {
+              "$ref": "#/$defs/telemetryReceived"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "status",
+            "steps",
+            "received"
+          ],
+          "properties": {
+            "status": {
+              "const": "manual"
+            },
+            "steps": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "received": {
+              "$ref": "#/$defs/telemetryReceived"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "status",
+            "why"
+          ],
+          "properties": {
+            "status": {
+              "const": "unsupported"
+            },
+            "why": {
+              "type": "string"
+            }
+          }
+        }
+      ]
+    },
+    "telemetryReceived": {
+      "oneOf": [
+        {
+          "type": "null"
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "lastSeenAt",
+            "release",
+            "stale"
+          ],
+          "properties": {
+            "lastSeenAt": {
+              "type": "string"
+            },
+            "release": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "stale": {
+              "type": "boolean"
+            }
+          }
+        }
+      ]
+    }
+  }
+}