ccqa 1.13.0 → 1.14.0

package/README.md

@@ -152,7 +152,7 @@ where the shared state lives — there is no second place to put it:
   current by `record`/`generate`
 - the variables `${…}` resolve to, and saved browser sessions, fetched at run
   time — so CI holds one secret instead of an environment
-- the deploy log behind `--only-stale`, and the drift ledger
+- the deploy log behind `--only-hub-stale`, and the drift ledger
 - a dashboard of runs with per-step screenshots, triage grading, and the
   prompts learned from those grades
 
@@ -186,7 +186,7 @@ All three need two things:
 - **A Claude credential.** Replaying a recorded spec uses no model, but the
   change selection, the failure analysis and the audit all do.
 - **A running [hub](#the-hub)**, reached with `CCQA_HUB_URL` and
-  `CCQA_HUB_TOKEN`. Only a pre-merge run with no `--profile` and no
+  `CCQA_HUB_TOKEN`. Only a pre-merge run with no `--hub-profile` and no
   `--report-to-hub` can do without one.
 
 See [Environment variables](./docs/commands.md#environment-variables) for the
@@ -201,7 +201,7 @@ once, from your machine:
 ccqa hub var set APP_URL --value https://app.example --profile staging
 ```
 
-Pass the same `--profile` and `--project` in every job. That is what makes the
+Pass the same `--hub-profile` and `--project` in every job. That is what makes the
 jobs refer to the same environment.
 
 ### On a pull request
@@ -209,14 +209,14 @@ jobs refer to the same environment.
 Run the specs the change reaches, and label what broke.
 
 ```bash
-ccqa run --only-affected-by --on-fail-explain --profile staging \
+ccqa run --only-affected-by --on-fail-explain --hub-profile staging \
   --report-format github --report-to-hub
 ```
 
 - `--only-affected-by` selects the specs the diff reaches. A spec it cannot clear runs
   anyway.
 - `--on-fail-explain` labels the cause of each failure.
-- `--profile staging` fetches that environment's variables and saved sessions
+- `--hub-profile staging` fetches that environment's variables and saved sessions
   from the hub. Without it, a spec's `${…}` references go unresolved.
 - `--report-format github` annotates the pull request.
 - `--report-to-hub` streams results to the hub as the run executes.
@@ -242,12 +242,12 @@ ccqa hub deploy record --profile staging --sha "$GITHUB_SHA" --select
 Then, in a job of its own, run what that deploy invalidated:
 
 ```bash
-ccqa run --only-stale --profile staging --report-to-hub
+ccqa run --only-hub-stale --hub-profile staging --report-to-hub
 ```
 
 - `--select` records which specs the deployed range reaches. Without it, every
   spec behind that entry answers `unknown` instead of `notNeeded`.
-- `--only-stale` asks the hub, per spec, whether any deploy has touched
+- `--only-hub-stale` asks the hub, per spec, whether any deploy has touched
   it since that spec last ran.
 
 The hub has no checkout and never runs `git`, so it cannot work out what a
@@ -260,7 +260,7 @@ a hole nothing can fill in afterwards.
 runs by default. Record a deploy, run every spec once with `--report-to-hub`,
 and the selection means something from the next deploy on. This job also reads
 the spec inventory from the hub, so `ccqa perspectives` has to have run.
-`--only-stale-with-unknown` opts the undecided specs in.
+`--only-hub-stale-with-unknown` opts the undecided specs in.
 
 ### On a schedule
 

package/dist/bin/ccqa.mjs

@@ -477,7 +477,7 @@ function getBlocksDir(cwd) {
 /**
 * Inverse of `getBlockDir`. Given a file path that appears in a git diff,
 * return the block name if the path points at the block's spec.yaml, else
-* null. Used by `drift --changed` to invalidate specs whose included blocks
+* null. Used by `audit --only-affected-by` to invalidate specs whose included blocks
 * were edited. (v0.4 inlines blocks into every spec's own trace, so the
 * block directory holds only spec.yaml — no per-block recording lives
 * here anymore.)
@@ -524,24 +524,22 @@ const USER_PROMPT_MAX_BYTES = 32768;
 * Load the prompt bundle from the hub for one guidance kind ("record" /
 * "live" / an LLM-generation target such as "playwright" or "runn").
 * Best-effort: no hub client, a fetch failure, or both prompts absent all
-* resolve to null — a broken/missing hub prompt must never stop a run.
+* A prompt that was never stored resolves to null. A hub that cannot be
+* reached throws: running with silently different guidance than the project
+* configured is worse than stopping.
 */
 async function loadPromptBundleFromHub(ctx, kind) {
 	if (!ctx) return null;
 	const userName = `${kind}.user`;
 	const agentName = `${kind}.agent`;
-	try {
-		const [userText, agentText] = await Promise.all([ctx.hub.getPrompt(ctx.project, userName).then(normalizePromptText), ctx.hub.getPrompt(ctx.project, agentName).then(normalizePromptText)]);
-		return assemblePromptBundle({
-			text: userText,
-			label: userName
-		}, {
-			text: agentText,
-			label: agentName
-		});
-	} catch {
-		return null;
-	}
+	const [userText, agentText] = await Promise.all([ctx.hub.getPrompt(ctx.project, userName).then(normalizePromptText), ctx.hub.getPrompt(ctx.project, agentName).then(normalizePromptText)]);
+	return assemblePromptBundle({
+		text: userText,
+		label: userName
+	}, {
+		text: agentText,
+		label: agentName
+	});
 }
 /**
 * Shared concatenation logic behind `loadPromptBundleFromHub`: section
@@ -557,7 +555,7 @@ function assemblePromptBundle(user, agent) {
 		loaded.push(user.label);
 	}
 	if (agent.text !== null) {
-		sections.push(`### Agent learnings (auto-updated by ccqa --update-agent-prompt)\n\n${agent.text}`);
+		sections.push(`### Agent learnings (auto-updated by ccqa's --learn-*-prompt flags)\n\n${agent.text}`);
 		loaded.push(agent.label);
 	}
 	let text = sections.join("\n\n");
@@ -2475,7 +2473,7 @@ const FailureAnalysisSchema = z.object({
 });
 /**
 * What a drift audit may conclude, in the same vocabulary `ccqa run
-* --failure-analysis` uses for a failure. One question, one answer, the same
+* --on-fail-explain` uses for a failure. One question, one answer, the same
 * words whether it was reached by running the spec or by reading the code — so
 * a reader never translates between two taxonomies, and the hub renders,
 * grades and learns from both through one path.
@@ -3312,7 +3310,7 @@ function relativeToCwd(path, cwd) {
 /** The model's reply: a diagnosis, or `null` for "the spec still matches the code". */
 const DriftReplySchema = z.object({ drift: DriftDiagnosisSchema.nullable() });
 /**
-* How a label reads against `--severity`. The threshold asks "would a
+* How a label reads against `--exit-on`. The threshold asks "would a
 * deterministic replay fail today", which is what the label already answers:
 * both findings mean the spec no longer describes the code, while `UNKNOWN`
 * means the audit could not tell and should not fail a build on its own.
@@ -3971,14 +3969,10 @@ ${customPrompt.guidance}
 */
 async function fetchCustomPrompt(ctx) {
 	if (!ctx) return null;
-	try {
-		const raw = await ctx.hub.getPrompt(ctx.project, "analysis-custom-prompt");
-		if (raw === null) return null;
-		const parsed = AnalysisCustomPromptSchema.safeParse(JSON.parse(raw));
-		return parsed.success ? parsed.data : null;
-	} catch {
-		return null;
-	}
+	const raw = await ctx.hub.getPrompt(ctx.project, "analysis-custom-prompt");
+	if (raw === null) return null;
+	const parsed = AnalysisCustomPromptSchema.safeParse(JSON.parse(raw));
+	return parsed.success ? parsed.data : null;
 }
 /**
 * Render the human-maintained `triage.user` guidance as a prompt section, or
@@ -4006,12 +4000,8 @@ ${trimmed}
 */
 async function fetchTriageUserPrompt(ctx) {
 	if (!ctx) return null;
-	try {
-		const trimmed = (await ctx.hub.getPrompt(ctx.project, "triage.user"))?.trim();
-		return trimmed ? trimmed : null;
-	} catch {
-		return null;
-	}
+	const trimmed = (await ctx.hub.getPrompt(ctx.project, "triage.user"))?.trim();
+	return trimmed ? trimmed : null;
 }
 /**
 * Short, stable content hash for a `triage.user` prompt. The Markdown body
@@ -4812,12 +4802,12 @@ async function readDotenv(path) {
 	}
 	return parseDotenv(content);
 }
-/** Absolute path of the default `.env` ccqa loads when `--profile` is absent. */
+/** Absolute path of the default `.env` ccqa loads when `--hub-profile` is absent. */
 function defaultEnvPath(cwd) {
 	return join(cwd, ".env");
 }
 /**
-* Load `<cwd>/.env`, the default when no `--profile` is given. A missing `.env`
+* Load `<cwd>/.env`, the default when no `--hub-profile` is given. A missing `.env`
 * is fine (returns `null`) — the run falls back to the existing `process.env`.
 */
 async function loadDefaultEnv(cwd) {
@@ -5023,7 +5013,7 @@ function addLanguageOption(command) {
 * `record`), registered identically so help text and behaviour don't drift.
 */
 function addProfileOption(command) {
-	return command.option("--profile <name>", "Load this profile's variables from the hub into the environment before resolving spec ${VAR} references (URLs, credentials), so one spec can target dev/stg/prd without per-environment copies. Profile values override the inherited environment. Requires --hub-url/--hub-token (or CCQA_HUB_URL/CCQA_HUB_TOKEN).");
+	return command.option("--hub-profile <name>", "Load this profile's variables from the hub into the environment before resolving spec ${VAR} references (URLs, credentials), so one spec can target dev/stg/prd without per-environment copies. Profile values override the inherited environment. Requires --hub-url/--hub-token (or CCQA_HUB_URL/CCQA_HUB_TOKEN).");
 }
 /**
 * Shared `--hub-url` / `--hub-token` flags for commands that optionally talk
@@ -5901,7 +5891,7 @@ async function runVerificationLoop(p, ref, state) {
 	const runCommand = p.ctx.targetConfig.runCommand;
 	if (!runCommand) return true;
 	const maxRetries = p.ctx.fix.mode === "non-interactive" ? 0 : p.ctx.fix.maxRetries;
-	if (!p.ctx.fix.useSnapshot) warn(`--no-snapshot has no effect on the ${p.target} target — it captures no browser snapshot; the fix loop uses the command's output instead`);
+	if (!p.ctx.fix.useSnapshot) warn(`--no-session-pin has no effect on the ${p.target} target — it captures no browser snapshot; the fix loop uses the command's output instead`);
 	for (let attempt = 0;; attempt++) {
 		const testFiles = [...state.entries()].filter(([, f]) => f.kind === "test").map(([rel]) => rel);
 		const artifactsDir = await mkdtemp(join(tmpdir(), "ccqa-verify-artifacts-"));
@@ -6089,8 +6079,8 @@ const C$1 = {
 * script, so it keeps its own caller in `cli/run-live.ts`; only the
 * `ANALYSIS_DISABLED` string is shared with it.
 */
-/** `analysisSkipped` for a failed row when `--failure-analysis` was not requested. */
-const ANALYSIS_DISABLED = "skipped: --failure-analysis not enabled";
+/** `analysisSkipped` for a failed row when `--on-fail-explain` was not requested. */
+const ANALYSIS_DISABLED = "skipped: --on-fail-explain not enabled";
 /**
 * Create one analysis pass. The returned object is stateful on purpose: the
 * "source diff unavailable" notice and the summary block's header are printed
@@ -6610,7 +6600,7 @@ async function detectDefaultBranch(cwd) {
 /**
 * Fetch the last-green ledger for this run — one hub round trip, logged as
 * the run's analysis-base meta line. Fails fast (RunUsageError) when the hub
-* can't serve it: `--failure-analysis=last-green` explicitly opted into
+* can't serve it: `--on-fail-explain` explicitly opted into
 * hub-backed baselines, so a broken hub connection is a usage error, never a
 * silent no-baseline run.
 */
@@ -6633,7 +6623,7 @@ async function fetchLastGreenLedger(hubCtx, profile, cwd) {
 	return entries;
 }
 /**
-* Per-spec baseline resolver for `--failure-analysis=last-green`. A spec
+* Per-spec baseline resolver for `--on-fail-explain` without an explicit base. A spec
 * missing from the ledger (never green on a pushed run yet) or whose
 * baseline commit isn't in this checkout resolves to a skip — the run
 * continues; only that spec's classification is withheld, with the reason
@@ -6687,7 +6677,7 @@ async function deployHeadSha(hub, project, profile) {
 *
 * Captured before any spec executes and asserted on both push paths
 * (`?deployedSha=` on `POST /runs` via `ccqa hub push`, and on `POST
-* /runs/open` for `--push-report`). Left to itself the hub reads its own
+* /runs/open` for `--report-to-hub`). Left to itself the hub reads its own
 * deploy-log head when the call lands — after the whole run for a single-shot
 * push, after the deterministic phase for an incremental one — so a deploy
 * landing in that window would be recorded as the run's baseline and
@@ -6712,7 +6702,7 @@ async function tryDeployHeadSha(hubCtx, profile) {
 *
 * This exists because a selection can be wrong in a way that costs money.
 * `ccqa select-specs`'s model judgment is not infallible, and both
-* `--changed <ref>` and `--changed=last-run` decide from it, so a human has to
+* `--only-affected-by` and `--only-hub-stale` decide from it, so a human has to
 * be able to read the selection back before a live spec spends a Claude
 * budget on it.
 *
@@ -6758,7 +6748,7 @@ async function fetchAuditedLedger(hubCtx) {
 	try {
 		ledger = await hubCtx.hub.getDriftLedger(hubCtx.project);
 	} catch (err) {
-		throw new RunUsageError(`--only-audited-clean: could not fetch the drift ledger from the hub: ${errMessage(err)}`);
+		throw new RunUsageError(`--only-hub-audited-clean: could not fetch the drift ledger from the hub: ${errMessage(err)}`);
 	}
 	const clean = /* @__PURE__ */ new Set();
 	const audited = /* @__PURE__ */ new Set();
@@ -6790,7 +6780,7 @@ function selectAuditedClean(specs, ledger) {
 //#endregion
 //#region src/run/rerun-selection.ts
 /**
-* `ccqa run --changed=last-run`: select specs from the hub's re-run verdicts
+* `ccqa run --only-hub-stale`: select specs from the hub's re-run verdicts
 * instead of from a git diff (ADR-0010). The baseline is not a ref at all —
 * it is each spec's own last run, positioned against the deploy log the
 * consuming deploy job feeds the hub — so this path does no git work.
@@ -6802,12 +6792,12 @@ function selectAuditedClean(specs, ledger) {
 /** First ccqa release whose hub serves `GET /projects/:project/rerun`. */
 const RERUN_MIN_HUB_VERSION = "1.9";
 /**
-* The profile `--changed=last-run` asks about. Mandatory: two environments sit
+* The profile `--only-hub-stale` asks about. Mandatory: two environments sit
 * at different commits and the deploy log is per-profile, so "needs re-run"
 * has no profile-free answer.
 */
 function requireRerunProfile(profile) {
-	if (profile === void 0) throw new RunUsageError("--only-stale requires --profile <name>: the deploy log it reads is per-profile, so which specs need a re-run has no answer without one");
+	if (profile === void 0) throw new RunUsageError("--only-hub-stale requires --hub-profile <name>: the deploy log it reads is per-profile, so which specs need a re-run has no answer without one");
 	return profile;
 }
 /**
@@ -6820,9 +6810,9 @@ async function fetchRerunReport(hubCtx, profile) {
 		report = await hubCtx.hub.getRerun(hubCtx.project, { profile });
 	} catch (err) {
 		if (err instanceof HubApiError && err.status === 404) throw new RunUsageError(explainNotFound(hubCtx, err));
-		throw new RunUsageError(`--only-stale: could not ask the hub which specs need a re-run: ${errMessage(err)}`);
+		throw new RunUsageError(`--only-hub-stale: could not ask the hub which specs need a re-run: ${errMessage(err)}`);
 	}
-	if (report.deployHead === null) throw new RunUsageError(`--only-stale: no deploy has been recorded for profile "${profile}" of project "${hubCtx.project}", so nothing can be compared against. Wire \`ccqa hub deploy record\` into the deploy job, or pass an explicit baseline (--changed=<ref>).`);
+	if (report.deployHead === null) throw new RunUsageError(`--only-hub-stale: no deploy has been recorded for profile "${profile}" of project "${hubCtx.project}", so nothing can be compared against. Wire \`ccqa hub deploy record\` into the deploy job, or select with --only-affected-by <ref> instead.`);
 	return {
 		...report,
 		deployHead: report.deployHead
@@ -6834,8 +6824,8 @@ async function fetchRerunReport(hubCtx, profile) {
 * means the hub does not serve this route at all.
 */
 function explainNotFound(hubCtx, err) {
-	if (err.code === "no_perspectives") return `--only-stale: project "${hubCtx.project}" has no perspectives document on the hub, so no spec is registered to compare against a deploy. Run \`ccqa perspectives\` first.`;
-	return `--only-stale: this hub does not serve re-run verdicts — it needs ccqa ${RERUN_MIN_HUB_VERSION} or newer. Upgrade the hub, or pass an explicit baseline (--changed=<ref>).`;
+	if (err.code === "no_perspectives") return `--only-hub-stale: project "${hubCtx.project}" has no perspectives document on the hub, so no spec is registered to compare against a deploy. Run \`ccqa perspectives\` first.`;
+	return `--only-hub-stale: this hub does not serve re-run verdicts — it needs ccqa ${RERUN_MIN_HUB_VERSION} or newer. Upgrade the hub, or select with --only-affected-by <ref> instead.`;
 }
 /** States the summary line reports, worst-known-first. */
 const SUMMARY_ORDER = [
@@ -6856,7 +6846,7 @@ const UNANSWERABLE = new Set([
 *
 * `needed` is always selected. `unknown` and `neverRun` are "the question
 * cannot be answered", so they are excluded by default and opted into with
-* `--include-unknown` — fail-open on request, never silently. `notNeeded` and
+* `--only-hub-stale-with-unknown` — fail-open on request, never silently. `notNeeded` and
 * `notEvaluated` are never selected.
 */
 function selectSpecsNeedingRerun(specs, report, opts) {
@@ -7634,7 +7624,7 @@ function safeOriginPath(href) {
 *
 * Two kinds share one namespace:
 *  - "guidance": the record/live prompt bundle — `.user.md` (human-maintained)
-*    and `.agent.md` (auto-rewritten by `ccqa run --update-agent-prompt`) —
+*    and `.agent.md` (auto-rewritten by `ccqa run --learn-hub-live-prompt`) —
 *    plus `triage.user`, the human-maintained guidance injected into the
 *    failure-analysis (triage) prompt.
 *  - "custom-prompt": `analysis-custom-prompt` — Claude-written calibration guidance
@@ -8103,7 +8093,7 @@ z.object({
 	lastRed: z.record(z.string(), SpecLedgerEntrySchema).default({})
 });
 /**
-* One spec's last drift audit, as recorded by `ccqa drift --push`. Unlike the
+* One spec's last drift audit, as recorded by `ccqa audit --report-to-hub`. Unlike the
 * spec ledger above, this carries no profile: drift asks whether a spec still
 * describes the code, which has nothing to do with which environment is
 * running it (ADR-0010 draws the same line for "needs re-run").
@@ -8313,7 +8303,7 @@ function isCcqaPath(path) {
 }
 /**
 * A malformed reply costs the whole selection, so it is worth one more call
-* before giving up. `ccqa drift` retries per spec for the same reason; this
+* before giving up. `ccqa audit` retries per spec for the same reason; this
 * call carries every undecided spec at once, so the blast radius is larger,
 * not smaller. Observed in practice: three runs over one commit produced a
 * parse failure, a clean answer, and a different clean answer.
@@ -8510,7 +8500,7 @@ const sessionCaptureCommand = new Command("capture").description("Open a headed
 		error(err.message);
 		process.exit(2);
 	}
-	header("session bootstrap", name);
+	header("session capture", name);
 	meta("project", project);
 	meta("profile", opts.profile ?? "default");
 	blank();
@@ -8631,7 +8621,7 @@ const sessionPush = new Command("push").description("Upload a locally-saved brow
 		state = await loadStorageState(path);
 	} catch (err) {
 		error(`could not read session "${name}" at ${path}: ${err instanceof Error ? err.message : String(err)}`);
-		hint(`create it first with:  ccqa session bootstrap ${name}${opts.profile ? ` --profile ${opts.profile}` : ""}`);
+		hint(`create it first with:  ccqa hub session capture ${name}${opts.profile ? ` --profile ${opts.profile}` : ""}`);
 		process.exit(2);
 	}
 	await connect(opts).putSession(project, profile, name, state);
@@ -8718,12 +8708,12 @@ const promptPush = new Command("push").description("Upload a locally-generated p
 		body = await readFile(path, "utf8");
 	} catch (err) {
 		error(`could not read prompt "${name}" at ${path}: ${err instanceof Error ? err.message : String(err)}`);
-		hint("nothing to push; generate it first (e.g. ccqa run --update-agent-prompt)");
+		hint("nothing to push; generate it first (e.g. ccqa run --learn-hub-live-prompt)");
 		process.exit(2);
 	}
 	if (body.trim().length === 0) {
 		error(`prompt "${name}" at ${path} is empty`);
-		hint("nothing to push; generate it first (e.g. ccqa run --update-agent-prompt)");
+		hint("nothing to push; generate it first (e.g. ccqa run --learn-hub-live-prompt)");
 		process.exit(2);
 	}
 	await connect(opts).putPrompt(project, name, body);
@@ -8749,7 +8739,7 @@ const promptRm = new Command("rm").description("Delete a prompt from the hub.").
 	info(`deleted prompt "${name}" from the hub`);
 }));
 const promptCommand = new Command("prompt").description("Manage prompt assets (per-flow user/agent guidance, triage user guidance, analysis custom prompt) stored on the hub (fetched automatically by `ccqa run` at run time).").addCommand(promptPush).addCommand(promptLs).addCommand(promptRm);
-const deployRecord = new Command("record").description("Tell the hub what a deploy shipped, so it can answer which specs need a re-run (`ccqa run --changed=last-run`). Run this from the deploy job, after the deploy succeeds. The changed paths are computed locally with a two-dot `git diff <previous> <sha>`; a job that has only curl and git can POST the same body directly (see docs/hub.md).").requiredOption("--profile <name>", "Environment this deploy landed in (e.g. 'stg'). Required: dev and stg sit at different commits, so the deploy log is per-profile.").requiredOption("--sha <sha>", "Commit that was deployed.").option("--previous <sha>", "Commit this deploy replaced. Defaults to the profile's current deploy-log head on the hub. With neither, there's nothing to diff against: changedPaths is unset and --select is skipped.").option("--ref <ref>", "Ref that was deployed (branch or tag). Recorded for display only.").option("--select", "Also decide which specs this deploy reaches (`ccqa select-specs`) and send the verdict with it. Without it the deploy is a hole in the range: specs behind it report 'unknown' rather than 'not needed'.").option("-m, --model <name>", "Model for --select. Claude alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option(...hubUrlOption).option(...hubTokenOption).option("--project <name>", "Project whose deploy log this entry joins. Defaults to the current directory's name.").option("--cwd <path>", "Directory the git diff and the default --project name are resolved against.").action(withHubErrors(async (opts) => {
+const deployRecord = new Command("record").description("Tell the hub what a deploy shipped, so it can answer which specs need a re-run (`ccqa run --only-hub-stale`). Run this from the deploy job, after the deploy succeeds. The changed paths are computed locally with a two-dot `git diff <previous> <sha>`; a job that has only curl and git can POST the same body directly (see docs/hub.md).").requiredOption("--profile <name>", "Environment this deploy landed in (e.g. 'stg'). Required: dev and stg sit at different commits, so the deploy log is per-profile.").requiredOption("--sha <sha>", "Commit that was deployed.").option("--previous <sha>", "Commit this deploy replaced. Defaults to the profile's current deploy-log head on the hub. With neither, there's nothing to diff against: changedPaths is unset and --select is skipped.").option("--ref <ref>", "Ref that was deployed (branch or tag). Recorded for display only.").option("--select", "Also decide which specs this deploy reaches (`ccqa select-specs`) and send the verdict with it. Without it the deploy is a hole in the range: specs behind it report 'unknown' rather than 'not needed'.").option("-m, --model <name>", "Model for --select. Claude alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option(...hubUrlOption).option(...hubTokenOption).option("--project <name>", "Project whose deploy log this entry joins. Defaults to the current directory's name.").option("--cwd <path>", "Directory the git diff and the default --project name are resolved against.").action(withHubErrors(async (opts) => {
 	const cwd = resolveCwd(opts.cwd);
 	const project = resolveProject(opts);
 	const hub = connect(opts);
@@ -8828,7 +8818,7 @@ function describeSelection(selection, diffAvailable) {
 	const values = Object.values(selection);
 	return `${values.filter((s) => s.verdict === "needed").length} needed / ${values.filter((s) => s.verdict === "unknown").length} unknown / ${values.length} specs`;
 }
-const deployCommand = new Command("deploy").description("Report deploys to the hub, the input behind `ccqa run --changed=last-run`.").addCommand(deployRecord);
+const deployCommand = new Command("deploy").description("Report deploys to the hub, the input behind `ccqa run --only-hub-stale`.").addCommand(deployRecord);
 const pushCommand = new Command("push").description("Upload the report directory of a finished `ccqa run --report` to the hub as a run. Run this after `ccqa run` (use `if: always()` in CI so failing runs are pushed too).").option("--report-dir <dir>", `Report directory to push. Default: ${DEFAULT_REPORT_DIR}/`).option("--project <name>", "Logical project name for the run. Defaults to the current directory's name.").option("--branch <name>", "Branch label. Defaults to $GITHUB_HEAD_REF / $GITHUB_REF_NAME / current git branch.").option("--profile <name>", "Profile (environment) the run executed against. Recorded for display; runs are not scoped by profile.").option(...hubUrlOption).option(...hubTokenOption).option("--cwd <path>", "Directory the report dir is resolved against (defaults to the current directory).").action(withHubErrors(async (opts) => {
 	const cwd = resolveCwd(opts.cwd);
 	const reportDir = join(cwd, opts.reportDir ?? "ccqa-report");
@@ -8971,7 +8961,7 @@ function generateLiveSessionName() {
 * Project-specific guidance ("the admin tenant is foo.example", "session
 * times out at X minutes", …) is appended from
 * `.ccqa/prompts/live.user.md` (human-maintained) and
-* `.ccqa/prompts/live.agent.md` (updated by `ccqa run --update-agent-prompt`)
+* `.ccqa/prompts/live.agent.md` (updated by `ccqa run --learn-hub-live-prompt`)
 * by the caller, so ccqa stays clean of downstream-product context.
 *
 * Constraint posture: `ccqa record` (trace) enforces a strict selector
@@ -9726,7 +9716,7 @@ const verifiedSessions = /* @__PURE__ */ new Set();
 * each named session from the hub (`.ccqa/sessions/*.json` is no longer
 * read here). Every name must load as a valid agent-browser state (the spec
 * assumes it starts signed-in); a missing/malformed session fails with a
-* `ccqa session bootstrap` hint instead of running unauthenticated.
+* `ccqa hub session capture` hint instead of running unauthenticated.
 *
 * If a session carries an embedded verify URL (bootstrap saved it), the
 * restore is health-checked before the run starts, so an expired/unusable
@@ -9769,7 +9759,7 @@ async function resolveSessionState(names, hubCtx, profile, verify = verifySessio
 				if (!check.restored) return {
 					ok: false,
 					error: `session '${name}' did not restore to a signed-in page — ${check.reason}`,
-					hint: `re-bootstrap it: ccqa session bootstrap ${name}${profileFlag}`
+					hint: `re-bootstrap it: ccqa hub session capture ${name}${profileFlag}`
 				};
 				verifiedSessions.add(memoKey);
 			}
@@ -9779,7 +9769,7 @@ async function resolveSessionState(names, hubCtx, profile, verify = verifySessio
 	if (broken.length > 0) return {
 		ok: false,
 		error: `session not usable on the hub: ${broken.join(", ")}`,
-		hint: `create it with: ${broken.map((name) => `ccqa session bootstrap ${name}${profileFlag}`).join("  ·  ")}`
+		hint: `create it with: ${broken.map((name) => `ccqa hub session capture ${name}${profileFlag}`).join("  ·  ")}`
 	};
 	const statePath = await writeMergedTempState(mergeStorageStates(loaded));
 	return {
@@ -11652,7 +11642,7 @@ async function groupSpecsByTarget(specs, config, cwd, resolve = resolveTarget) {
 * then each external target group through its runner. Every row is upserted
 * into the incremental report the moment it exists — the runner reports each
 * spec through `onSpecComplete` as it finishes — so an interrupt keeps what
-* already ran and `--push-report` streams spec by spec. Rows are also
+* already ran and `--report-to-hub` streams spec by spec. Rows are also
 * returned for the tail phase (failure analysis) and the final batch write. A
 * crashing runner marks its own specs failed instead of aborting the run.
 */
@@ -11788,7 +11778,7 @@ function createIncrementalReport(reportDir, envelope, sink) {
 //#endregion
 //#region src/prompts/agent-update.ts
 /**
-* Build the prompts used by `--update-agent-prompt` to refresh
+* Build the prompts used by the `--learn-*-prompt` flags to refresh
 * `.ccqa/prompts/<kind>.agent.md` after a run:
 *   - `ccqa run` (live) → `live.agent`
 *   - `ccqa record` (trace) → `record.agent`
@@ -12044,10 +12034,7 @@ async function updateAgentPrompt(args) {
 		warn(`${flag} skipped (${auth.reason})`);
 		return;
 	}
-	if (!hubContext) {
-		warn(`${flag} skipped (hub connection required; pass --hub-url/--hub-token or set CCQA_HUB_URL/CCQA_HUB_TOKEN)`);
-		return;
-	}
+	if (!hubContext) throw new Error(`${flag} requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)`);
 	const { hub, project } = hubContext;
 	const promptName = `${kind}.agent`;
 	try {
@@ -12169,6 +12156,19 @@ async function resolveVitestConfig(cwd) {
 function resolveReportDir(reportDir, cwd) {
 	return resolve(cwd, reportDir ?? "ccqa-report");
 }
+/**
+* Turn a hub transport failure into a usage error, as a `.catch` so the
+* tuple types of the `Promise.all` it guards survive.
+*
+* Without it the raw `fetch failed` escapes as an unhandled rejection: a stack
+* trace and exit 1, where the user needs "the hub is unreachable" and exit 2.
+* Errors the callers already shaped pass through — they say more than this
+* wrapper could.
+*/
+function asHubReadError(err) {
+	if (err instanceof RunUsageError) throw err;
+	throw new RunUsageError(`could not read from the hub: ${errMessage(err)}`);
+}
 /** De-dupe by `featureName/specName`, keeping first-seen order. */
 function dedupeSpecs(specs) {
 	const seen = /* @__PURE__ */ new Set();
@@ -12189,10 +12189,10 @@ function dedupeSpecs(specs) {
 * maps it to `process.exit(2)`).
 */
 async function executeRun(targets, opts) {
-	const filtering = Boolean(opts.onlyAffectedBy || opts.onlyStale || opts.onlyAuditedClean);
+	const filtering = Boolean(opts.onlyAffectedBy || opts.onlyHubStale || opts.onlyHubAuditedClean);
 	if (filtering && targets.length > 0) throw new RunUsageError("a --only-* filter and an explicit spec target cannot be combined");
-	const rerunProfile = opts.onlyStale === true ? requireRerunProfile(opts.profile) : null;
-	if (opts.onlyStaleWithUnknown && rerunProfile === null) warn("--only-stale-with-unknown is ignored: it only applies to --only-stale");
+	const rerunProfile = opts.onlyHubStale === true ? requireRerunProfile(opts.hubProfile) : null;
+	if (opts.onlyHubStaleWithUnknown && rerunProfile === null) warn("--only-hub-stale-with-unknown is ignored: it only applies to --only-hub-stale");
 	const forExecution = opts.dryRun !== true;
 	const cwd = opts.cwd ?? process.cwd();
 	const wantsLastGreen = opts.onFailExplain === true && opts.onFailExplainBase === void 0;
@@ -12217,8 +12217,8 @@ async function executeRun(targets, opts) {
 		meta("analysis-base", `${fixedBase.ref} (${fixedBase.sha.slice(0, 12)}, ${fixedBase.source})`);
 	}
 	if (forExecution) try {
-		if (opts.profile !== void 0) await resolveProfileEnv({
-			profile: opts.profile,
+		if (opts.hubProfile !== void 0) await resolveProfileEnv({
+			profile: opts.hubProfile,
 			project: resolveProjectOrThrow(opts.project, cwd),
 			cwd,
 			hubUrl: opts.hubUrl,
@@ -12234,7 +12234,7 @@ async function executeRun(targets, opts) {
 		if (err instanceof RunUsageError) throw err;
 		if (err instanceof ProjectNameError) throw new RunUsageError(err.message);
 		if (err instanceof HubConnectionError || err instanceof HubApiError) throw new RunUsageError(err.message);
-		throw new RunUsageError(`failed to load profile "${opts.profile}": ${errMessage(err)}`);
+		throw new RunUsageError(`failed to load profile "${opts.hubProfile}": ${errMessage(err)}`);
 	}
 	let hubCtx = null;
 	try {
@@ -12250,16 +12250,18 @@ async function executeRun(targets, opts) {
 	}
 	if (wantsLastGreen && hubCtx == null) throw new RunUsageError("--on-fail-explain needs a hub connection for the per-spec last-green baselines (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN), or an explicit --on-fail-explain-base <ref>");
 	const ledgerHub = wantsLastGreen ? hubCtx : null;
-	if (rerunProfile !== null && hubCtx == null) throw new RunUsageError("--only-stale requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)");
-	if (opts.onlyAuditedClean && hubCtx == null) throw new RunUsageError("--only-audited-clean requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)");
+	if (rerunProfile !== null && hubCtx == null) throw new RunUsageError("--only-hub-stale requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)");
+	if (opts.onlyHubAuditedClean && hubCtx == null) throw new RunUsageError("--only-hub-audited-clean requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)");
+	if (opts.reportToHub && hubCtx == null) throw new RunUsageError("--report-to-hub requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)");
+	if (opts.learnHubLivePrompt && hubCtx == null) throw new RunUsageError("--learn-hub-live-prompt requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)");
 	const [customPrompt, triageUserPrompt, ledgerEntries, rerunReport, fetchedDeployHead, auditedLedger] = await Promise.all([
 		forExecution ? fetchCustomPrompt(hubCtx) : null,
 		forExecution ? fetchTriageUserPrompt(hubCtx) : null,
-		forExecution && ledgerHub ? fetchLastGreenLedger(ledgerHub, opts.profile, cwd) : null,
+		forExecution && ledgerHub ? fetchLastGreenLedger(ledgerHub, opts.hubProfile, cwd) : null,
 		rerunProfile !== null && hubCtx ? fetchRerunReport(hubCtx, rerunProfile) : null,
-		forExecution && hubCtx && opts.profile && rerunProfile === null ? tryDeployHeadSha(hubCtx, opts.profile) : null,
-		opts.onlyAuditedClean && hubCtx ? fetchAuditedLedger(hubCtx) : null
-	]);
+		forExecution && hubCtx && opts.hubProfile && rerunProfile === null ? tryDeployHeadSha(hubCtx, opts.hubProfile) : null,
+		opts.onlyHubAuditedClean && hubCtx ? fetchAuditedLedger(hubCtx) : null
+	]).catch(asHubReadError);
 	const deployedSha = rerunReport?.deployHead.sha ?? fetchedDeployHead;
 	if (ledgerEntries) diffProvider = createDiffProvider({
 		resolveBase: createLastGreenResolver(ledgerEntries, cwd),
@@ -12286,7 +12288,7 @@ async function executeRun(targets, opts) {
 		const before = specs.length;
 		let unanswerable = 0;
 		if (rerunReport) {
-			const selection = selectSpecsNeedingRerun(specs, rerunReport, { includeUnknown: opts.onlyStaleWithUnknown === true });
+			const selection = selectSpecsNeedingRerun(specs, rerunReport, { includeUnknown: opts.onlyHubStaleWithUnknown === true });
 			specs = selection.selected;
 			unanswerable = selection.excludedUnanswerable;
 			meta("stale-base", `deploy ${rerunReport.deployHead.sha.slice(0, 12)} (profile ${rerunReport.profile})`);
@@ -12303,7 +12305,7 @@ async function executeRun(targets, opts) {
 			...opts.model ? { model: opts.model } : {}
 		})).specs;
 		meta("selected", `${specs.length} of ${before} spec${before === 1 ? "" : "s"}`);
-		if (specs.length === 0 && unanswerable > 0) hint(`${unanswerable} spec(s) were excluded because the hub could not tell whether they need a re-run; pass --only-stale-with-unknown to run them anyway`);
+		if (specs.length === 0 && unanswerable > 0) hint(`${unanswerable} spec(s) were excluded because the hub could not tell whether they need a re-run; pass --only-hub-stale-with-unknown to run them anyway`);
 	}
 	if (specs.length === 0) {
 		warn("no specs to run");
@@ -12328,7 +12330,7 @@ async function executeRun(targets, opts) {
 		const why = "it only applies to agent-browser 'mode: live' specs, and this run has none";
 		if (typeof opts.liveStepRetry === "number" && opts.liveStepRetry > 0) warn(`--live-step-retry is ignored: ${why}`);
 		if (opts.liveArtifactsDir) warn(`--live-artifacts-dir is ignored: ${why}`);
-		if (opts.learnLivePrompt) warn(`--learn-live-prompt is ignored: ${why}`);
+		if (opts.learnHubLivePrompt) warn(`--learn-live-prompt is ignored: ${why}`);
 	} else if (opts.liveArtifactsDir && liveSpecs.length > 1) warn("--out is ignored when running multiple live specs");
 	if (detSpecs.length === 0 && opts.replaySkipEvidence === true) warn("--no-evidence is ignored: it only applies to agent-browser 'mode: deterministic' specs, and this run has none");
 	blank();
@@ -12343,7 +12345,6 @@ async function executeRun(targets, opts) {
 		};
 	}
 	const det = await runDeterministicSpecs(detSpecs, opts, cwd, reportDir);
-	if (opts.reportToHub && hubCtx == null) warn("--push-report requires --hub-url/--hub-token (or CCQA_HUB_URL/CCQA_HUB_TOKEN); skipping push");
 	let hubRunId = null;
 	let hubSink;
 	if (hubCtx != null && opts.reportToHub) try {
@@ -12353,7 +12354,7 @@ async function executeRun(targets, opts) {
 		const opened = await hubCtx.hub.openRun({
 			project: hubCtx.project,
 			...branch ? { branch } : {},
-			...opts.profile ? { profile: opts.profile } : {},
+			...opts.hubProfile ? { profile: opts.hubProfile } : {},
 			...git.head ? { gitHead: git.head } : {},
 			...deployedSha ? { deployedSha } : {},
 			...ciRunId ? { ciRunId } : {},
@@ -12375,7 +12376,7 @@ async function executeRun(targets, opts) {
 			}
 		} };
 	} catch (err) {
-		warn(`hub: could not open incremental run (${errMessage(err)}); continuing with local report only`);
+		throw new RunUsageError(`--report-to-hub: could not open a run on the hub (${errMessage(err)})`);
 	}
 	const incrementalReport = createIncrementalReport(reportDir, buildReportEnvelope({
 		git,
@@ -12414,7 +12415,7 @@ async function executeRun(targets, opts) {
 		reportDir,
 		...typeof opts.liveStepRetry === "number" ? { retry: opts.liveStepRetry } : {},
 		concurrency: opts.concurrency ?? 1,
-		...opts.profile ? { profile: opts.profile } : {},
+		...opts.hubProfile ? { profile: opts.hubProfile } : {},
 		diffProvider,
 		hubContext: hubCtx,
 		customPrompt,
@@ -12476,7 +12477,7 @@ async function executeRun(targets, opts) {
 			}
 		}
 	}
-	if (opts.learnLivePrompt && liveSpecs.length > 0) {
+	if (opts.learnHubLivePrompt && liveSpecs.length > 0) {
 		blank();
 		await updateAgentPrompt({
 			kind: "live",
@@ -12789,7 +12790,7 @@ const PATCH_FILES_RAW_BUDGET = 20 * 1024 * 1024;
 /**
 * Add one row's file assets to `acc` as `{ reportDir-relative posix path →
 * base64 }`. Every kind of screenshot a row can carry has to be collected here,
-* or `--push-report` — the way CI publishes — silently ships a report whose
+* or `--report-to-hub` — the way CI publishes — silently ships a report whose
 * images 404 on the hub: a live row's per-step PNGs
 * (`liveRun.steps[].beforePng/afterPng`), a script-driven row's step evidence
 * (`evidence[].pngPath` / `beforePngPath`, written by agent-browser replays and
@@ -13018,14 +13019,14 @@ function installTeardownSignalHandlers(teardown) {
 }
 //#endregion
 //#region src/cli/run.ts
-const runCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("run").argument("[targets...]", "Specs to run, space-separated: each '<feature>/<spec>', '<feature>', or omit for all. Duplicates are de-duped.").description("Run specs, on any target. Agent-browser specs replay the recorded test.spec.ts under vitest (default), or, with spec.yaml `mode: live`, have Claude drive agent-browser live per step. External-target specs (playwright, runn) run through the target's configured `runCommand`. A structured report (report.json + evidence) is always written; use --report-to-hub to also stream it to a hub.").optionsGroup("Which specs to run:").option("--only-affected-by <ref>", "Only specs `ccqa select-specs` judges reached by the diff against <ref> (e.g. origin/main). In pull_request CI, pass $GITHUB_BASE_REF. Cannot be combined with an explicit spec id.").option("--only-stale", "Only specs whose last result no longer holds — each spec's own last run compared against the hub's deploy log. No git diff involved. Requires a hub connection and --profile.").option("--only-stale-with-unknown", "With --only-stale: also take specs whose re-run need the hub cannot answer ('unknown') and specs that never ran ('neverRun'). Off by default: an unanswerable question is reported, not guessed.").option("--only-audited-clean", "Only specs `ccqa audit` last found no drift in. A spec that has never been audited is not taken: this flag spends a run where a cheap audit already cleared the spec, and \"never looked\" is not that. Requires a hub connection.").option("--dry-run", "Print the specs this invocation would run, then exit 0 without executing anything and without writing a report. Works with every selection flag.").optionsGroup("How to run them:").option("--concurrency <n>", "Run up to N specs in parallel within each phase (deterministic / external-target / live), never across phases. Default 1 (sequential). Live specs each get an isolated agent-browser session; high values spawn many headed Chrome instances.", parseConcurrency$1, 1).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--live-step-retry <n>", "(live only) Retry each failed step up to N more times before recording failure. This retries a step, not the whole spec — see --on-fail-explain-rerun for that.", (raw) => {
+const runCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("run").argument("[targets...]", "Specs to run, space-separated: each '<feature>/<spec>', '<feature>', or omit for all. Duplicates are de-duped.").description("Run specs, on any target. Agent-browser specs replay the recorded test.spec.ts under vitest (default), or, with spec.yaml `mode: live`, have Claude drive agent-browser live per step. External-target specs (playwright, runn) run through the target's configured `runCommand`. A structured report (report.json + evidence) is always written; use --report-to-hub to also stream it to a hub.").optionsGroup("Which specs to run:").option("--only-affected-by <ref>", "Only specs `ccqa select-specs` judges reached by the diff against <ref> (e.g. origin/main). In pull_request CI, pass $GITHUB_BASE_REF. Cannot be combined with an explicit spec id.").option("--only-hub-stale", "Only specs the hub says are no longer covered by their last result — each spec's own last run compared against the hub's deploy log. No git diff involved. Requires a hub connection and --hub-profile.").option("--only-hub-stale-with-unknown", "With --only-hub-stale: also take specs whose re-run need the hub cannot answer ('unknown') and specs that never ran ('neverRun'). Off by default: an unanswerable question is reported, not guessed.").option("--only-hub-audited-clean", "Only specs the hub's drift ledger records as audited with no drift. A spec that has never been audited is not taken: this flag spends a run where a cheap audit already cleared the spec, and \"never looked\" is not that. Requires a hub connection.").option("--dry-run", "Print the specs this invocation would run, then exit 0 without executing anything and without writing a report. Works with every selection flag.").optionsGroup("How to run them:").option("--concurrency <n>", "Run up to N specs in parallel within each phase (deterministic / external-target / live), never across phases. Default 1 (sequential). Live specs each get an isolated agent-browser session; high values spawn many headed Chrome instances.", parseConcurrency$1, 1).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--live-step-retry <n>", "(live only) Retry each failed step up to N more times before recording failure. This retries a step, not the whole spec — see --on-fail-explain-rerun for that.", (raw) => {
 	const n = Number(raw);
 	if (!Number.isFinite(n) || n < 0 || Math.floor(n) !== n) throw new Error(`--live-step-retry must be a non-negative integer, got "${raw}"`);
 	return n;
 }, 0).option("--live-artifacts-dir <dir>", "(live only) Override the per-spec artifact directory. Default: <specDir>/runs/<runId>. Ignored when running multiple specs.").option("--replay-skip-evidence", `(deterministic replay only) Skip step-boundary evidence capture (PNG + meta JSON written to ${DEFAULT_REPORT_DIR}/${EVIDENCE_SUBDIR}/ by default).`).optionsGroup("What to do about failures:").option("--on-fail-explain", "Classify each failure against the source diff since the commit where that spec last passed (per-spec baselines from the hub). Off by default — no Claude calls without it.").option("--on-fail-explain-base <ref>", "With --on-fail-explain: diff against <ref> instead of each spec's last green. Use when there is no hub to hold the baselines.").optionsGroup("What to do with the results:").option("--report-dir <dir>", `Directory for the structured run results (report.json + evidence PNGs), which are always written. Default: ${DEFAULT_REPORT_DIR}/.`).option("--report-format <fmt>", "Additional output format alongside HTML: 'text' (default), 'json' (writes report.json), 'github' (GitHub Actions annotations on stdout).", (raw) => {
 	if (REPORT_FORMATS.includes(raw)) return raw;
 	throw new Error(`--report-format must be one of ${REPORT_FORMATS.join(" | ")}`);
-}, "text").option("--report-to-hub", "Incrementally push the run report to the hub as the run progresses (open → patch per spec → finalize). Requires --hub-url/--hub-token (or CCQA_HUB_URL/CCQA_HUB_TOKEN). Without it, hub credentials are used only to fetch variables/sessions/prompts, not to push.").optionsGroup("Learning:").option("--learn-live-prompt", "(live only) After the run finishes, ask Claude to refresh the \"live.agent\" prompt on the hub from a summary of the run. Requires a hub connection.").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--project <name>", "Project name for the hub. Defaults to the current directory's name.")))).action(async (targets, opts) => {
+}, "text").option("--report-to-hub", "Incrementally push the run report to the hub as the run progresses (open → patch per spec → finalize). Requires --hub-url/--hub-token (or CCQA_HUB_URL/CCQA_HUB_TOKEN). Without it, hub credentials are used only to fetch variables/sessions/prompts, not to push.").optionsGroup("Learning:").option("--learn-hub-live-prompt", "(live only) After the run finishes, ask Claude to refresh the \"live.agent\" prompt on the hub from a summary of the run. Requires a hub connection.").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--project <name>", "Project name for the hub. Defaults to the current directory's name.")))).action(async (targets, opts) => {
 	await runCliAction(targets, opts);
 });
 /** Parse --concurrency: a positive integer. Rejects 0, negatives, non-integers. */
@@ -13043,8 +13044,8 @@ function headerTarget(targets, opts) {
 	if (targets.length > 1) return `${targets.length} targets`;
 	const filters = [
 		opts.onlyAffectedBy ? "affected" : null,
-		opts.onlyStale ? "stale" : null,
-		opts.onlyAuditedClean ? "audited clean" : null
+		opts.onlyHubStale ? "stale" : null,
+		opts.onlyHubAuditedClean ? "audited clean" : null
 	].filter((s) => s !== null);
 	return filters.length === 0 ? "(all specs)" : `(${filters.join(" + ")})`;
 }
@@ -15142,21 +15143,21 @@ async function runGenerateLocked(featureName, specName, opts, cwd) {
 	hint(`run 'ccqa run ${featureName}/${specName}' to execute the test`);
 }
 /**
-* `ccqa generate --update-agent-prompt`: refresh the target's learned
+* `ccqa generate --learn-hub-codegen-prompt`: refresh the target's learned
 * `<target>.agent` playbook from this generation. Only targets that declare a
 * `guidanceKind` (the LLM-generating ones: playwright, runn) have such a
 * prompt — agent-browser's codegen is mechanical, so point at `ccqa record
-* --update-agent-prompt` for its tracer instead.
+* --learn-hub-trace-prompt` for its tracer instead.
 */
 async function runGenerateAgentPromptUpdate(target, featureName, specName, result, opts, cwd) {
 	if (target.guidanceKind === void 0) {
-		warn(`--update-agent-prompt has no effect on the "${target.id}" target — it has no learned generation prompt (only LLM-generating targets like playwright/runn do)`);
+		warn(`--learn-hub-codegen-prompt has no effect on the "${target.id}" target — it has no learned generation prompt (only LLM-generating targets like playwright/runn do)`);
 		return;
 	}
 	blank();
 	await updateAgentPrompt({
 		kind: target.guidanceKind,
-		flag: "--learn-codegen-prompt",
+		flag: "--learn-hub-codegen-prompt",
 		runSummary: buildGenerateRunSummary(target.id, featureName, specName, result, cwd),
 		hubContext: opts.hubContext ?? null,
 		...opts.model ? { model: opts.model } : {},
@@ -15182,7 +15183,7 @@ async function confirmOverwrite(path) {
 		rl.close();
 	}
 }
-const generateCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("generate").argument("<feature/spec>", "Spec id in '<feature>/<spec>' form (resolves to .ccqa/features/<feature>/test-cases/<spec>/)").description("Generate test code from a spec via its target plugin. Recording-backed targets compile the existing ir.json (run `ccqa record` first); spec-input targets generate directly from the spec.").optionsGroup("How to generate:").option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--target <id>", "Generate through this target instead of the spec's own — e.g. emit a Playwright spec from an agent-browser recording. The spec's `target:` stays the default for `ccqa run`.").option("--auto-fix <mode>", "Auto-fix behaviour during script generation: 'interactive' (default, prompt y/N; declines on non-TTY), 'auto' (apply without prompt, for CI), 'skip' (agent-browser: apply only high-confidence fixes; external targets like playwright/runn: no fix pass at all).", parseAutoFixFlag, "interactive").option("--auto-fix-max-retries <n>", "Maximum number of auto-fix retries", "3").option("--no-session-pin", "Don't pin AGENT_BROWSER_SESSION / capture page snapshots after a failure (debug toggle)").optionsGroup("What to do with the result:").option("--overwrite", "Replace previously generated test code without warning").optionsGroup("Learning:").option("--learn-codegen-prompt", "After generation, ask Claude to refresh the target's \"<target>.agent\" learning prompt on the hub from a summary of the run. LLM-generating targets (playwright, runn) only; requires a hub connection.").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--project <name>", "Project name for the hub. Defaults to the current directory's name.")))).action(withUsageErrors(async (specPath, opts) => {
+const generateCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("generate").argument("<feature/spec>", "Spec id in '<feature>/<spec>' form (resolves to .ccqa/features/<feature>/test-cases/<spec>/)").description("Generate test code from a spec via its target plugin. Recording-backed targets compile the existing ir.json (run `ccqa record` first); spec-input targets generate directly from the spec.").optionsGroup("How to generate:").option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--target <id>", "Generate through this target instead of the spec's own — e.g. emit a Playwright spec from an agent-browser recording. The spec's `target:` stays the default for `ccqa run`.").option("--auto-fix <mode>", "Auto-fix behaviour during script generation: 'interactive' (default, prompt y/N; declines on non-TTY), 'auto' (apply without prompt, for CI), 'skip' (agent-browser: apply only high-confidence fixes; external targets like playwright/runn: no fix pass at all).", parseAutoFixFlag, "interactive").option("--auto-fix-max-retries <n>", "Maximum number of auto-fix retries", "3").option("--no-session-pin", "Don't pin AGENT_BROWSER_SESSION / capture page snapshots after a failure (debug toggle)").optionsGroup("What to do with the result:").option("--overwrite", "Replace previously generated test code without warning").optionsGroup("Learning:").option("--learn-hub-codegen-prompt", "After generation, ask Claude to refresh the target's \"<target>.agent\" learning prompt on the hub from a summary of the run. LLM-generating targets (playwright, runn) only; requires a hub connection.").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--project <name>", "Project name for the hub. Defaults to the current directory's name.")))).action(withUsageErrors(async (specPath, opts) => {
 	const { featureName, specName } = parseSpecPath(specPath);
 	const language = opts.language ?? "auto";
 	const cwd = resolveCwd(opts.cwd);
@@ -15191,9 +15192,9 @@ const generateCommand = addHubOptions(addProfileOption(addLanguageOption(new Com
 		hubToken: opts.hubToken,
 		hubHeader: opts.hubHeader
 	});
-	const project = opts.profile !== void 0 || hubClient !== null ? resolveProject(opts) : void 0;
-	if (opts.profile !== void 0) await applyProfileFromOption({
-		profile: opts.profile,
+	const project = opts.hubProfile !== void 0 || hubClient !== null ? resolveProject(opts) : void 0;
+	if (opts.hubProfile !== void 0) await applyProfileFromOption({
+		profile: opts.hubProfile,
 		project,
 		cwd,
 		hubUrl: opts.hubUrl,
@@ -15205,6 +15206,10 @@ const generateCommand = addHubOptions(addProfileOption(addLanguageOption(new Com
 		project: "",
 		cwd
 	});
+	if (opts.learnHubCodegenPrompt && hubClient === null) {
+		error("--learn-hub-codegen-prompt requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)");
+		process.exit(2);
+	}
 	const hubContext = hubClient && project ? {
 		hub: hubClient,
 		project
@@ -15220,7 +15225,7 @@ const generateCommand = addHubOptions(addProfileOption(addLanguageOption(new Com
 			targetOverride: opts.target,
 			cwd,
 			hubContext,
-			updateAgentPrompt: opts.learnCodegenPrompt ?? false
+			updateAgentPrompt: opts.learnHubCodegenPrompt ?? false
 		});
 	} catch (e) {
 		if (e instanceof SpecLockedError) {
@@ -15259,7 +15264,7 @@ const VALIDATION_MODES = ["lenient", "strict"];
 const recordCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("record").argument("<feature/spec>", "Spec id in '<feature>/<spec>' form (resolves to .ccqa/features/<feature>/test-cases/<spec>/)").description("Record a test from a spec: run agent-browser to collect actions (trace), then compile them into runnable code via the spec's target (generate) — a vitest test.spec.ts for agent-browser, a @playwright/test spec for the playwright target. Recording-backed targets only; spec-input targets like runn have no trace step (use `ccqa generate`), and agent-browser live specs need no recording.").optionsGroup("How to record:").option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--trace-validation <mode>", "What to do with actions that fail post-trace validation: 'lenient' (default) tags them; 'strict' drops them.", (raw) => {
 	if (VALIDATION_MODES.includes(raw)) return raw;
 	throw new Error(`--trace-validation must be one of ${VALIDATION_MODES.join(" | ")}`);
-}, "lenient").option("--auto-fix <mode>", "Auto-fix behaviour during script generation: 'interactive' (default, prompt y/N; declines on non-TTY), 'auto' (apply without prompt, for CI), 'skip' (agent-browser: apply only high-confidence fixes; external targets like playwright/runn: no fix pass at all).", parseAutoFixFlag, "interactive").option("--auto-fix-max-retries <n>", "Maximum number of auto-fix retries", "3").option("--trace-only", "Stop after the trace step; do not generate test code").option("--no-session-pin", "Don't pin AGENT_BROWSER_SESSION / capture page snapshots after a failure (debug toggle)").optionsGroup("What to do with the result:").option("--overwrite", "Replace an existing test.spec.ts without warning").optionsGroup("Learning:").option("--learn-trace-prompt", "After the trace finishes, ask Claude to refresh the \"record.agent\" prompt on the hub from a summary of the run. Requires a hub connection.").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--project <name>", "Project name for the hub. Defaults to the current directory's name.")))).action(withUsageErrors(async (specPath, opts) => {
+}, "lenient").option("--auto-fix <mode>", "Auto-fix behaviour during script generation: 'interactive' (default, prompt y/N; declines on non-TTY), 'auto' (apply without prompt, for CI), 'skip' (agent-browser: apply only high-confidence fixes; external targets like playwright/runn: no fix pass at all).", parseAutoFixFlag, "interactive").option("--auto-fix-max-retries <n>", "Maximum number of auto-fix retries", "3").option("--trace-only", "Stop after the trace step; do not generate test code").option("--no-session-pin", "Don't pin AGENT_BROWSER_SESSION / capture page snapshots after a failure (debug toggle)").optionsGroup("What to do with the result:").option("--overwrite", "Replace an existing test.spec.ts without warning").optionsGroup("Learning:").option("--learn-hub-trace-prompt", "After the trace finishes, ask Claude to refresh the \"record.agent\" prompt on the hub from a summary of the run. Requires a hub connection.").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--project <name>", "Project name for the hub. Defaults to the current directory's name.")))).action(withUsageErrors(async (specPath, opts) => {
 	await withCostTally(async () => {
 		try {
 			await runRecord(specPath, opts);
@@ -15279,9 +15284,9 @@ async function runRecord(specPath, opts) {
 		error(`target "${target.id}" does not use a browser recording — run 'ccqa generate ${featureName}/${specName}' instead`);
 		process.exit(2);
 	}
-	const project = opts.profile !== void 0 ? resolveProject(opts) : void 0;
-	if (opts.profile !== void 0) await applyProfileFromOption({
-		profile: opts.profile,
+	const project = opts.hubProfile !== void 0 ? resolveProject(opts) : void 0;
+	if (opts.hubProfile !== void 0) await applyProfileFromOption({
+		profile: opts.hubProfile,
 		project,
 		cwd: cwdForProfile,
 		hubUrl: opts.hubUrl,
@@ -15303,6 +15308,10 @@ async function runRecord(specPath, opts) {
 		hub: hubClientForTrace,
 		project: hubProject
 	} : null;
+	if (opts.learnHubTracePrompt && hubContext === null) {
+		error("--learn-hub-trace-prompt requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)");
+		process.exit(2);
+	}
 	const releaseLock = await acquireSpecLock(featureName, specName, "record", cwdForProfile).catch((e) => {
 		if (e instanceof SpecLockedError) {
 			error(e.message);
@@ -15330,11 +15339,11 @@ async function runRecord(specPath, opts) {
 	} finally {
 		await releaseLock();
 	}
-	if (opts.learnTracePrompt && traceResult !== null) {
+	if (opts.learnHubTracePrompt && traceResult !== null) {
 		blank();
 		await updateAgentPrompt({
 			kind: "record",
-			flag: "--learn-trace-prompt",
+			flag: "--learn-hub-trace-prompt",
 			runSummary: buildRecordRunSummary(featureName, specName, traceResult),
 			hubContext,
 			...opts.model ? { model: opts.model } : {},
@@ -15615,7 +15624,7 @@ function specStatus(result, threshold) {
 	return "passed";
 }
 /**
-* Adapts `ccqa drift` results into the shared RunReportData shape so they can
+* Adapts `ccqa audit` results into the shared RunReportData shape so they can
 * be pushed to the hub (`ccqa audit --report-to-hub`) and rendered by the same report
 * UI as `ccqa run`/`ccqa live`. Browser-execution fields (testCounts,
 * evidence, liveRun, ...) don't apply to a drift audit and are always null —
@@ -15664,7 +15673,7 @@ function driftResultsToReport(results, meta) {
 //#endregion
 //#region src/cli/audit.ts
 const DEFAULT_CONCURRENCY = 3;
-const auditCommand = addLanguageOption(new Command("audit").argument("[feature/spec]", "Optional spec id. If omitted, every spec under .ccqa/features/ is checked.").description("Read each spec against the code it describes and report where the two have drifted. Static: no browser is run, so this is the cheap check to put in front of `ccqa run`.").optionsGroup("Which specs to audit:").option("--only-affected-by <ref>", "Only specs `ccqa select-specs` judges reached by the diff against <ref> (e.g. origin/main). In pull_request CI, pass $GITHUB_BASE_REF. Costs one model call; specs it cannot decide are audited rather than skipped.").optionsGroup("How to run it:").option("--concurrency <n>", `Parallel spec checks (default: ${DEFAULT_CONCURRENCY})`).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").optionsGroup("What to do with the results:").option("--report-format <fmt>", "Output format: text | json | github", "text").option("--report-to-hub", "Push the result to a ccqa hub as a run (kind: drift), which is what updates the drift ledger `ccqa run --only-audited-clean` reads.").option("--exit-on <level>", "Exit non-zero on this severity or higher: warn | error", "error").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory used as both the .ccqa root and the codebase Claude reads. Useful for monorepos. Defaults to process.cwd().").option("--project <name>", "Logical project name for the pushed run. Defaults to the current directory's name.").option(...hubUrlOption).option(...hubTokenOption).option(...hubHeaderOption)).action(withUsageErrors(async (specPath, opts) => {
+const auditCommand = addLanguageOption(new Command("audit").argument("[feature/spec]", "Optional spec id. If omitted, every spec under .ccqa/features/ is checked.").description("Read each spec against the code it describes and report where the two have drifted. Static: no browser is run, so this is the cheap check to put in front of `ccqa run`.").optionsGroup("Which specs to audit:").option("--only-affected-by <ref>", "Only specs `ccqa select-specs` judges reached by the diff against <ref> (e.g. origin/main). In pull_request CI, pass $GITHUB_BASE_REF. Costs one model call; specs it cannot decide are audited rather than skipped.").optionsGroup("How to run it:").option("--concurrency <n>", `Parallel spec checks (default: ${DEFAULT_CONCURRENCY})`).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").optionsGroup("What to do with the results:").option("--report-format <fmt>", "Output format: text | json | github", "text").option("--report-to-hub", "Push the result to a ccqa hub as a run (kind: drift), which is what updates the drift ledger `ccqa run --only-hub-audited-clean` reads.").option("--exit-on <level>", "Exit non-zero on this severity or higher: warn | error", "error").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory used as both the .ccqa root and the codebase Claude reads. Useful for monorepos. Defaults to process.cwd().").option("--project <name>", "Logical project name for the pushed run. Defaults to the current directory's name.").option(...hubUrlOption).option(...hubTokenOption).option(...hubHeaderOption)).action(withUsageErrors(async (specPath, opts) => {
 	await withCostTally(() => runAudit(specPath, opts));
 }));
 async function runAudit(specPath, opts) {
@@ -15723,9 +15732,9 @@ async function runAudit(specPath, opts) {
 }
 /**
 * Push a finished drift audit to a ccqa hub as a `kind: "drift"` run, so it
-* shows up alongside `ccqa run` runs in the hub UI. Best-effort: a missing
-* hub connection warns and returns rather than failing the command (`--report-to-hub`
-* never changes drift's own exit code).
+* shows up alongside `ccqa run` runs in the hub UI. A missing hub connection
+* is a usage error, not a silent skip — a CI job that asked to publish and
+* did not must say so.
 *
 * `resolveHub` is injectable so tests can supply a fake `HubClient` without
 * a real hub connection; it defaults to the real flag/env resolution.
@@ -15734,8 +15743,8 @@ async function pushDriftResults(args, resolveHub = resolveHubClient) {
 	const { results, threshold, cwd, opts, format, baseRef } = args;
 	const hub = resolveHub(opts);
 	if (!hub) {
-		warn("--report-to-hub requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN) — skipping push");
-		return;
+		error("--report-to-hub requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN)");
+		process.exit(2);
 	}
 	try {
 		const project = resolveProject({
@@ -15812,7 +15821,7 @@ function parseFormat$1(raw) {
 function parseSeverity(raw) {
 	const v = raw ?? "error";
 	if (v === "warn" || v === "error") return v;
-	error(`invalid --severity: ${v} (expected warn|error)`);
+	error(`invalid --exit-on: ${v} (expected warn|error)`);
 	process.exit(2);
 }
 function parseConcurrency(raw) {
@@ -16282,7 +16291,7 @@ function countSpecs(results) {
 * or `red` (the last outcome), which are orthogonal axes.
 *
 * Best-effort — a ledger failure must not fail the push; the ledger is an
-* accelerator for `--failure-analysis=last-green` and re-run selection, not
+* accelerator for `--on-fail-explain` baselines and re-run selection, not
 * part of the run record. Runs without a branch or gitHead can't be placed in
 * the ledger and are skipped.
 *
@@ -16926,7 +16935,7 @@ function createGetLastGreenHandler(storage) {
 /**
 * GET /api/v1/projects/:project/drift
 *
-* Every spec's last `ccqa drift --push` audit, keyed by "feature/spec". No
+* Every spec's last `ccqa audit --report-to-hub` result, keyed by "feature/spec". No
 * `?profile=` — drift asks whether a spec still describes the code, which
 * has nothing to do with which environment is running it, unlike the
 * `/rerun` and `/last-green` endpoints. Merged across every branch (newest
@@ -18028,7 +18037,7 @@ const HTML_BODY = `
           <div style="font-weight:600" data-i18n="session.help.title">How to get this JSON</div>
           <ol class="help-steps">
             <li><span class="step-n">1</span><div class="step-b"><span data-i18n="session.help.step1">Run this in your terminal and log in by hand when the browser opens:</span>
-              <div class="cmd"><code id="session-help-cmd">ccqa session bootstrap &lt;name&gt;</code><button type="button" class="copy" id="session-help-copy"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="9" y="9" width="11" height="11" rx="2"/><path d="M5 15V5a2 2 0 0 1 2-2h10"/></svg><span data-i18n="common.copy">Copy</span></button></div>
+              <div class="cmd"><code id="session-help-cmd">ccqa hub session capture &lt;name&gt;</code><button type="button" class="copy" id="session-help-copy"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="9" y="9" width="11" height="11" rx="2"/><path d="M5 15V5a2 2 0 0 1 2-2h10"/></svg><span data-i18n="common.copy">Copy</span></button></div>
             </div></li>
             <li><span class="step-n">2</span><div class="step-b"><span data-i18n="session.help.step2">Open the saved file and paste its contents below:</span>
               <div style="margin-top:5px"><span class="path">.ccqa/sessions/&lt;profile&gt;/&lt;name&gt;.json</span></div>
@@ -20154,7 +20163,7 @@ const CLIENT_JS = `
     }
 
     // A drift-kind row's diagnosis lives in analysis regardless of status
-    // (an UNKNOWN-labelled finding below the --severity threshold still
+    // (an UNKNOWN-labelled finding below the --exit-on threshold still
     // "passes" but has something to show); a normal run only ever classifies
     // a failed spec.
     var hasAnalysis = isDrift ? !!r.analysis : r.status === "failed" && r.analysis;
@@ -21147,7 +21156,7 @@ const CLIENT_JS = `
   //
   // "unknown" keeps its own state rather than folding into the last result:
   // it means the hub cannot say whether that result still holds, and
-  // --changed=last-run does not re-run it without --include-unknown. Showing
+  // --only-hub-stale does not re-run it without --only-hub-stale-with-unknown. Showing
   // it as passed or failed would claim a confidence nothing supports.
   function perspRunState(rr) {
     if (!rr) return null;

package/dist/hub-client/index.d.mts

@@ -151,7 +151,7 @@ type PutActualCauseRequest = z.infer<typeof PutActualCauseRequestSchema>;
  * updates the ledger whenever a `kind: "run"` run reaches a terminal state:
  * every spec that passed gets its entry advanced to that run's `gitHead`
  * (newest `at` wins, so out-of-order finalizes can't move a baseline
- * backwards). `ccqa run --failure-analysis=last-green` reads it to diff each
+ * backwards). `ccqa run --on-fail-explain` reads it to diff each
  * failing spec against the commit where that spec was last green.
  */
 declare const LastGreenEntrySchema: z.ZodObject<{
@@ -297,7 +297,7 @@ type DriftLedgerResponse = z.infer<typeof DriftLedgerResponseSchema>;
  *
  * Two kinds share one namespace:
  *  - "guidance": the record/live prompt bundle — `.user.md` (human-maintained)
- *    and `.agent.md` (auto-rewritten by `ccqa run --update-agent-prompt`) —
+ *    and `.agent.md` (auto-rewritten by `ccqa run --learn-hub-live-prompt`) —
  *    plus `triage.user`, the human-maintained guidance injected into the
  *    failure-analysis (triage) prompt.
  *  - "custom-prompt": `analysis-custom-prompt` — Claude-written calibration guidance
@@ -820,7 +820,7 @@ interface HubClient {
   }): Promise<Record<string, LastGreenEntry>>;
   /**
    * Per spec of one project/profile: is its last result still trustworthy?
-   * Answers `ccqa run --changed=last-run`. 404 when the project has no
+   * Answers `ccqa run --only-hub-stale`. 404 when the project has no
    * perspectives document — there is then no spec registered to compare
    * against a deploy, which the caller must report rather than read as
    * "nothing to run".

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {