@nextcommerce/campaigns-os 1.55.0 → 1.57.0

package/contracts/runtime-recipe.campaigns-os-node-v1.json

@@ -3,7 +3,7 @@
   "_growth_note": "When a bound below is genuinely reached, the answer is to find out why before raising it. A dependency install that exceeds its bound on a warm machine is a supply-chain change, not a slow morning; an output inventory that exceeds its file or byte bound is a build that went wrong, not a package that grew 50x overnight. Raising a bound is the fallback, it advances recipe_revision, and it owes a release-ledger entry. Widening the accepted npm range follows the same path, and its trigger is external and checkable: widen when a Node release line ships that npm major by default, not when a particular machine happens to have it installed.",
   "schema": "campaigns-os-runtime-recipe/v1",
   "recipe_kind": "campaigns-os-node-v1",
-  "recipe_revision": "1.0.2",
+  "recipe_revision": "1.0.3",
   "refusal_reason_code": "runtime_recipe_refused",
   "fail_closed": true,
   "unperformable_check_disposition": "failed",
@@ -106,6 +106,7 @@
     "fingerprint_algorithm": "sha256",
     "files": [
       "campaign-spec/analytics-vocabulary.ts",
+      "campaign-spec/checkout-flow.ts",
       "campaign-spec/index.ts",
       "campaign-spec/normalize.ts",
       "campaign-spec/package.json",
@@ -113,7 +114,9 @@
       "campaign-spec/rules/analytics-contract-shape.ts",
       "campaign-spec/rules/assembly-hints-shape.ts",
       "campaign-spec/rules/campaign-metadata.ts",
+      "campaign-spec/rules/checkout-forward-target.ts",
       "campaign-spec/rules/checkout-has-success-url.ts",
+      "campaign-spec/rules/checkout-step-reaches-checkout.ts",
       "campaign-spec/rules/cycle-detection.ts",
       "campaign-spec/rules/design-source-shape.ts",
       "campaign-spec/rules/downsell-without-upsell.ts",
@@ -124,9 +127,11 @@
       "campaign-spec/rules/funnel-weight-sum.ts",
       "campaign-spec/rules/index.ts",
       "campaign-spec/rules/offer-ref-integrity.ts",
+      "campaign-spec/rules/one-checkout-per-path.ts",
       "campaign-spec/rules/package-pricing-sanity.ts",
       "campaign-spec/rules/page-count.ts",
       "campaign-spec/rules/page-id-uniqueness.ts",
+      "campaign-spec/rules/pre-payment-forward-target.ts",
       "campaign-spec/rules/promo-code-input-validation.ts",
       "campaign-spec/rules/promo-codes-shape.ts",
       "campaign-spec/rules/route-field-ignored-for-page-type.ts",

package/contracts/supported-surface.json

@@ -1,6 +1,6 @@
 {
   "_note": "The downstream contract manifest. Everything listed here is SUPPORTED SURFACE: consumers (campaigns-agent, campaign-builder, the private ops repo, page-kit campaign repos) may depend on it, and changing it is a deliberate act — hashed entries require a surface_version bump in the same change (check-supported-surface.mjs --base, mirroring the skills.json bump gate), named entries must keep existing at their path, cli_commands must keep resolving in the CLI dispatch, package_exports must stay exported, and every entry must ship in the npm pack (files[] coverage). Anything NOT listed here — src/** internals, scripts/** checkers, examples/**, prompts/**, contracts/** other than this file and the entries named[] below (the orientation contract, the release ledger, and the consumer-facing orientation fixtures) — is implementation: consumers may read it for context but must not build on it, and it can change without notice. Rationale and the compatibility promise: docs/supported-surface.md.",
-  "surface_version": "1.55.0",
+  "surface_version": "1.57.0",
   "package_exports": [
     "./commercial-journey",
     "./commercial-parity",
@@ -8,6 +8,7 @@
     "./campaign-spec",
     "./legacy-migration",
     "./schemas/campaign-spec.v4.schema.json",
+    "./schemas/campaign-spec.v5.schema.json",
     "./schemas/campaigns-os-legacy-migration-inventory.v0.schema.json",
     "./schemas/campaigns-os-legacy-provisioning-plan.v0.schema.json",
     "./schemas/campaigns-os-legacy-provisioning-receipt.v0.schema.json",
@@ -51,7 +52,7 @@
       "sha256": "53269453dfdaac4b286124d445b60b0c46205dfbaf8037ac61b30254a32df53a"
     },
     "contracts/runtime-recipe.campaigns-os-node-v1.json": {
-      "sha256": "90aaaaade90cf2525ea1aa05be5cb2d02b57e6e59f9278a946efa8a087946fd3"
+      "sha256": "ab0537a4756310d3a35b400d3932e46695a820f1b8b398f52f6fd0906098bc1d"
     },
     "schemas/campaign-build-brief.v1.schema.json": {
       "sha256": "d524003184131398dc15fdb84385af1be0de0c69d6c5ede7278689a5b6101b81"
@@ -63,14 +64,17 @@
       "sha256": "625a6f2ed6bee726f9cddad750e64a54a7e03744c777f5a70afe4a39afdd9848"
     },
     "schemas/campaign-runtime-build-context.v0.schema.json": {
-      "sha256": "f310c1b7844d9b1994864d15858ff0c6f17efc1e5285ba193d181bdb2dd4be2f"
+      "sha256": "1f9bd6cced44a8ba6b29cc650f2b071db67ad710c5a9e9dfe47287eac11e0ebf"
     },
     "schemas/campaign-runtime-build-packet.v0.schema.json": {
-      "sha256": "5002529c5979c4d8fef7e298de82ebdf625ffbd11f5284ba684d96d173788d62"
+      "sha256": "f0952f64fe9f5ae6147649e5e99b24f215c8d080fca4e330d73f54e49a00d0e2"
     },
     "schemas/campaign-spec.v4.schema.json": {
       "sha256": "af56c3de638d3c4e1fd5df8c2d733754d9ad16caa23b5bec92ce3a6f71bd0271"
     },
+    "schemas/campaign-spec.v5.schema.json": {
+      "sha256": "2923382e94ac51f6a19a3f9dfd0993d8c30fab33cd9be3d6901f314e02f5d960"
+    },
     "schemas/campaigns-os-legacy-migration-inventory.v0.schema.json": {
       "sha256": "d6edc4572900d15fdaf6b8c59916b0d885303c1d398bdadeb7c58285522c9049"
     },

package/docs/build-packet.md

@@ -19,7 +19,8 @@ The current schema is `schemas/campaign-runtime-build-packet.v0.schema.json`.
 
 A saved Map is optional for a prepared-HTML build. The coding agent authors an
 ordinary CampaignSpec from the brief, source design and configured campaign's
-real commerce values, following `schemas/campaign-spec.v4.schema.json`. The
+real commerce values, following `schemas/campaign-spec.v5.schema.json` (a 4.2/4.3
+spec still reads, upgraded on read; see `docs/versioning.md`). The
 operator supplies the selected store/campaign, public Campaigns API key, intended
 pages and commercial choices, plus store contact details and policy URLs. Verify
 the store/campaign binding, and read the package, offer and shipping references
@@ -1020,13 +1021,25 @@ than hand-adding the field. Note that a committed artifact set always reads
 stale to the readback once HEAD moves past it — freshness proof is a
 regeneration at HEAD, not a property a commit can preserve.
 
-Commit durable packet/context/report artifacts when they represent a real build handoff. The rest of `.campaign-runtime/` is machine-local and is not for the campaign repository: `run-session.json`, `command-lifecycle.jsonl`, `agent-deviations.jsonl`, `workflow-findings.jsonl`, `run-records/`, `fetched-specs/`, `polish-evidence/`, `evidence/`, and `*.log`/`*.tmp` are per-machine, append-only, or carry live URLs and absolute paths, and so are the full QA verdicts `qa run` writes under the target's `qa-output/`. `start`, `prepare-build`, `install-agent-context`, and `run start` write a managed ignore block for exactly that set into the target's `.gitignore` once (keyed on its marker line; edit the list beneath it freely). The readback bundle (`build-context.json`, `assembly-report.json`, `doctor-output.json`, `qa-verdict.json`), `input/`, `theme/`, `agent-context/`, and `setup-handoff.json` are deliberately not ignored. The Campaigns API key is a public, browser-side, domain-allowlisted key and may already be present in the local CampaignSpec as `campaign.campaigns_api_key`; do not duplicate it into the packet unless the spec is unavailable. Do not commit raw private API responses, backend secrets, or temporary media exports.
+Commit durable packet/context/report artifacts when they represent a real build handoff. The rest of `.campaign-runtime/` is machine-local and is not for the campaign repository: `run-session.json`, `command-lifecycle.jsonl`, `agent-deviations.jsonl`, `workflow-findings.jsonl`, `run-records/`, `fetched-specs/`, `progress/`, `polish-evidence/`, `evidence/`, and `*.log`/`*.tmp` are per-machine, append-only, or carry live URLs and absolute paths, and so are the full QA verdicts `qa run` writes under the target's `qa-output/`. `start`, `prepare-build`, `install-agent-context`, and `run start` write a managed ignore block for that set into the target's `.gitignore` (keyed on its marker line; edit the list beneath it freely). An existing block gains `qa-output/` and `.campaign-runtime/progress/` when they are missing, since those hold live URLs, order references and remit records. The readback bundle (`build-context.json`, `assembly-report.json`, `doctor-output.json`, `qa-verdict.json`), `input/`, `theme/`, `agent-context/`, and `setup-handoff.json` are deliberately not ignored. The Campaigns API key is a public, browser-side, domain-allowlisted key and may already be present in the local CampaignSpec as `campaign.campaigns_api_key`; do not duplicate it into the packet unless the spec is unavailable. Do not commit raw private API responses, backend secrets, or temporary media exports.
 
 Packet-mode `doctor` is inspection-only by default and preserves retained evidence and active run journals, even when lifecycle capture is configured. Use `--write` to intentionally record fresh evidence; `--no-write` takes precedence. Inspection still reports current blockers and keeps the same exit status.
 
 `campaigns-os doctor --packet <packet> --write` restates its outcome on the Assembly Report's `stages.doctor` (status, command, outputs, blockers, warnings, `checked_at`). A re-run that reaches the same outcome leaves the report's bytes unchanged rather than refreshing the timestamp alone, so a digest taken of the report — a Run Record's `assembly_report` sha256 — keeps verifying across repeated doctor runs; a changed outcome still rewrites the file.
 
-`campaigns-os start` / `campaigns-os prepare-build` writes packet, context, report, and generated doctor-output paths as relative paths by default, including sibling CampaignSpec/source directories such as `../campaign-source`. `campaigns-os doctor` continues to accept older absolute-path packets; use `campaigns-os doctor --packet <packet> --write --strip-paths` when regenerating a commit-ready doctor output from an older packet. Committed handoff artifacts should not contain machine-local absolute paths unless no relative form is possible.
+`campaigns-os start` / `campaigns-os prepare-build` writes portable packet, context, report, and generated doctor-output paths. Resolve each path from its reader's base:
+
+| Field | Base | Writer |
+|---|---|---|
+| Build Packet `spec.local_path`, `design_source_package.path`, `source_html.root`, `build_brief.input_path`, `build_brief.normalized_path`, `assembly.target_repo`, `assembly.commerce_catalog.path` | Build Packet file's directory, including when `--out` places it under `config/` | `start` / `prepare-build`; `record brief` and stage records retain this base for older absolute values |
+| Build Packet `source_html.pages[].path`; Build Context `page_map[].source_path` | Source HTML root | `start` / `prepare-build`; later context writes retain it |
+| Build Packet and Build Context `source_html.pages[].page_kit.target_path` / `page_map[].page_kit.target_path` | Page Kit output directory | `start` / `prepare-build`; later packet/context writes retain it |
+| Build Packet `assembly.output_dir` and `source_html.pages[].page_kit.output_path`; Build Context `page_map[].output_path` and `page_map[].page_kit.output_path` | Target repository root | `start` / `prepare-build`; later packet/context writes retain it |
+| Build Context and Assembly Report `design_source_package.path` | Directory of that context or report file (normally `.campaign-runtime/`) | `start` / `prepare-build`; later report writes retain it |
+| Normalized Campaign Build Brief `_meta.input_path` | Directory of the normalized brief file | `start` / `prepare-build`; `record brief` and `record spec` retain it |
+| Other listed Build Context, Assembly Report, and doctor-output filesystem paths | Target repository root | Intake, `doctor --write`, `next`, and stage writes |
+
+Outside source inputs use ordinary relative paths from the applicable base; keep them at the recorded locations when moving the repository. Manifest paths embedded in decision evidence use relative paths from the target repository root. A stored command such as `next.command` uses a relative packet path and runs from the target repository root. `campaigns-os doctor` continues to accept older absolute-path packets; `--strip-paths` remains available when inspecting an older packet. Machine-local run sessions and journals remain ignored and may use absolute paths.
 
 `start` / `prepare-build` also run the [Brand Theme Bridge](./brand-theme-bridge.md)
 in `inspect_only` mode. The optional theme evidence lives in `context.theme`,
@@ -1463,10 +1476,29 @@ Fresh `prepare-build` output also writes `source_html.pages[].page_kit` for mapp
 - `target_path` is the page file relative to `assembly.output_dir` (`checkout.html`, `receipt.html`, etc.).
 - `output_path` is the same target file relative to `assembly.target_repo`.
 - `public_route` is the rendered campaign-rooted route Page Kit should produce.
-- `page_type` is the CPK runtime/analytics vocabulary (`product`, `checkout`, `upsell`, `receipt`), not the richer CampaignSpec or producer page type. CampaignSpec `select` pages project as CPK `checkout` because they are pre-checkout runtime selection surfaces.
-- `frontmatter` names the Page Kit frontmatter fields the build should write or preserve.
+- `page_type` is the CPK runtime/analytics vocabulary (`product`, `checkout`, `upsell`, `receipt`), not the richer CampaignSpec or producer page type. CampaignSpec `select` and `checkout_step` pages project as CPK `checkout` because they render the SDK checkout surface ahead of the page that takes payment.
+- `frontmatter` names the Page Kit frontmatter fields the build should write or preserve. Beside `page_type`, `permalink`, `next_url` and `decline_url`, two keys wire multi-step checkout paths: `success_url`, on every page that leads into a Checkout (a `select` page, a `checkout_step`, or a landing page whose forward links reach one), is that Checkout's post-payment destination and feeds the page's `next-success-url` meta tag, which the SDK reads for express orders; `step_number`, on a `checkout_step` only, is its position on its path from 1, for the step form's `data-next-step-number`. The step form's `data-next-checkout-step` is the page's `next_url`.
 - `permalink_required` is true when Page Kit's filename-derived route would not match `public_route`.
 
+An entry page (`is_entry: true`) declares the campaign root when `page_url` is
+empty, `/`, `/<slug>/`, or `<slug>`.
+If Page Kit emits its mapped target file, or a materialised template-stock
+family page, at that file's route without a root output, doctor recognizes the
+built page and warns that the root is unserved. The warning names both routes:
+add a redirect from the root to the emitted route or set
+`permalink: /<slug>/` on the entry page, the campaign root as Page Kit emits it.
+It uses `campaign.route_root`: a root-served campaign names `/` and
+`/<file-route>/`; a slug-served campaign names `/<slug>/` and
+`/<slug>/<file-route>/`. The built files stay under `_site/<slug>/` in both cases.
+`qa resolve --packet campaign-runtime.build.json --base-url <preview-url>` then
+prints the locally emitted entry route. An explicit permalink on that entry's
+Page Kit source file takes precedence, even if stale output remains at the
+file route. Doctor still warns if that permalink serves a non-root route and
+the root output is absent. With no permalink, a root `index.html` takes
+precedence over the recorded file route; with a non-root permalink, a present
+root output suppresses the warning while QA keeps the permalink Entry URL.
+Another page's `index.html` cannot stand in for the entry.
+
 The Design Source Package should reference this projection without confusing it
 with Surface Identity. Surface Identity is the campaign-facing join key; Page Kit
 `page_type`, public routes, output paths, CampaignSpec/Map Builder page IDs,
@@ -1761,7 +1793,19 @@ prepare-build gate is set (`next` answers prepare-build) or while an earlier
 stage in the order below is not terminal. The exception is the one `next`
 makes: on the local preview, a polish doctor carries forward (never recorded
 for this build) does not hold `record deploy` back, as it does not hold `next`;
-polish stays owed and QA reports it.
+polish stays owed and QA reports it. If every mapped page is template stock on
+a hosted preview, doctor carries the same missing-evidence shape forward.
+`record deploy` remains local-only: record an unset hosted preview URL with
+`campaigns-os qa policy set --packet <p> --preview-url <url>`, then run
+`campaigns-os next --packet <p>`. The hosted preview must be a non-loopback
+HTTP(S) URL whose origin or QA-resolved campaign route path differs from `deploy.production_url`;
+query and fragment text does not make the production page a preview. With
+`deploy.preview_url` recorded, run `campaigns-os next qa --packet <p>` and
+`campaigns-os qa run --packet <p> --base-url <preview-url> --browser
+--test-order common`. The recorded hosted preview satisfies the deploy step
+for this all-template shape. After QA records a verdict for the current build,
+`campaigns-os next --packet <p>` reaches closeout without a hosted deploy
+record. QA against the packet's production URL retains the strict gate.
 
 Each command reads the same packet, Build Context and Assembly Report `next`
 reads (`--context` / `--report` override them the same way), validates what it
@@ -1791,7 +1835,7 @@ build` after every page-kit build; a rebuild that changes the output needs
 rebuilt output, `next` asks for QA again if the last QA record names the
 previous build fingerprint, even while its stage status still says completed.
 
-Stage order: `setup → build → polish → deploy → qa`. The picker walks this list and returns the first stage whose recorded status isn't terminal (`completed`, `completed_with_warnings`, `skipped`). During Polish, install the package-owned browser first, then run `campaigns-os polish capture` against the served current build before recording a terminal `stages.polish.status` or proceeding to deploy/QA; the producer attaches package-owned `visual_review.page_load` evidence and never marks the stage complete itself.
+Stage order: `setup → build → polish → deploy → qa`. The picker walks this list and returns the first stage whose recorded status isn't terminal (`completed`, `completed_with_warnings`, `skipped`), except that a carried-forward all-template hosted preview with a recorded `deploy.preview_url` satisfies deploy without a report record. During Polish, when a design route exists, install the package-owned browser first, then run `campaigns-os polish capture` against the served current build before recording a terminal `stages.polish.status` or proceeding to deploy/QA; the producer attaches package-owned `visual_review.page_load` evidence and never marks the stage complete itself. Template-stock campaigns with no design route have no capture to run and follow the preview policy above.
 
 | Stage | Report key | Owner |
 |---|---|---|
@@ -1824,7 +1868,7 @@ Result shape (with `--json`):
 Terminal states:
 
 - **`stage: "doctor-blocked"`** — doctor returned errors. Resolve the blockers and re-run `campaigns-os doctor` to confirm before calling `next` again.
-- **`stage: "done"`** — every stage is in a terminal status. Pipeline is complete. To repeat build work, do the work and use `record build`; it makes downstream stages owed as needed. Use `record setup` or `record polish` after repeating those stages, and `qa run` for QA. `record deploy` records a local-serve target; for a hosted deploy, record the URL and stage outcome as the deploy prompt describes. Then call `next` again.
+- **`stage: "done"`** — every stage is terminal, or a carried-forward all-template hosted preview satisfies deploy with a recorded `deploy.preview_url` and current-build QA verdict. Pipeline is complete. To repeat build work, do the work and use `record build`; it makes downstream stages owed as needed. Use `record setup` or `record polish` after repeating those stages, and `qa run` for QA. `record deploy` records a local-serve target; other hosted deploys record the URL and stage outcome as the deploy prompt describes. Then call `next` again.
 - **`stage_blocked: true`** — the picker returned a stage whose recorded status is `blocked`. Don't run the prompt as-is; clear the blocker first.
 
 The legacy form `campaigns-os next <stage>` (e.g. `next build`) still works and is the way to force a specific stage when you want to override the picker.

package/docs/local-setup.md

@@ -3,7 +3,7 @@
 For a new campaign, create an empty working folder and run this from it:
 
 ```sh
-npm init -y && npm install --save-exact next-campaign-page-kit@0.2.0 && npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.55.0 && npx --no-install campaigns-os tooling setup --target . --platform claude
+npm init -y && npm install --save-exact next-campaign-page-kit@0.2.0 && npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.57.0 && npx --no-install campaigns-os tooling setup --target . --platform claude
 ```
 
 `npm init -y` gives the folder its own `package.json`. Without one, npm

package/docs/orientation-contract-reference.md

@@ -26,7 +26,7 @@ Ledger schema id: `campaigns-os-release-ledger/v1`
 Change policy version: `1.0.0`  
 Reason-code vocabulary version: `1.0.0`  
 Limits version: `1.0.0`  
-Supported surface at generation time: `1.55.0`
+Supported surface at generation time: `1.57.0`
 
 ## Forward compatibility
 

package/docs/qa-and-test-orders.md

@@ -101,7 +101,7 @@ recapture. A hosted target (`netlify`, `cloudflare-pages`, …) is unaffected:
 its build stage renders production as before and `page-kit parity` refuses the
 packet (`local_proof.parity.not_local_serve`).
 
-### Missing evidence carried forward on the local preview
+### Missing evidence carried forward on previews
 
 On a `local-serve` packet served from a loopback host (`localhost`,
 `127.0.0.1`, `[::1]`, for both `deploy.preview_url` and `--base-url`), some
@@ -110,20 +110,28 @@ loop. The campaign must still prove its commerce there: store and campaign
 binding, routes, SDK loading, prices and a typed-card order. Only these
 checks are carried forward:
 
-| Check | When |
-| --- | --- |
-| `polish.evidence_missing`, `polish.report_missing` | Polish was never recorded for this build. |
-| `polish.hidden_eager_media.no_capturable_routes` | Every mapped page is template stock (`skip_reason`), so polish capture has no design route to capture. |
-| `polish.hidden_eager_media.capture_malformed` | Only when no page-load capture was recorded at all. |
-| Template-residue severity | With `theme_gate.nothing_generatable`, the starter template is the design, so residue findings are warnings rather than blockers. |
+| Check | Local loopback preview | Hosted preview |
+| --- | --- | --- |
+| `polish.evidence_missing`, `polish.report_missing` | Carried when Polish was never recorded. | Carried only with the all-template `no_capturable_routes` checkpoint. |
+| `polish.hidden_eager_media.no_capturable_routes` | Carried when every mapped page is template stock (`skip_reason`). | Carried when every mapped page is template stock and QA uses the packet's non-loopback `deploy.preview_url`, distinct from `deploy.production_url` by origin or QA-resolved campaign route path. |
+| `polish.hidden_eager_media.capture_malformed` | Carried only when no page-load capture was recorded at all. | Blocked. |
+| Template-residue severity | With `theme_gate.nothing_generatable`, residue findings warn. | Unchanged. |
 
 A carried-forward gate has status `carried_forward`. Doctor reports it as a
-warning starting "Carried forward on the local preview"; `next` moves past
-polish to deploy and QA; QA records it as a `warn` row, so the verdict is at
+warning starting "Carried forward on the local preview" or "Carried forward on the hosted preview"; `next` moves past
+polish to deploy and QA, and the recorded all-template hosted preview satisfies deploy without a deploy record; QA records it as a `warn` row, so the verdict is at
 best `ready_with_exceptions`. The evidence is reported as missing, never as
-passed. Any other check keeps its meaning. A hosted preview or production
-packet, and a `local-serve` packet served from any other host, gets the strict
-gates. `record polish` and the waiver commands also keep them strict. Progress
+passed. On a hosted all-template preview, first record an unset preview URL
+with `campaigns-os qa policy set --packet <packet> --preview-url <url>`, then
+run `campaigns-os next --packet <packet>`. Run `campaigns-os next qa --packet <packet>`
+then `campaigns-os qa run --packet <packet> --base-url <preview-url> --browser --test-order common` directly. After QA records the current-build verdict, run `campaigns-os next --packet <packet>` for closeout;
+`record deploy` only accepts loopback local-serve URLs; a pending hosted deploy
+record does not suppress these QA actions when the all-template checkpoint is
+carried forward. The hosted exception
+requires a distinct packet `deploy.preview_url`; a query or fragment on the production page does not count as distinct. QA with `--base-url` equal to
+the packet's `deploy.production_url` stays blocked. A `local-serve` packet
+served from any other host also gets strict gates. `record polish` and the
+waiver commands keep them strict. Progress
 snapshots record a carried-forward gate as `not_applicable`, because their
 schema has no carried-forward state.
 
@@ -179,8 +187,9 @@ line and the printed per-URL rows say which URLs those were rather than leaving
 an operator to infer it from `counts.unreachable`. It is `null` only when every
 probed URL resolved, or when nothing was probed at all.
 
-Resolve appends `campaign.public_route_slug` unconditionally — the packet is
-the authority on where a campaign is served, and no flag overrides it. When
+Resolve appends `campaign.public_route_slug` to the preview base for `base_url`
+and page URLs, including when `campaign.route_root` is `/`. A subpath on
+`--base-url` stays ahead of the slug. When
 every derived route is dead, one extra probe of the host without that slug
 separates the two causes and says which it found:
 `route_probe.route_root_mismatch` (the host serves the campaign under a
@@ -308,6 +317,21 @@ for that entry URL. If Entry URLs are empty, still point at a deleted preview, o
 fail their own HTTP assertion, fix `--base-url` or the packet deploy URL before
 continuing.
 
+For an `is_entry` page with `page_url` empty, `/`, `/<slug>/`, or `<slug>`, `qa resolve` uses that page's
+explicit Page Kit permalink first, then the campaign root when
+`_site/<slug>/index.html` exists. If neither applies and Page Kit emitted the
+entry at its recorded page-file route, the printed Entry URL uses that locally
+emitted route. Doctor warns that the Map still points at the unserved root;
+add a redirect from the root to the emitted route or set `permalink: /<slug>/`
+on the entry page. A non-root permalink also gets the warning when root output
+is absent; QA keeps that permalink as its Entry URL. A present root output
+suppresses the warning. The default
+probe checks the printed URL on the host. For either `campaign.route_root: "/"`
+or the default route root, the file route is joined under `base_url` as
+`/<slug>/<file-route>/` (after any preview subpath). The root output, when
+present, uses `base_url` itself. The route-root declaration still determines
+the public route named in doctor's unserved-root warning.
+
 `--base-url` can be either the deploy host or the campaign root. If the Build Packet says `campaign.public_route_slug = "roadside-ready"`, both of these resolve pages under `/roadside-ready/`:
 
 ```bash
@@ -1446,7 +1470,21 @@ timeout still leaves the ladder up to the point of failure. Ladder entries carry
 object. Evidence is resolved even when the step fails or times out, because the
 failing path is the one worth reading.
 
-Four steps write structured evidence today.
+Five steps write structured evidence today.
+
+**Multi-step checkout paths (campaigns-os#641).** The ladder drives the
+Checkout — the page that takes payment (`type: "checkout"`) — on the tested
+path, never the first page typed checkout. When `checkout_step` pages lead
+into it, the runner lands on the first step: through a `select` page ahead of
+it when there is one (`entered_via_landing` with `control_kind:
+checkout_button`), otherwise the step fills the cart itself.
+`customer_fields_filled` fills only the fields that step renders, one
+`checkout_step_submitted` rung per step follows, and the order is submitted
+only on the Checkout. With
+split-test paths in one campaign, each Checkout reached from an entry page is
+its own path; `tiers` plans read declared tiers and bumps from every page of
+that path (the select page or first step declares the cart), and coupons from
+its steps and Checkout.
 
 **`entered_via_landing` — cart entry.** The first rung of the ladder, before
 `opened_checkout`. A checkout renders its customer form whether or not the SDK
@@ -1490,7 +1528,13 @@ checkout — never a receipt or an offer page), navigates there, waits for the
 SDK, and clicks the cart-entry control: an SDK add-to-cart control
 (`[data-next-action="add-to-cart"]`, the only attribute the SDK activates the
 feature on), or a link into the checkout URL carrying `?forcePackageId=`,
-which is what the certified `shop-single-step` landing renders. A control
+which is what the certified `shop-single-step` landing renders, or, on a
+page with bundle cards (`[data-next-bundle-card]`, a `select` page), a checkout
+button: the SDK's `[data-next-action="checkout"]` or a plain link into the
+checkout URL. There the swap-mode selector already wrote the cart and the SDK
+persists it, so the runner keeps the pre-selected card, or with
+`--select-package <ref>` clicks the bundle card carrying that ref first,
+strictly, before the button. A control
 spelled any other way is not a cart entry, so a page that offers nothing else
 fails the step by name (`cart_entry_control_missing`) rather than clicking a
 control the SDK never wired and waiting out the navigation budget. A visible
@@ -1508,8 +1552,9 @@ cart away. `opened_checkout` then records the arrival instead of re-opening.
 
 Evidence: `landing_url`, `landing_page_id`, `landing_page_type`,
 `landing_resolution` (`routes_into_checkout`, `entry_page_fallback`,
-`first_page_fallback`), `control_text`, `control_kind` (`add_to_cart` or
-`checkout_link`), `package_id`, `sdk_ready`, `arrived_url`, the
+`first_page_fallback`), `control_text`, `control_kind` (`add_to_cart`,
+`checkout_link`, or `checkout_button`), `package_id`, `bundle_card_selection`
+when `--select-package` clicked a bundle card, `sdk_ready`, `arrived_url`, the
 `checkout_selection_surface` probe result, `selection_surface_probe`
 (`loaded`, `reused`, or `failed`), and `selection_surface_probe_error` when it
 failed. The failure codes are
@@ -1545,6 +1590,21 @@ own 30s default, so a caller-supplied budget only ever tightens the ceiling. A
 stuck required field fails as that field rather than as an anonymous step
 timeout; a slow-but-working funnel waits no longer than it did before.
 
+**`checkout_step_submitted` — one rung per `checkout_step`.** On a path whose
+Checkout is preceded by `checkout_step` pages, each step's rung checks the page
+is on that step, clicks the submit control of its
+`form[data-next-checkout-step]` (the SDK validates the step's fields, keeps the
+answers and navigates), and waits for the page to land on the step's declared
+next page (`expected_next_url`). It then fills whatever fields the arrived page
+renders. A step whose form carries no `data-next-checkout-step`, or whose
+submit never reaches the declared next page (usually a required field the
+step validates), fails the rung by name; nothing is reserved or submitted, so
+the creation classifier reads it as `not_created`. Evidence: `step_page_id`,
+`step_number`, `expected_next_url`, `arrived_url` and the arrived page's
+`fields` trace. A path that starts on its first step, with no page routing into
+it, skips `entered_via_landing`: the step page fills the cart and the guard
+before submit checks it.
+
 **`cart_created` — cart-API observation.** The step reports what the cart API
 actually returned: the most recent `POST /api/v1/carts/` response's `status`, an
 `ok` flag, `line_count` when the response body exposes lines, `response_count`,

package/docs/runtime-readiness.md

@@ -8,7 +8,7 @@
 
 How a checkout of this repository at one commit becomes a usable installed runtime, and how a consumer decides whether a prepared one is still trustworthy. Everything below is generated from `contracts/runtime-recipe.campaigns-os-node-v1.json`, which is the only authority for these values.
 
-Recipe kind `campaigns-os-node-v1`, revision `1.0.2`, validated by `schemas/campaigns-os-runtime-recipe.v1.schema.json` (`Campaigns OS Runtime Recipe v1`). Supported surface at generation time: `1.55.0`.
+Recipe kind `campaigns-os-node-v1`, revision `1.0.3`, validated by `schemas/campaigns-os-runtime-recipe.v1.schema.json` (`Campaigns OS Runtime Recipe v1`). Supported surface at generation time: `1.57.0`.
 
 ## What this is
 
@@ -81,9 +81,10 @@ Not redundant with the install step. Because install runs with lifecycle scripts
 
 The complete input set, enumerated explicitly rather than globbed. The compiler's configured include globs are NOT the input set: two root modules enter the compilation transitively through imports from the entry module and are emitted, so a fingerprint derived from the globs would cover 36 of the 38 compiled sources and miss one of the larger emitted surfaces. Test fixtures and the package's own tests are not inputs; nothing under them is emitted. A checker resolves the compiler's actual file list and asserts it equals this enumeration, so this list cannot rot silently.
 
-Fingerprint algorithm `sha256`, over 42 enumerated files:
+Fingerprint algorithm `sha256`, over 47 enumerated files:
 
 - `campaign-spec/analytics-vocabulary.ts`
+- `campaign-spec/checkout-flow.ts`
 - `campaign-spec/index.ts`
 - `campaign-spec/normalize.ts`
 - `campaign-spec/package.json`
@@ -91,7 +92,9 @@ Fingerprint algorithm `sha256`, over 42 enumerated files:
 - `campaign-spec/rules/analytics-contract-shape.ts`
 - `campaign-spec/rules/assembly-hints-shape.ts`
 - `campaign-spec/rules/campaign-metadata.ts`
+- `campaign-spec/rules/checkout-forward-target.ts`
 - `campaign-spec/rules/checkout-has-success-url.ts`
+- `campaign-spec/rules/checkout-step-reaches-checkout.ts`
 - `campaign-spec/rules/cycle-detection.ts`
 - `campaign-spec/rules/design-source-shape.ts`
 - `campaign-spec/rules/downsell-without-upsell.ts`
@@ -102,9 +105,11 @@ Fingerprint algorithm `sha256`, over 42 enumerated files:
 - `campaign-spec/rules/funnel-weight-sum.ts`
 - `campaign-spec/rules/index.ts`
 - `campaign-spec/rules/offer-ref-integrity.ts`
+- `campaign-spec/rules/one-checkout-per-path.ts`
 - `campaign-spec/rules/package-pricing-sanity.ts`
 - `campaign-spec/rules/page-count.ts`
 - `campaign-spec/rules/page-id-uniqueness.ts`
+- `campaign-spec/rules/pre-payment-forward-target.ts`
 - `campaign-spec/rules/promo-code-input-validation.ts`
 - `campaign-spec/rules/promo-codes-shape.ts`
 - `campaign-spec/rules/route-field-ignored-for-page-type.ts`
@@ -132,7 +137,7 @@ The output directory is a build product. It is untracked and git-ignored, no com
 
 Directory `campaign-spec/dist`. Committed: `false`. Type entry `campaign-spec/dist/index.d.ts`.
 
-Expected inventory is derived, never listed twice. For every enumerated input under module_source_root whose path ends in .ts, the build is expected to emit campaign-spec/dist/<path relative to module_source_root, with .ts replaced> once per entry in emitted_extensions. The expected inventory is exactly that set: nothing missing, nothing extra. Emitted extensions: `.js`, `.d.ts`. At this revision that derivation yields 76 files.
+Expected inventory is derived, never listed twice. For every enumerated input under module_source_root whose path ends in .ts, the build is expected to emit campaign-spec/dist/<path relative to module_source_root, with .ts replaced> once per entry in emitted_extensions. The expected inventory is exactly that set: nothing missing, nothing extra. Emitted extensions: `.js`, `.d.ts`. At this revision that derivation yields 86 files.
 
 ### Mandatory checks
 

package/docs/skills-revision.md

@@ -16,7 +16,7 @@ that the copy on disk moved.
 `skills.json` carries one top-level field:
 
 ```json
-"bundle_revision": "1.55.0+skills.1"
+"bundle_revision": "1.57.0+skills.1"
 ```
 
 The spelling is `<package version>+skills.<n>`:
@@ -25,7 +25,7 @@ The spelling is `<package version>+skills.<n>`:
   skills ship with (`check-skill-versions.mjs` fails if the two disagree);
 - `<n>` is a plain counter, not a semver component. It says "this is the *n*th
   skill-text revision published against that package version" and it **resets
-  with the prefix**. `1.55.0+skills.1` is therefore ahead of `1.40.0+skills.7`.
+  with the prefix**. `1.57.0+skills.1` is therefore ahead of `1.40.0+skills.7`.
 
 It is one identity for the bundle as a whole, on purpose. Per-skill versions
 still exist and still gate per-skill changes, but an agent that loaded one skill
@@ -37,7 +37,7 @@ The first body line of every bundled `SKILL.md`, immediately after the
 frontmatter, is exactly:
 
 ```
-Bundle revision: 1.55.0+skills.1
+Bundle revision: 1.57.0+skills.1
 ```
 
 followed by a short paragraph telling the agent to run the check below at the
@@ -48,7 +48,7 @@ text the agent is actually reading, not from a file it would have to go and open
 ## The check
 
 ```bash
-npx --no-install campaigns-os tooling status --skills-revision 1.55.0+skills.1
+npx --no-install campaigns-os tooling status --skills-revision 1.57.0+skills.1
 ```
 
 The value is compared against the bundle revision of the **CLI the command runs
@@ -90,20 +90,20 @@ reports the choice as `skills.scope` (`requested`, `installed_platforms`, or
 "revision_check": "match",
 "skills_revision": {
   "status": "match",
-  "requested": "1.55.0+skills.1",
+  "requested": "1.57.0+skills.1",
   "spelling": "bundle",
-  "on_disk": "1.55.0+skills.1",
+  "on_disk": "1.57.0+skills.1",
   "on_disk_skill": null,
-  "message": "match (1.55.0+skills.1)"
+  "message": "match (1.57.0+skills.1)"
 }
 ```
 
 The text view prints one named line, as a header above the rest of the status:
 
 ```
-Skills revision: match (1.55.0+skills.1)
-Skills revision: mismatch: loaded 1.39.0+skills.1, on disk 1.55.0+skills.1 — start a fresh session
-Skills revision: unchecked (on disk 1.55.0+skills.1)
+Skills revision: match (1.57.0+skills.1)
+Skills revision: mismatch: loaded 1.39.0+skills.1, on disk 1.57.0+skills.1 — start a fresh session
+Skills revision: unchecked (on disk 1.57.0+skills.1)
 ```
 
 `unchecked` is the state when the flag is absent. It is not an error — an

package/docs/supported-surface.md

@@ -13,7 +13,7 @@ implementation detail, however stable it looks.
 
 | Surface | Contract | Change discipline |
 |---|---|---|
-| `schemas/*.schema.json` (all of them) | The portable contract catalog: CampaignSpec, Design Source Package, Build Packet, Build Context, Assembly Report, Doctor Output, sidecar-bundle conformance, Run Record, Workflow Finding, Build Brief, Source-HTML Manifest, Tooling Orientation, Release Ledger, QA Verdict, the QA Verdict sidecar projection, Runtime Recipe, and the legacy-migration inventory/plan/receipt trio. | Hashed. Any content change requires updating the recorded hash **and** bumping `surface_version` in the same PR. A shape change that alters meaning gets a new schema-version const — one version identifier must never cover two shapes (the 2026-08 assembly-report drift is the incident this rule encodes). Additions to an open `v0` schema are expected and consumers must tolerate unknown fields; the security-sensitive legacy-migration schemas are closed, so additions there require a new lineage. 1.28.0 (RL entry `surface_version: 1.28.0`, breaking) removed the two required Build Packet booleans `qa.test_orders_allowed` and `qa.sandbox_test_card_confirmed` (nothing read them; test orders run from `--test-order <mode>` alone), added `local-serve` to the `deploy.target` enum, and added the optional `remit_result` / `remit_base_kind` fields to the Run Record. 1.30.0 (additive) added the optional `data_layer` record to the QA Verdict's `test_orders[]` entries — the order's `dl_purchase` reading (#325). 1.33.0 (additive) added the optional `qa_verdict_publish` block to the Run Record — which verdict was posted to the QA portal, by `qa run` or `qa publish`, and what the portal answered, in the `remit_result` vocabulary (#328). 1.55.0 (breaking) adds the optional publish decision `reason`, record `closed_by` closer, QA observation `verdict_run_id`, `build_fingerprint`, and `stale`, lifecycle `stages[].wait_ms` and `stages[].finding_codes`, and run-level `needs_input_count` and `failure_count` while removing the unused `agent_usage` field from the same v0 Run Record shape. |
+| `schemas/*.schema.json` (all of them) | The portable contract catalog: CampaignSpec, Design Source Package, Build Packet, Build Context, Assembly Report, Doctor Output, sidecar-bundle conformance, Run Record, Workflow Finding, Build Brief, Source-HTML Manifest, Tooling Orientation, Release Ledger, QA Verdict, the QA Verdict sidecar projection, Runtime Recipe, and the legacy-migration inventory/plan/receipt trio. | Hashed. Any content change requires updating the recorded hash **and** bumping `surface_version` in the same PR. A shape change that alters meaning gets a new schema-version const — one version identifier must never cover two shapes (the 2026-08 assembly-report drift is the incident this rule encodes). Additions to an open `v0` schema are expected and consumers must tolerate unknown fields; the security-sensitive legacy-migration schemas are closed, so additions there require a new lineage. 1.28.0 (RL entry `surface_version: 1.28.0`, breaking) removed the two required Build Packet booleans `qa.test_orders_allowed` and `qa.sandbox_test_card_confirmed` (nothing read them; test orders run from `--test-order <mode>` alone), added `local-serve` to the `deploy.target` enum, and added the optional `remit_result` / `remit_base_kind` fields to the Run Record. 1.30.0 (additive) added the optional `data_layer` record to the QA Verdict's `test_orders[]` entries — the order's `dl_purchase` reading (#325). 1.33.0 (additive) added the optional `qa_verdict_publish` block to the Run Record — which verdict was posted to the QA portal, by `qa run` or `qa publish`, and what the portal answered, in the `remit_result` vocabulary (#328). 1.55.0 (breaking) adds the optional publish decision `reason`, record `closed_by` closer, QA observation `verdict_run_id`, `build_fingerprint`, and `stale`, lifecycle `stages[].wait_ms` and `stages[].finding_codes`, and run-level `needs_input_count` and `failure_count` while removing the unused `agent_usage` field from the same v0 Run Record shape. 1.56.0 (breaking) adds `schemas/campaign-spec.v5.schema.json` (CampaignSpec `5.0`: the `checkout_step` page type, and `checkout` meaning the page that takes payment; 4.2/4.3 specs still validate against the v4 schema and are upgraded on read) and the `success_url` and `step_number` keys to the closed `page_kit.frontmatter` object of the Build Packet and Build Context v0 schemas, so a validator holding the 1.55.0 schemas refuses a packet that carries them (campaigns-os#641). |
 | CLI commands: `start`, `prepare-build`, `build`, `polish`, `checkpoint`, `page-kit`, `spec`, `doctor`, `bundle`, `next`, `theme`, `tooling`, `install-skills`, `install-agent-context`, `validate-assembly-report`, `telemetry`, `standardize`, `qa`, `findings`, `run-record`, `run`, `sdk`, `demo`, `login`, `logout` | Scriptable entry points. The founding list (1.0.0) was the argv surface Campaigns Agent's remit fixture pins; 1.25.0 adds the partner entry path the public guides instruct — `install-skills` (skill install), `tooling status` (preflight), `next --packet` (the runtime cursor) — plus `theme`, `install-agent-context`, `validate-assembly-report`, and `telemetry`, since consent is part of the partner contract. `validate-build-packet`, formerly an undocumented and unsupported alias of `doctor`, was removed in 1.25.0+agent.7 (RL-0036) and now gets the unknown-command error; use `doctor`. `standardization-report`, a supported but redundant second spelling of `standardize` — same flags, same output, same exit codes — was removed in 1.27.0 and now gets the same unknown-command error; use `standardize`. Removing a supported command is a breaking change and is why that release moved the minor. `bundle check` validates the canonical JSON readback set and makes QA required only under `--require-qa`. `polish capture` owns page-load evidence production. `checkpoint waive` currently accepts five registered gates: `page_kit.store_profile`, `page_kit.sdk_version`, `polish.hidden_eager_media`, `built_output.upsell_selector_scope`, and `source_html.producer_provenance` (per page, with `--page <page_id>`). `page-kit sync` (added in 1.29.0) writes the CampaignSpec's Store Profile fields and SDK pin into the target's `_data/campaigns.json` entry — the repair the first two gates name — and is the only `page-kit` subcommand. `spec derive` (added in 1.31.0) is the reverse write for the repo-derived field class (#432): the target's SDK pin, page routes and analytics ids into the packet's local CampaignSpec; it is the only `spec` subcommand, and the `page_kit.sdk_version.repo_newer` advisory names it; its `--write-map` flag (1.33.0+agent.2) also records the derived pin in the saved Map's Build hints field through the proxy Worker, never moving a Map pin backwards. `qa publish` (added in 1.33.0) posts an already-stored verdict to the QA portal without a re-run or an order, refusing a stale `spec_hash` or a verdict its Run Record already records as published (#328). Within Polish, only the broader Source Freshness waiver remains on its existing report lane; theme and QA decisions also retain their existing lanes. | Any change to this list — adding, renaming, or removing a command — bumps `surface_version` in the same PR, and since 1.25.0 `check-supported-surface.mjs --base` enforces that (before, only hashed and named entries owed a bump, so `checkpoint` landed unbumped). Subcommands, registered gates, and flags may grow freely beneath a listed command. Removing a listed command from dispatch fails the gate outright. Do not infer support for an unregistered checkpoint from the top-level command. |
 | `sdk storage-check` and `docs/sdk-storage-compatibility.md` | Read-only AST compatibility report for explicitly scoped tracked campaign HTML/JS before an SDK bump; consumes the supplied SDK-owned manifest and records its SHA-256 and verified or unverified local Git provenance. Incompatible and unknown findings exit 2; a clean scan is static source evidence only. | Additive supported CLI and named documentation; no automatic merchant integration repair. |
 | `sdk repin` | Rewrites the version segment of semver-pinned Campaign Cart loader.js / campaign-cart.css URLs in a static repo (no `_data/campaigns.json`) to a target version, default the SDK support policy's `preferred_minimum`. It previews by default. `--apply` writes the files and the change record `.campaign-runtime/sdk-repin.json` (`campaigns-os-sdk-repin/v0`). `@latest`, `@main`, commit and prerelease refs, and pins at or above the target, are reported and never rewritten. A page-kit repo is refused with exit 2. Usage is in `docs/sdk-storage-compatibility.md`. | Additive supported subcommand under the listed `sdk` command. It never changes anything in a URL except the version segment. |

package/docs/versioning.md

@@ -23,7 +23,10 @@ This repo uses independent compatibility versions:
 - QA Verdict sidecar projection: same `"1.0"` literal, projection guarantees in
   `schemas/campaigns-os-qa-verdict-sidecar.v0.schema.json` (one contract, two
   schema files — the sidecar is an allowlist projection, never a second lineage)
-- CampaignSpec: `4.2`–`4.3` (JSON Schema: `schemas/campaign-spec.v4.schema.json`)
+- CampaignSpec: `5.0` (JSON Schema: `schemas/campaign-spec.v5.schema.json`), with
+  `4.2`–`4.3` still read (`schemas/campaign-spec.v4.schema.json`) and upgraded on
+  read: each `checkout` page whose resolved forward target is another `checkout`
+  becomes `checkout_step`
 - starter-template agent contract: `1`
 - commerce surface catalog: `2`
 - Tooling Orientation: `campaigns-os-tooling-orientation/v1`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextcommerce/campaigns-os",
-  "version": "1.55.0",
+  "version": "1.57.0",
   "description": "Toolkit for agent-assisted NEXT campaign builds.",
   "license": "Apache-2.0",
   "repository": {
@@ -44,6 +44,7 @@
       "default": "./src/legacy-migration.mjs"
     },
     "./schemas/campaign-spec.v4.schema.json": "./schemas/campaign-spec.v4.schema.json",
+    "./schemas/campaign-spec.v5.schema.json": "./schemas/campaign-spec.v5.schema.json",
     "./schemas/campaigns-os-legacy-migration-inventory.v0.schema.json": "./schemas/campaigns-os-legacy-migration-inventory.v0.schema.json",
     "./schemas/campaigns-os-legacy-provisioning-plan.v0.schema.json": "./schemas/campaigns-os-legacy-provisioning-plan.v0.schema.json",
     "./schemas/campaigns-os-legacy-provisioning-receipt.v0.schema.json": "./schemas/campaigns-os-legacy-provisioning-receipt.v0.schema.json",

package/schemas/campaign-runtime-build-context.v0.schema.json

@@ -191,7 +191,9 @@
                   },
                   "permalink": { "type": "string", "minLength": 1 },
                   "next_url": { "type": "string", "minLength": 1 },
-                  "decline_url": { "type": "string", "minLength": 1 }
+                  "decline_url": { "type": "string", "minLength": 1 },
+                  "success_url": { "type": "string", "minLength": 1, "description": "On a page that leads into a Checkout (select, checkout_step, or a landing page whose forward links reach one): that Checkout's post-payment destination, for the next-success-url meta tag the SDK reads for express orders. Never the next step (campaigns-os#641)." },
+                  "step_number": { "type": "integer", "minimum": 1, "description": "On a checkout_step page: its position among its path's steps, from 1, for the step form's data-next-step-number." }
                 }
               }
             },

package/schemas/campaign-runtime-build-packet.v0.schema.json

@@ -193,7 +193,9 @@
                       },
                       "permalink": { "type": "string", "minLength": 1 },
                       "next_url": { "type": "string", "minLength": 1 },
-                      "decline_url": { "type": "string", "minLength": 1 }
+                      "decline_url": { "type": "string", "minLength": 1 },
+                      "success_url": { "type": "string", "minLength": 1, "description": "On a page that leads into a Checkout (select, checkout_step, or a landing page whose forward links reach one): that Checkout's post-payment destination, for the next-success-url meta tag the SDK reads for express orders. Never the next step (campaigns-os#641)." },
+                      "step_number": { "type": "integer", "minimum": 1, "description": "On a checkout_step page: its position among its path's steps, from 1, for the step form's data-next-step-number." }
                     }
                   }
                 },