@12ui/design 0.2.56 → 0.2.58

package/dist/cli-help/index.d.ts

@@ -9,13 +9,13 @@ export declare const CLI_HELP_CONTEXTS: {
         }];
     };
     readonly spend: {
-        readonly summary: "Report what this account actually settled: per run, per day, and who funded it.";
+        readonly summary: "Report settled account spend, or exact durable identities from an improve kit or redesign run.";
         readonly sections: readonly [{
             readonly heading: "Reads";
             readonly items: readonly [string, "Wallet balance and lifetime funding, plus the current daily quota window.", string];
         }, {
             readonly heading: "Notes";
-            readonly items: readonly [string, "Totals cover the whole window even when --limit shortens the run list."];
+            readonly items: readonly [string, "Totals cover the whole window even when --limit shortens the run list.", string];
         }];
     };
     readonly mcp: {
@@ -70,7 +70,7 @@ export declare const CLI_HELP_CONTEXTS: {
         readonly summary: "Search the Design Corpus and download validated visual references.";
         readonly sections: readonly [{
             readonly heading: "Behavior";
-            readonly items: readonly ["Runs in the foreground and writes an attempt record before the metered search, then a manifest, evidence, receipts, and downloaded references.", "Defaults to four references in balanced mode; --count accepts 1–48.", "--reference-image conditions retrieval on an existing PNG, JPEG, or WebP."];
+            readonly items: readonly ["Runs in the foreground and writes an attempt record before the metered search, then a manifest, evidence, receipts, and downloaded references.", "Defaults to four references in balanced mode; --count accepts 1–48 in every mode.", "--reference-image conditions retrieval on an existing PNG, JPEG, or WebP."];
         }, {
             readonly heading: "Modes";
             readonly items: readonly ["direct stays closest to the literal query.", "balanced is the default relevance, quality, and variety trade-off.", "adventurer keeps a relevant head while exploring less expected directions."];
@@ -90,7 +90,7 @@ export declare const CLI_HELP_CONTEXTS: {
             readonly items: readonly ["Creates a resumable temporary run directory, prints it first, retrieves a balanced corpus set, and claims one hosted /api/v1/create run.", "--candidates accepts 2–16 and defaults to four; prefer at least four distinct directions.", "Every service dispatch request stays in the foreground. The command returns after no slot remains pending; generation stays server-side.", "Run `12ui next <run-dir> --wait` to poll, repair only recorded slots that never started, and download real PNGs into <run-dir>/candidates/.", "Defaults to landscape. Authentication is 12ui-only; no Codex session or caller-side image-provider key is read."];
         }, {
             readonly heading: "Redesign modes";
-            readonly items: readonly ["Without --reference, creates a new interface and pairs one corpus reference with each candidate.", "--reference accepts a local path or HTTP(S) URL, conditions corpus retrieval, and sends those original bytes to every candidate.", "A reference retains style by default while excluding layout, content, and assets. --retain accepts comma-separated values; layout is the explicit structure-preserving opt-in.", "--redesign-source remains an alias for local redesign workflows. --mode reskin is the layout-retain shorthand."];
+            readonly items: readonly ["Without --reference, creates a new interface and pairs one corpus reference with each candidate.", "--reference accepts a local path or HTTP(S) URL, conditions corpus retrieval, and sends those original bytes to every candidate.", "A reference retains style by default while excluding layout, content, and assets. --retain accepts comma-separated values; layout is the explicit structure-preserving opt-in.", "--retain-source says what the reference IS. inspiration (the default) is a design you like, so an exclusion is a prohibition: do not reuse its words or its logo. subject is your own page, so the same exclusion is a licence: its words may be rewritten, its brand may be replaced. `12ui improve` sends subject. Against a subject, at least one of layout, copy, brand, and style must be left free to change: keeping all four asks for the page back unchanged and is refused.", "--redesign-source remains an alias for local redesign workflows. --mode reskin is the layout-retain shorthand."];
         }, {
             readonly heading: "Next";
             readonly items: readonly ["Run `12ui next <run-dir>` to follow generation. Convert one chosen image, or pass it to `12ui branch execute --start`."];
@@ -141,10 +141,13 @@ export declare const CLI_HELP_CONTEXTS: {
         }];
     };
     readonly improve: {
-        readonly summary: "Improve one live interface or screenshot and produce a replayable implementation kit.";
+        readonly summary: "Improve one live interface, site, or screenshot and produce a replayable implementation kit.";
         readonly sections: readonly [{
             readonly heading: "Behavior";
-            readonly items: readonly ["Five stages run in order: local capture, hosted draft candidates retaining layout and content, explicit pick, fused LayerDoc and responsive HTML conversion, then a local implementation plan.", "The pick is explicit and has no default. With no --pick and no pick already recorded, the run stops after the draw, prints where the candidates are and the exact command that continues (--from pick --pick <slot>), and buys no conversion: converting a candidate nobody chose spends money on a guess that cannot be cancelled. --target supplies the design instead and skips draft and pick.", "URL input uses one Playwright context for repeated --bootstrap actions, screenshot capture, and selector-verified DOM extraction. Image input normalizes the source locally.", string, "The kit keeps every candidate, winner, target, plan, assets, and improve.json replay record. Repeating a settled stage reuses it; --from pick --pick <slot> invalidates only the old target and plan.", "--responsive-quality selects standard or pro responsive export. If that export fails or reaches the improve deadline after LayerDoc materialization, improve derives fixed HTML free and continues to plan with a warning.", "--convert-stall-seconds bounds every hosted wait the convert stage makes, including the free fixed-layout derivation (default: twice the model's typical wall, 480s standard and pro, 300s fast; refused below one typical wall). If a wait ends with no LayerDoc on disk there is nothing to derive, so improve records the abandoned conversion and dispatches exactly ONE fresh one; a second stall writes plan/STALL.md and exits non-zero. The retry budget belongs to the kit: a resume re-attaches to the newest conversion already bought, a kit that has spent its retry refuses to dispatch again, and a pro conversion is never retried automatically because no measured wall justifies it. Stopping the wait does not stop the conversion: there is no cancel, so an abandoned run keeps billing.", "--fresh re-buys ONE conversion of the same settled winner under a new idempotency key: it records the abandoned conversion identity and reuses capture, draft and pick untouched. --redraw is the one that buys new candidates — it discards draft, pick, convert and plan, moves the old draw to candidates.previous, records any conversion it drops, and runs the draft stage again; it is also the one path allowed to change --direction, --candidates or --retain against the record. A temporarily unavailable stage retries once after 30 seconds.", "--target brings your own design image or LayerDoc, skips draft and pick, converts an image when needed, and aligns the plan to the captured URL DOM."];
+            readonly items: readonly ["Page scope runs five stages in order: local capture, hosted draft candidates, explicit pick, fused LayerDoc and responsive HTML conversion, then a local implementation plan.", "The pick is explicit and has no default. With no --pick and no pick already recorded, the run stops after the draw, prints where the candidates are and the exact command that continues (--from pick --pick <slot>), and buys no conversion: converting a candidate nobody chose spends money on a guess that cannot be cancelled. --target supplies the design instead and skips draft and pick.", "--retain says what to hold from the live page, in the four-facet vocabulary: layout, content, assets, style. It defaults to assets,content — keep the product's brand and words, rework its layout and visual system. Add layout to hold the geometry, add style to work inside the existing visual language, drop assets to let the brand be replaced. The /improve page exposes the same four as Keep layout, Keep copy, Keep brand, and Keep style. At least one of the four must be left free to change: keeping all four asks for the page back unchanged and is refused before anything is bought.", "Whatever is retained, no setting licenses inventing a product fact: with content held the page says the same things; with content freed the words may be rewritten but every claim, number, offer, and control must still be present and true.", "URL input uses one Playwright context for repeated --bootstrap actions, screenshot capture, and selector-verified DOM extraction. Image input normalizes the source locally.", string, "The kit keeps every candidate, winner, target, plan, assets, and improve.json replay record. Repeating a settled stage reuses it; --from pick --pick <slot> invalidates only the old target and plan.", "--responsive-quality selects standard or pro responsive export. If that export fails, is absent, or reaches the improve deadline after LayerDoc materialization, improve continues to plan with a warning and derives fixed HTML free when possible.", "--convert-stall-seconds is a no-progress bound for every hosted convert wait, including the free fixed-layout derivation (default: 960s standard and pro, 300s fast; refused below one typical wall). A newly polled live stage or active lane resets it, so healthy tall work stays attached to its original purchase and no second conversion is dispatched. A true no-progress stall with no LayerDoc writes plan/STALL.md and exits non-zero with free re-attachment commands. With a LayerDoc, improve derives fixed HTML for the plan and plan/STALL.md gives the free resume command that later collects responsive winner.html without changing that plan basis. Stopping the wait does not stop the conversion: there is no cancel, so an open run keeps billing.", "--fresh re-buys ONE conversion of the same settled winner under a new idempotency key: it records the abandoned conversion identity and reuses capture, draft and pick untouched. --redraw is the one that buys new candidates — it discards draft, pick, convert and plan, moves the old draw to candidates.previous, records any conversion it drops, and runs the draft stage again; it is also the one path allowed to change --direction, --candidates or --retain against the record. A temporarily unavailable stage retries once after 30 seconds.", "--target brings your own design image or LayerDoc, skips draft and pick, converts an image when needed, and aligns the plan to the captured URL DOM."];
+        }, {
+            readonly heading: "Whole-site polish";
+            readonly items: readonly ["--scope site captures 2–8 same-origin pages including the root, then runs capture, draft, pick, branch, convert, plan, and site. The accepted root is the visual system; each current non-root page is edited against it.", "Root and page conversions share one resilience policy: an unavailable responsive export never discards its LayerDoc or blocks that page plan, and the site kit records fixed-layout or LayerDoc-only delivery honestly.", "--pages caps free one-hop discovery including the root (default 5); repeat --page to supply explicit same-origin pages instead. --page-concurrency defaults to 3, and --reference-order defaults to current-first.", "The site roll-up writes site-plan/tokens.css, shared-shell.md, pages.md, and APPLY.md. It deduplicates tokens and shared shell changes so the implementation plan applies them once before per-page residue.", "Apply APPLY.md, then run `12ui improve <url> --scope site --out-dir <kit> --recheck`. It captures the root and every page once in one browser context, writes numbered recheck evidence, and replans only against kept targets without replaying settled stages. The command never applies code."];
         }, {
             readonly heading: "Planning";
             readonly items: readonly ["URL plans require at least 60% plausible DOM-side coverage; a blocked gate writes GATE.md while target HTML and LayerDoc remain authoritative sidecars.", "Image plans are target-only by default. --plan-source-convert buys one source LayerDoc conversion for an unanchored LayerDoc comparison.", "--repo adds evidence-ranked src/ TSX, JSX, and CSS file hints to a URL plan. The command never applies code.", "--dry-run prints exact catalog price ceilings for every stage and makes no network request."];

package/dist/cli-help/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli-help/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAkB,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAKK,CAAC;AAIpC,eAAO,MAAM,aAAa,GAAI,SAAS,SAAS,MAAM,EAAE,KAAG,SAAS,MAAM,EAUzE,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GACzB,SAAS,SAAS,MAAM,EAAE,KACzB,cAAc,GAAG,SAenB,CAAC;AAEF,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli-help/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAkB,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAKK,CAAC;AAIpC,eAAO,MAAM,aAAa,GAAI,SAAS,SAAS,MAAM,EAAE,KAAG,SAAS,MAAM,EAUzE,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GACzB,SAAS,SAAS,MAAM,EAAE,KACzB,cAAc,GAAG,SAenB,CAAC;AAEF,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/cli-help/meta.d.ts

@@ -7,13 +7,13 @@ export declare const META_HELP: {
         }];
     };
     readonly spend: {
-        readonly summary: "Report what this account actually settled: per run, per day, and who funded it.";
+        readonly summary: "Report settled account spend, or exact durable identities from an improve kit or redesign run.";
         readonly sections: readonly [{
             readonly heading: "Reads";
             readonly items: readonly [string, "Wallet balance and lifetime funding, plus the current daily quota window.", string];
         }, {
             readonly heading: "Notes";
-            readonly items: readonly [string, "Totals cover the whole window even when --limit shortens the run list."];
+            readonly items: readonly [string, "Totals cover the whole window even when --limit shortens the run list.", string];
         }];
     };
     readonly mcp: {

package/dist/cli-help/meta.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"meta.d.ts","sourceRoot":"","sources":["../../src/cli-help/meta.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgDa,CAAC"}
+{"version":3,"file":"meta.d.ts","sourceRoot":"","sources":["../../src/cli-help/meta.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmDa,CAAC"}

package/dist/cli-help/meta.js

@@ -10,7 +10,7 @@ export const META_HELP = {
             }],
     },
     spend: {
-        summary: 'Report what this account actually settled: per run, per day, and who funded it.',
+        summary: 'Report settled account spend, or exact durable identities from an improve kit or redesign run.',
         sections: [{
                 heading: 'Reads',
                 items: [
@@ -26,6 +26,9 @@ export const META_HELP = {
                     'Read-only, free, and account-scoped; it can only report the account its own credential'
                         + ' proves.',
                     'Totals cover the whole window even when --limit shortens the run list.',
+                    '--run-dir reads durable improve.json or redesign.json identities, writes spend.json beside it,'
+                        + ' and filters the returned account window locally. It names the searched window and truncation state'
+                        + ' instead of treating unreturned rows as absent. --conversion and --run add exact identities directly.',
                 ],
             }],
     },

package/dist/cli-help/meta.js.map

@@ -1 +1 @@
-{"version":3,"file":"meta.js","sourceRoot":"","sources":["../../src/cli-help/meta.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,YAAY,EAAE;QACZ,OAAO,EAAE,8DAA8D;QACvE,QAAQ,EAAE,CAAC;gBACT,OAAO,EAAE,UAAU;gBACnB,KAAK,EAAE;oBACL,2IAA2I;oBAC3I,sGAAsG;iBACvG;aACF,CAAC;KACH;IACD,KAAK,EAAE;QACL,OAAO,EAAE,iFAAiF;QAC1F,QAAQ,EAAE,CAAC;gBACT,OAAO,EAAE,OAAO;gBAChB,KAAK,EAAE;oBACL,wFAAwF;0BACtF,kEAAkE;oBACpE,2EAA2E;oBAC3E,0FAA0F;0BACxF,eAAe;iBAClB;aACF,EAAE;gBACD,OAAO,EAAE,OAAO;gBAChB,KAAK,EAAE;oBACL,wFAAwF;0BACtF,UAAU;oBACZ,wEAAwE;iBACzE;aACF,CAAC;KACH;IACD,GAAG,EAAE;QACH,OAAO,EAAE,qEAAqE;QAC9E,QAAQ,EAAE,CAAC;gBACT,OAAO,EAAE,UAAU;gBACnB,KAAK,EAAE;oBACL,qFAAqF;oBACrF,iHAAiH;iBAClH;aACF,CAAC;KACH;IACD,OAAO,EAAE;QACP,OAAO,EAAE,2CAA2C;QACpD,QAAQ,EAAE,CAAC;gBACT,OAAO,EAAE,OAAO;gBAChB,KAAK,EAAE,CAAC,mGAAmG,CAAC;aAC7G,CAAC;KACH;CACgC,CAAC"}
+{"version":3,"file":"meta.js","sourceRoot":"","sources":["../../src/cli-help/meta.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,YAAY,EAAE;QACZ,OAAO,EAAE,8DAA8D;QACvE,QAAQ,EAAE,CAAC;gBACT,OAAO,EAAE,UAAU;gBACnB,KAAK,EAAE;oBACL,2IAA2I;oBAC3I,sGAAsG;iBACvG;aACF,CAAC;KACH;IACD,KAAK,EAAE;QACL,OAAO,EAAE,gGAAgG;QACzG,QAAQ,EAAE,CAAC;gBACT,OAAO,EAAE,OAAO;gBAChB,KAAK,EAAE;oBACL,wFAAwF;0BACtF,kEAAkE;oBACpE,2EAA2E;oBAC3E,0FAA0F;0BACxF,eAAe;iBAClB;aACF,EAAE;gBACD,OAAO,EAAE,OAAO;gBAChB,KAAK,EAAE;oBACL,wFAAwF;0BACtF,UAAU;oBACZ,wEAAwE;oBACxE,gGAAgG;0BAC9F,qGAAqG;0BACrG,uGAAuG;iBAC1G;aACF,CAAC;KACH;IACD,GAAG,EAAE;QACH,OAAO,EAAE,qEAAqE;QAC9E,QAAQ,EAAE,CAAC;gBACT,OAAO,EAAE,UAAU;gBACnB,KAAK,EAAE;oBACL,qFAAqF;oBACrF,iHAAiH;iBAClH;aACF,CAAC;KACH;IACD,OAAO,EAAE;QACP,OAAO,EAAE,2CAA2C;QACpD,QAAQ,EAAE,CAAC;gBACT,OAAO,EAAE,OAAO;gBAChB,KAAK,EAAE,CAAC,mGAAmG,CAAC;aAC7G,CAAC;KACH;CACgC,CAAC"}

package/dist/cli-improve-command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-improve-command.d.ts","sourceRoot":"","sources":["../src/cli-improve-command.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAenD,OAAO,EAQL,KAAK,0BAA0B,EAChC,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAIL,KAAK,aAAa,EAEnB,MAAM,wBAAwB,CAAC;AA2FhC,eAAO,MAAM,iBAAiB,GAC5B,SAAS,SAAS,MAAM,EAAE,EAC1B,OAAO,QAAQ,EACf,eAAc,0BAA+B,KAC5C,OAAO,CAAC,aAAa,CA4SvB,CAAC"}
+{"version":3,"file":"cli-improve-command.d.ts","sourceRoot":"","sources":["../src/cli-improve-command.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAiCnD,OAAO,EAaL,KAAK,0BAA0B,EAChC,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAKL,KAAK,aAAa,EAGnB,MAAM,wBAAwB,CAAC;AA8MhC,eAAO,MAAM,iBAAiB,GAC5B,SAAS,SAAS,MAAM,EAAE,EAC1B,OAAO,QAAQ,EACf,eAAc,0BAA+B,KAC5C,OAAO,CAAC,aAAa,CAgbvB,CAAC"}

package/dist/cli-improve-command.js

@@ -5,14 +5,22 @@ import { CliRefusal } from './cli-refusal.js';
 import { prepareOutputDirectory } from './cli-output-paths.js';
 import { parseImproveOptions } from './improve-options.js';
 import { buildImprovePricingPlan } from './improve-pricing-plan.js';
+import { assertImproveCaptureNotRedirected } from './improve-capture-redirect.js';
+import { improveBootstrapRecordFields, redactImproveBootstrap, } from './improve-bootstrap-secret.js';
+import { hasImprovePaidStage, improveBootstrapChanged, rebootstrapImproveRecord, } from './improve-bootstrap-history.js';
 import { improveStalled, retryImproveTemporarilyUnavailable } from './improve-convert-resilience.js';
-import { writeImproveStallReport } from './improve-kit-stall.js';
+import { ensureImproveKitIgnored } from './improve-kit-ignore.js';
+import { resolveImproveStall, writeImproveFallbackStall, writeImproveStallReport, } from './improve-kit-stall.js';
+import { readImproveKitStatus } from './improve-kit-status.js';
 import { resetImproveDraw } from './improve-reset.js';
 import { awaitingImprovePick, buildImproveRunSummary, improveStallErrorWithSummary, } from './improve-run-summary.js';
+import { readImproveSpendLedger } from './improve-spend-ledger.js';
+import { markImproveStageStalled } from './improve-stage-shared.js';
 import { registerImproveStopHandler } from './improve-stop-handler.js';
 import { noteImproveTerminalEvent } from './improve-terminal-event.js';
-import { runImproveCaptureStage, runImproveConvertStage, runImproveDraftStage, markImproveStageSkipped, runImprovePickStage, runImprovePlanStage, writeImproveReadme, } from './improve-stage-runners.js';
-import { IMPROVE_STAGES, readImproveRecord, writeImproveRecord, } from './improve-workspace.js';
+import { runImproveCaptureStage, runImproveConvertStage, runImproveSiteConvertStage, runImproveBranchStage, runImproveDraftStage, markImproveStageSkipped, runImprovePickStage, runImprovePlanStage, runImproveSiteRecheck, runImproveSitePlanPagesStage, runImproveSiteStage, writeImproveReadme, } from './improve-stage-runners.js';
+import { discoverRedesignPageUrls, pageId } from './redesign-capture.js';
+import { IMPROVE_STAGES, IMPROVE_SITE_ROOT_ID, readImproveRecord, writeImproveRecord, } from './improve-workspace.js';
 /**
  * `12ui improve`: one replay-aware local orchestrator over existing draft and
  * convert commands, redesign's Playwright provisioning, and the local plan
@@ -48,6 +56,7 @@ const assertCompatibleRecord = async (args) => {
     // match: a redraw does not license a different model or a different page.
     const drawFlags = new Set(args.parsed.redraw ? ['direction', 'candidates', 'retain'] : []);
     const explicitChecks = [
+        ['scope', args.record.scope, args.parsed.scope],
         ['direction', args.record.direction, args.parsed.direction],
         ['candidates', args.record.candidates, args.parsed.candidates],
         ['retain', args.record.retain, args.parsed.retain],
@@ -55,11 +64,19 @@ const assertCompatibleRecord = async (args) => {
         ['responsive-quality', args.record.responsiveQuality, args.parsed.responsiveQuality],
         ['viewport', args.record.viewport, args.parsed.viewport],
         ['full-page', args.record.fullPage, args.parsed.fullPage],
-        ['bootstrap', args.record.bootstrap, args.parsed.bootstrapValues],
         ['repo', args.record.repo, args.parsed.repo],
         ['plan-source-convert', args.record.planSourceConvert, args.parsed.planSourceConvert],
+        ['pages', args.record.pageLimit, args.parsed.pages],
+        ['page', args.record.requestedPages, args.parsed.explicitPages],
+        ['page-concurrency', args.record.pageConcurrency, args.parsed.pageConcurrency],
+        ['reference-order', args.record.referenceOrder, args.parsed.referenceOrder],
         ['target', args.record.target && { kind: args.record.target.kind, value: args.record.target.value }, args.parsed.target],
     ];
+    // `--bootstrap` compares by digest, because the record deliberately holds no
+    // live value to compare against (F31), and neither side of the refusal may
+    // print the secret.
+    const bootstrapChanged = args.flags.bootstrap !== undefined
+        && improveBootstrapChanged(args.record, args.parsed.bootstrapValues);
     for (const [flag, recorded, requested] of explicitChecks) {
         if (drawFlags.has(flag))
             continue;
@@ -83,10 +100,100 @@ const assertCompatibleRecord = async (args) => {
             throw new CliRefusal('The --target bytes changed. Start a new improve directory.', 'improve_target_changed');
         }
     }
+    if (!bootstrapChanged)
+        return args.record;
+    if (hasImprovePaidStage(args.record)) {
+        throw new CliRefusal('--bootstrap does not match the durable improve record.'
+            + ` The record holds ${describeRecordedValue(args.record.bootstrap)}`
+            + ' (query values redacted; the live value is never stored);'
+            + ` this run asked for ${describeRecordedValue(args.parsed.bootstrapValues.map(redactImproveBootstrap))}.`
+            + ' Paid work has already been dispatched from this capture, so improve cannot replace it in place.'
+            + ' Drop --bootstrap to replay the captured page and its purchased work, or start a new kit with'
+            + ' a new --out-dir before using the changed bootstrap.', 'improve_record_mismatch');
+    }
+    return rebootstrapImproveRecord({
+        record: args.record,
+        bootstrapValues: args.parsed.bootstrapValues,
+    });
 };
 const missingStage = (stage, runDir) => {
     throw new CliRefusal(`Stage ${stage} has not settled in ${runDir}. Include it in the stage range first.`, `improve_${stage}_missing`);
 };
+const uniquePageUrls = (root, candidates) => {
+    const urls = [];
+    const seen = new Set();
+    for (const candidate of [root, ...candidates]) {
+        const url = new URL(candidate, root);
+        url.hash = '';
+        const key = `${url.origin}${url.pathname}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        urls.push(url.toString());
+    }
+    return urls;
+};
+const titleForPage = (url, id) => {
+    if (new URL(url).pathname === '/')
+        return 'Home';
+    return id.split('-').filter(Boolean)
+        .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
+        .join(' ') || 'Page';
+};
+const sitePages = async (args) => {
+    if (args.parsed.scope === 'page')
+        return { rootUrl: args.parsed.input.value, pages: [] };
+    if (args.prior?.scope === 'site' && args.prior.pages.length > 0) {
+        return { rootUrl: args.prior.input.value, pages: args.prior.pages };
+    }
+    const candidates = args.parsed.explicitPages.length > 0
+        ? args.parsed.explicitPages
+        : await (args.dependencies.discoverPages ?? discoverRedesignPageUrls)({
+            url: args.parsed.input.value,
+            maxPages: args.parsed.pages,
+        });
+    // The root is represented by the top-level ImproveRecord fields. `pages`
+    // deliberately contains only branchable non-root routes, while the cap and
+    // validation below still count the root.
+    // Discovery's first URL is the root it actually fetched. Keeping the raw
+    // input ahead of it made redirecting sites capture the same root twice:
+    // `hubspot.com/` and `www.hubspot.com/` differ by origin, so the normal
+    // same-origin dedupe quite correctly could not join them. Explicit pages
+    // remain rooted at the requested URL; they did not perform discovery.
+    const discovered = uniquePageUrls(args.parsed.explicitPages.length > 0 ? args.parsed.input.value : (candidates[0] ?? args.parsed.input.value), candidates);
+    const urls = args.parsed.explicitPages.length > 0
+        ? discovered
+        : args.parsed.dryRun
+            ? discovered.slice(0, args.parsed.pages)
+            // Paid capture has one browser context anyway. Reserve local output
+            // slots through the requested cap, then let that rendered root replace
+            // this fetched inventory before it captures anything. This is what lets
+            // an SPA whose fetched shell names only `/` reach free DOM discovery;
+            // its placeholder is never navigated or persisted after capture.
+            : Array.from({ length: args.parsed.pages }, (_, index) => (discovered[index] ?? new URL(`/__12ui-discovery-slot-${index}`, discovered[0] ?? args.parsed.input.value).toString()));
+    if (urls.length < 2 || urls.length > 8) {
+        throw new CliRefusal(`--scope site requires 2–8 same-origin pages including the root; found ${urls.length}`, 'improve_pages_invalid');
+    }
+    const used = new Set();
+    return {
+        rootUrl: urls[0] ?? args.parsed.input.value,
+        pages: urls.slice(1).map((url, index) => {
+            let id = pageId(url, index + 1).slice(0, 64);
+            while (used.has(id)) {
+                const suffix = `-${index + 1}`;
+                id = `${id.slice(0, 64 - suffix.length)}${suffix}`;
+            }
+            used.add(id);
+            const parsedUrl = new URL(url);
+            return {
+                id,
+                url,
+                title: titleForPage(url, id),
+                route: `${parsedUrl.pathname}${parsedUrl.search}`,
+            };
+        }),
+    };
+};
 export const runImproveCommand = async (command, flags, dependencies = {}) => {
     const parsed = parseImproveOptions({
         command,
@@ -94,11 +201,30 @@ export const runImproveCommand = async (command, flags, dependencies = {}) => {
         ...(dependencies.workspaceRoot ? { workspaceRoot: dependencies.workspaceRoot } : {}),
     });
     const prior = parsed.dryRun ? undefined : await readImproveRecord(parsed.paths.record);
+    if (parsed.recheck) {
+        if (!prior || prior.scope !== 'site'
+            || prior.stages.site?.outcome !== 'settled' || !prior.site) {
+            throw new CliRefusal('--recheck requires a settled --scope site kit', 'improve_recheck_invalid');
+        }
+        await assertCompatibleRecord({ record: prior, parsed, flags });
+        await prepareOutputDirectory(parsed.paths.runDir);
+        const write = dependencies.write ?? ((line) => { process.stdout.write(`${line}\n`); });
+        write(parsed.paths.runDir);
+        dependencies.onRunDirectory?.(parsed.paths.runDir);
+        const record = await runImproveSiteRecheck({ record: prior, options: parsed, dependencies });
+        dependencies.journal?.note({ workspace: parsed.paths.runDir, writes: [parsed.paths.record] });
+        console.log(JSON.stringify({ recheck: record.rechecks?.at(-1), ...record }, null, 2));
+        return record;
+    }
+    const siteDiscovery = await sitePages({ parsed, prior, dependencies });
+    const pages = siteDiscovery.pages;
     const pricing = buildImprovePricingPlan({
         inputKind: parsed.input.kind,
         candidates: parsed.candidates,
         conversionModel: parsed.conversionModel,
         planSourceConvert: parsed.planSourceConvert,
+        scope: parsed.scope,
+        pages: parsed.scope === 'site' ? pages.length + 1 : 0,
         ...((parsed.target ?? prior?.target) ? { targetKind: (parsed.target ?? prior.target).kind } : {}),
     });
     const price = new Map(pricing.stages.map((stage) => [stage.stage, stage.priceCeilingUsd]));
@@ -114,10 +240,17 @@ export const runImproveCommand = async (command, flags, dependencies = {}) => {
             conversionModel: parsed.conversionModel,
             responsiveQuality: parsed.responsiveQuality,
             ...pricing,
-            note: 'Nothing was captured, read from the network, claimed, dispatched, or bought.',
+            scope: parsed.scope,
+            pages: parsed.scope === 'site'
+                ? [{ id: IMPROVE_SITE_ROOT_ID, url: siteDiscovery.rootUrl }, ...pages.map((page) => ({ id: page.id, url: page.url }))]
+                : [],
+            note: parsed.scope === 'site' && parsed.explicitPages.length === 0
+                ? 'Discovery fetched only the root HTML. Nothing was captured in a browser, claimed, dispatched, or bought.'
+                : 'Nothing was captured in a browser, claimed, dispatched, or bought.',
         }, null, 2));
         return {
-            version: 1,
+            version: 2,
+            scope: parsed.scope,
             createdAt: new Date().toISOString(),
             runDir: '',
             input: parsed.input,
@@ -130,20 +263,28 @@ export const runImproveCommand = async (command, flags, dependencies = {}) => {
             responsiveQuality: parsed.responsiveQuality,
             viewport: parsed.viewport,
             fullPage: parsed.fullPage,
-            bootstrap: parsed.bootstrapValues,
+            ...improveBootstrapRecordFields(parsed.bootstrapValues),
             ...(parsed.repo ? { repo: parsed.repo } : {}),
             planSourceConvert: parsed.planSourceConvert,
+            pageLimit: parsed.pages,
+            requestedPages: parsed.explicitPages,
+            pageConcurrency: parsed.pageConcurrency,
+            referenceOrder: parsed.referenceOrder,
+            pages,
             stages: {},
         };
     }
     await prepareOutputDirectory(parsed.paths.runDir);
     const existing = prior;
-    if (existing)
-        await assertCompatibleRecord({ record: existing, parsed, flags });
-    else if (parsed.from !== 'capture')
+    const compatible = existing
+        ? await assertCompatibleRecord({ record: existing, parsed, flags })
+        : undefined;
+    const rebootstrap = compatible !== undefined && compatible !== existing;
+    if (!existing && parsed.from !== 'capture')
         missingStage('capture', parsed.paths.runDir);
-    let record = existing ?? {
-        version: 1,
+    let record = compatible ?? {
+        version: 2,
+        scope: parsed.scope,
         createdAt: new Date().toISOString(),
         runDir: parsed.paths.runDir,
         input: parsed.input,
@@ -157,11 +298,21 @@ export const runImproveCommand = async (command, flags, dependencies = {}) => {
         responsiveQuality: parsed.responsiveQuality,
         viewport: parsed.viewport,
         fullPage: parsed.fullPage,
-        bootstrap: parsed.bootstrapValues,
+        ...improveBootstrapRecordFields(parsed.bootstrapValues),
         ...(parsed.repo ? { repo: parsed.repo } : {}),
         planSourceConvert: parsed.planSourceConvert,
+        pageLimit: parsed.pages,
+        requestedPages: parsed.explicitPages,
+        pageConcurrency: parsed.pageConcurrency,
+        referenceOrder: parsed.referenceOrder,
+        pages,
         stages: {},
     };
+    // A kit written inside the repository it improves is ~100 MB of paid
+    // artifacts one `git add -A` away from someone's history (F17). Decided every
+    // run, because the repository's own `.gitignore` can change between them.
+    const kitIgnore = await ensureImproveKitIgnored({ outDir: parsed.paths.runDir });
+    record = { ...record, ...(kitIgnore ? { kitIgnore } : {}) };
     await writeImproveRecord(parsed.paths.record, record);
     const write = dependencies.write ?? ((line) => { process.stdout.write(`${line}\n`); });
     write(parsed.paths.runDir);
@@ -178,6 +329,8 @@ export const runImproveCommand = async (command, flags, dependencies = {}) => {
     // apart from a signal after completion. The record cannot: `--fresh` clears
     // convert and plan from the durable record inside the convert stage, and
     // `record` here is only reassigned when that stage returns.
+    const extendedPageRange = record.scope === 'site'
+        || [flags.from, flags.to].some((value) => value === 'branch' || value === 'site');
     let liveStage;
     const runStage = async (stage, action) => {
         liveStage = stage;
@@ -201,8 +354,14 @@ export const runImproveCommand = async (command, flags, dependencies = {}) => {
     // lane was KILLED, not stalled, so it threw nothing the catch below could
     // have seen. The handler is armed here, before the first stage, because a
     // kill during capture, draft or pick used to leave nothing at all.
+    // A signal wrote this kit's `plan/STALL.md` during this very invocation, so
+    // nothing later in it may resolve that file away: in production the handler
+    // exits the process, and a harness that lets the stage unwind must not answer
+    // the signal by declaring the run fine (F21).
+    let stopped = false;
     const disarmStop = registerImproveStopHandler({
         getRecord: () => record,
+        onStopped: () => { stopped = true; },
         getLiveStage: () => liveStage,
         write,
         requestedTo: parsed.to,
@@ -249,13 +408,20 @@ export const runImproveCommand = async (command, flags, dependencies = {}) => {
             }
         }
         if (needed('capture')) {
-            if (within('capture'))
+            if (within('capture') || rebootstrap)
                 record = await runStage('capture', () => runImproveCaptureStage({
                     record, options: parsed, dependencies, price: price.get('capture') ?? 0,
                 }));
             if (!record.capture)
                 missingStage('capture', parsed.paths.runDir);
             await refreshReadme();
+            // Free, deterministic, and BEFORE the draft purchase: the captured page
+            // and the requested one have to be the same page, or nothing is bought
+            // (F27). The capture and the README above are already on disk, so the
+            // refusal costs a reader nothing and the next run replays them.
+            assertImproveCaptureNotRedirected({
+                record, allowRedirect: parsed.allowRedirect, runDir: parsed.paths.runDir,
+            });
         }
         if (needed('draft')) {
             if (record.target) {
@@ -264,7 +430,7 @@ export const runImproveCommand = async (command, flags, dependencies = {}) => {
             else {
                 if (within('draft'))
                     record = await runStage('draft', () => runImproveDraftStage({
-                        record, options: parsed, flags, dependencies, price: price.get('draft') ?? 0,
+                        record, options: parsed, dependencies, price: price.get('draft') ?? 0,
                     }));
                 if (!record.draft)
                     missingStage('draft', parsed.paths.runDir);
@@ -290,7 +456,13 @@ export const runImproveCommand = async (command, flags, dependencies = {}) => {
                     // rather than quietly stopping where it was told not to.
                     if (!chosen) {
                         await refreshReadme();
-                        write(awaitingImprovePick({ record, options: parsed }));
+                        write(awaitingImprovePick({
+                            record,
+                            options: parsed,
+                            // The draw is paid work and this is a stop, so the ids leave with
+                            // the reader (F33).
+                            ledger: await readImproveSpendLedger(record),
+                        }));
                         dependencies.journal?.note({
                             workspace: parsed.paths.runDir,
                             artifacts: [parsed.paths.record, parsed.paths.readme],
@@ -309,28 +481,68 @@ export const runImproveCommand = async (command, flags, dependencies = {}) => {
             }
             await refreshReadme();
         }
+        if (needed('branch')) {
+            if (record.scope === 'page') {
+                if (extendedPageRange)
+                    record = await markImproveStageSkipped(record, 'branch');
+            }
+            else {
+                if (within('branch'))
+                    record = await runStage('branch', () => runImproveBranchStage({
+                        record, options: parsed, dependencies, price: price.get('branch') ?? 0,
+                    }));
+                if (!record.branch)
+                    missingStage('branch', parsed.paths.runDir);
+            }
+            await refreshReadme();
+        }
         try {
             if (needed('convert')) {
                 if (within('convert'))
-                    record = await runStage('convert', () => runImproveConvertStage({
-                        record,
-                        options: parsed,
-                        dependencies,
-                        price: price.get('convert') ?? 0,
-                        ...(freshConversionNonce ? { freshConversionNonce } : {}),
-                    }));
+                    record = await runStage('convert', () => (record.scope === 'site'
+                        ? runImproveSiteConvertStage({
+                            record,
+                            options: parsed,
+                            dependencies,
+                            price: price.get('convert') ?? 0,
+                            ...(freshConversionNonce ? { freshConversionNonce } : {}),
+                        })
+                        : runImproveConvertStage({
+                            record,
+                            options: parsed,
+                            dependencies,
+                            price: price.get('convert') ?? 0,
+                            ...(freshConversionNonce ? { freshConversionNonce } : {}),
+                        })));
                 if (!record.convert)
                     missingStage('convert', parsed.paths.runDir);
                 await refreshReadme();
             }
             if (needed('plan')) {
                 if (within('plan'))
-                    record = await runStage('plan', () => runImprovePlanStage({
-                        record, options: parsed, dependencies, price: price.get('plan') ?? 0,
-                    }));
+                    record = await runStage('plan', () => (record.scope === 'site'
+                        ? runImproveSitePlanPagesStage({
+                            record, options: parsed, dependencies, price: price.get('plan') ?? 0,
+                        })
+                        : runImprovePlanStage({
+                            record, options: parsed, dependencies, price: price.get('plan') ?? 0,
+                        })));
                 if (!record.plan)
                     missingStage('plan', parsed.paths.runDir);
             }
+            if (needed('site')) {
+                if (record.scope === 'page') {
+                    record = await markImproveStageSkipped(record, 'site');
+                }
+                else {
+                    if (within('site'))
+                        record = await runStage('site', () => runImproveSiteStage({
+                            record, options: parsed, dependencies, price: price.get('site') ?? 0,
+                        }));
+                    if (!record.site)
+                        missingStage('site', parsed.paths.runDir);
+                }
+            }
         }
         catch (error) {
             // The durable record is the truth here: a stage that failed still wrote
@@ -344,6 +556,14 @@ export const runImproveCommand = async (command, flags, dependencies = {}) => {
             // failure, a refusal — keeps that classification: `withRunJournal` ends
             // it on the way out and the throw below is what gets there.
             const stalled = improveStalled(error);
+            // The durable record has to say the paid call never came back. `outcome`
+            // is the one field a supervisor or a parser reads, and it stayed
+            // `dispatched` — which reads as "in flight" long after the run ended (F28).
+            const marked = markImproveStageStalled({ record, stage: stalledStage, stalled });
+            if (marked !== record) {
+                record = marked;
+                await writeImproveRecord(parsed.paths.record, record);
+            }
             if (stalled) {
                 // Everything the record is owed goes in HERE. The session refuses to
                 // write after its end line, so the note that used to follow this call
@@ -375,16 +595,41 @@ export const runImproveCommand = async (command, flags, dependencies = {}) => {
             }
             throw improveStallErrorWithSummary(error, await buildImproveRunSummary({ record, requestedTo: parsed.to }));
         }
+        // A run that fell back to fixed layout finished, but something stalled on
+        // the way. It gets the same `plan/STALL.md` a dead run gets — written after
+        // the plan, so it can say the plan was built from the derivation — and the
+        // README, written next, links to it (F8).
+        const fallbackStall = await writeImproveFallbackStall({ record, requestedTo: parsed.to });
+        // And a run that SETTLED what an earlier one stalled on replaces the file
+        // that earlier one left. Freshdesk shipped a settled plan under a README
+        // saying "settled" beside a STALL.md saying "INCOMPLETE — no plan"; the
+        // reader had no way to tell which was current (F21).
+        const resolvedStall = fallbackStall || stopped
+            ? undefined
+            : await resolveImproveStall({
+                record,
+                status: await readImproveKitStatus({ record, requestedTo: parsed.to }),
+            });
+        const stallFile = fallbackStall ?? resolvedStall;
         const readme = await refreshReadme();
         dependencies.journal?.note({
             workspace: parsed.paths.runDir,
-            artifacts: [parsed.paths.record, readme, ...(record.plan?.artifacts ?? [])],
+            artifacts: [
+                parsed.paths.record,
+                readme,
+                ...(stallFile ? [stallFile] : []),
+                ...(record.plan?.artifacts ?? []),
+                ...(record.pages.flatMap((page) => page.plan?.artifacts ?? [])),
+                ...(record.site?.artifacts ?? []),
+            ],
             purchased: [
                 ...(record.draft ? [record.draft.runId] : []),
                 ...(record.convert?.purchaseIds ?? []),
                 ...(record.sourceConvert?.purchaseIds ?? []),
+                ...(record.pages.flatMap((page) => page.convert?.purchaseIds ?? [])),
+                ...(record.branch ? [record.branch.runId] : []),
             ],
-            terminal: parsed.to === 'plan',
+            terminal: parsed.to === 'site' || (record.scope === 'page' && parsed.to === 'plan'),
         });
         console.log(JSON.stringify({ from: parsed.from, to: parsed.to, ...record }, null, 2));
         write(await buildImproveRunSummary({ record, requestedTo: parsed.to }));