@nextcommerce/campaigns-os 1.34.1 → 1.37.1

package/skills/next-campaigns-os/SKILL.md

@@ -1,11 +1,27 @@
 ---
 name: next-campaigns-os
-version: 1.0.16
+version: 1.0.17
 description: Coordinate Campaigns OS lifecycle workflows from CampaignSpec, Build Packet, starter-template contracts, stage reports, deploy evidence, and QA proof depth.
 ---
 
 # Campaigns OS
 
+## Installed toolkit commands
+
+Run from the campaign folder with an exact project-local devDependency and
+committed lockfile. Orient on reviewed source before installation; check release
+provenance or pin the full reviewed Git SHA. Preflight with `npx campaigns-os
+tooling status --platform <claude|codex>` and refresh bundled skills for the same
+profile. Use the invocation printed by status and `next` to avoid PATH shadowing.
+
+In the instructions below, bare `campaigns-os …` means `npx campaigns-os …`
+from that campaign folder. Global-only users substitute the global copy's printed invocation for
+each `npx campaigns-os` example; toolkit contributors translate to `npm run campaigns-os -- …` in
+the toolkit checkout. Browser installation is `npx campaigns-os qa
+install-browser`, not a campaign npm script. `tooling diagnose --packet <p>
+--json` provides a redacted support export without changing retained evidence.
+
+
 Use this skill to orient a campaign build, run preflight, decide the next stage, and keep the lifecycle honest.
 
 ## Public Lifecycle Boundary
@@ -32,7 +48,7 @@ Workflow:
 7. If doctor's `next` block says `doctor-blocked` or `prepare-build` (it names the same stage `campaigns-os next` would), stop and resolve the named blockers.
 8. If doctor returns `build`, hand off with `campaigns-os next build --packet <packet>` and follow `next-campaigns-build`'s recommended **build → independent review → repair → verification** loop.
 9. After build, require polish and a preview deploy before QA. During Polish,
-   install the package-owned browser once with `npm run qa:install-browser`,
+   install the package-owned browser once with `npx campaigns-os qa install-browser`,
    serve the current build, and run `campaigns-os polish capture --packet <p> --base-url <served-build-url>` before recording a terminal Polish status.
    The package-owned producer attaches `visual_review.page_load`; never
    hand-author it. Nonwaivable incomplete evidence blocks. A complete hidden
@@ -41,7 +57,7 @@ Workflow:
    Doctor/next report `ready_with_waivers`; QA
    retains each attributed exception as `ready_with_exceptions`, and one
    exception never suppresses another blocker.
-10. Run the package-owned proof path in sequence: ensure `npm run qa:install-browser` has completed, run `campaigns-os qa resolve --packet <packet>`, then `campaigns-os qa run --packet <packet> --base-url <url> --browser --test-order common`.
+10. Run the package-owned proof path in sequence: ensure `npx campaigns-os qa install-browser` has completed, run `campaigns-os qa resolve --packet <packet>`, then `campaigns-os qa run --packet <packet> --base-url <url> --browser --test-order common`.
 11. Treat typed-card proof coverage as the control. Global test cards bypass the gateway and create no transactions, so no permission/approval is needed. `common` runs checkout, first-offer accept and decline, and a deduplicated shortest real receipt path when that adds coverage (at most four orders). `full` walks every actual terminal path in the selected checkout topology; cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. The accidental-flood cap remains `6`, and an overflow names the exact explicit `--max-test-orders` raise. Localhost on any port is a Campaigns App Development domain for SDK QA with analytics suppressed; non-localhost preview/production origins still need SDK origin allowlist confirmation.
 12. Discuss launch only from recorded build, polish, deploy, browser QA, and test-order evidence, or from explicit blockers.
 

package/skills/next-campaigns-os-setup/SKILL.md

@@ -1,11 +1,27 @@
 ---
 name: next-campaigns-os-setup
-version: 2.0.0
+version: 2.0.1
 description: Bootstrap or prepare a target page-kit campaign repo from a doctor-cleared Campaigns OS Build Packet before full build wiring. Formerly installed as next-campaigns-setup; renamed 2026-08 to stop colliding with the published NextCommerceCo/skills scaffolder of that name.
 ---
 
 # Next Campaigns OS Setup
 
+## Installed toolkit commands
+
+Run from the campaign folder with an exact project-local devDependency and
+committed lockfile. Orient on reviewed source before installation; check release
+provenance or pin the full reviewed Git SHA. Preflight with `npx campaigns-os
+tooling status --platform <claude|codex>` and refresh bundled skills for the same
+profile. Use the invocation printed by status and `next` to avoid PATH shadowing.
+
+In the instructions below, bare `campaigns-os …` means `npx campaigns-os …`
+from that campaign folder. Global-only users substitute the global copy's printed invocation for
+each `npx campaigns-os` example; toolkit contributors translate to `npm run campaigns-os -- …` in
+the toolkit checkout. Browser installation is `npx campaigns-os qa
+install-browser`, not a campaign npm script. `tooling diagnose --packet <p>
+--json` provides a redacted support export without changing retained evidence.
+
+
 Use this skill when the Build Packet doctor says setup is required before assembly.
 
 Responsibilities:

package/skills/next-campaigns-polish/SKILL.md

@@ -1,11 +1,27 @@
 ---
 name: next-campaigns-polish
-version: 1.1.1
+version: 1.1.2
 description: Run the visual/runtime polish pass after build and before QA for a Campaigns OS campaign.
 ---
 
 # Next Campaigns Polish
 
+## Installed toolkit commands
+
+Run from the campaign folder with an exact project-local devDependency and
+committed lockfile. Orient on reviewed source before installation; check release
+provenance or pin the full reviewed Git SHA. Preflight with `npx campaigns-os
+tooling status --platform <claude|codex>` and refresh bundled skills for the same
+profile. Use the invocation printed by status and `next` to avoid PATH shadowing.
+
+In the instructions below, bare `campaigns-os …` means `npx campaigns-os …`
+from that campaign folder. Global-only users substitute the global copy's printed invocation for
+each `npx campaigns-os` example; toolkit contributors translate to `npm run campaigns-os -- …` in
+the toolkit checkout. Browser installation is `npx campaigns-os qa
+install-browser`, not a campaign npm script. `tooling diagnose --packet <p>
+--json` provides a redacted support export without changing retained evidence.
+
+
 Use this after build has produced a runnable page-kit campaign.
 
 Theme gate: `campaigns-os next polish` blocks when theme inspect found a
@@ -33,7 +49,7 @@ Responsibilities:
 - For exit-intent pops and promo-code inputs, polish the wrapper/copy states without breaking SDK coupon/voucher apply hooks or `cart.hasCoupon("CODE")` conditional labels.
 - If `report.theme` or `context.theme` exists, verify brand-theme load order after `next-core.css`, source-token parity for primary color/CTA/surface/text/font/radius when present, and SDK safety. When the brand layer is missing, stale, low-confidence, or unsafe to apply, record the first repair-loop defect or an explicit skipped reason.
 - Before recording a terminal Polish status, install the package-owned browser
-  once with `npm run qa:install-browser`, serve the current build, and run
+  once with `npx campaigns-os qa install-browser`, serve the current build, and run
   `campaigns-os polish capture --packet <packet> --base-url <served-build-url>`.
   The package captures every mapped route at fixed desktop/mobile viewports and
   attaches `stages.polish.evidence.visual_review.page_load`. Never hand-author,

package/skills/next-campaigns-qa/SKILL.md

@@ -1,26 +1,42 @@
 ---
 name: next-campaigns-qa
-version: 1.3.1
+version: 1.3.2
 description: Run spec-aware QA from a Campaign Map ID and tested campaign URL after build, polish, and deploy/local evidence exist, including Playwright typed-card test-order proof.
 ---
 
 # Next Campaigns QA
 
+## Installed toolkit commands
+
+Run from the campaign folder with an exact project-local devDependency and
+committed lockfile. Orient on reviewed source before installation; check release
+provenance or pin the full reviewed Git SHA. Preflight with `npx campaigns-os
+tooling status --platform <claude|codex>` and refresh bundled skills for the same
+profile. Use the invocation printed by status and `next` to avoid PATH shadowing.
+
+In the instructions below, bare `campaigns-os …` means `npx campaigns-os …`
+from that campaign folder. Global-only users substitute the global copy's printed invocation for
+each `npx campaigns-os` example; toolkit contributors translate to `npm run campaigns-os -- …` in
+the toolkit checkout. Browser installation is `npx campaigns-os qa
+install-browser`, not a campaign npm script. `tooling diagnose --packet <p>
+--json` provides a redacted support export without changing retained evidence.
+
+
 Use this after the campaign has a preview or production URL and the assembly report records build and polish status. The public v0 runner is Node/npm-based, with an owned Playwright browser pass:
 
 ```bash
-npm run qa:install-browser
-npm run campaigns-os -- qa resolve --packet campaign-runtime.build.json
-npm run campaigns-os -- qa run --packet campaign-runtime.build.json --base-url <preview-url>
+npx campaigns-os qa install-browser
+npx campaigns-os qa resolve --packet campaign-runtime.build.json
+npx campaigns-os qa run --packet campaign-runtime.build.json --base-url <preview-url>
 # Fixture-driven migration parity proof. Publishes to the QA portal by default.
-npm run campaigns-os -- qa parity --fixture <parity-fixture.json> --scenario <scenario-id> --base-url <preview-url>
+npx campaigns-os qa parity --fixture <parity-fixture.json> --scenario <scenario-id> --base-url <preview-url>
 # Browser QA + typed-card proof. Publishes to the QA portal by default and prints the portal link.
-npm run campaigns-os -- qa run --packet campaign-runtime.build.json --base-url <preview-url> --browser --test-order common
+npx campaigns-os qa run --packet campaign-runtime.build.json --base-url <preview-url> --browser --test-order common
 # Offline / dev / CI only: keep the verdict local
-npm run campaigns-os -- qa run --packet campaign-runtime.build.json --base-url <preview-url> --browser --test-order common --no-post-verdict
+npx campaigns-os qa run --packet campaign-runtime.build.json --base-url <preview-url> --browser --test-order common --no-post-verdict
 ```
 
-`npm run qa:install-browser` is part of the standard QA sequence. Run it once
+`npx campaigns-os qa install-browser` is part of the standard QA sequence. Run it once
 after install/update before using `--browser` or `--test-order`; do not skip it
 unless the local Playwright browser binary is already installed.
 

package/skills.json

@@ -15,7 +15,7 @@
     {
       "id": "next-campaigns-os",
       "name": "Campaigns OS Lifecycle",
-      "version": "1.0.16",
+      "version": "1.0.17",
       "path": "skills/next-campaigns-os/SKILL.md",
       "domain": "campaigns",
       "description": "Coordinate Campaigns OS lifecycle workflows from CampaignSpec, Build Packet, starter-template contracts, stage reports, deploy evidence, and QA proof depth."
@@ -23,7 +23,7 @@
     {
       "id": "next-campaigns-os-setup",
       "name": "Campaigns OS Setup",
-      "version": "2.0.0",
+      "version": "2.0.1",
       "path": "skills/next-campaigns-os-setup/SKILL.md",
       "domain": "campaigns",
       "description": "Bootstrap or prepare a target page-kit campaign repo from a doctor-cleared Campaigns OS Build Packet before full build wiring. Formerly next-campaigns-setup; renamed to release that name to the published NextCommerceCo/skills scaffolder."
@@ -31,7 +31,7 @@
     {
       "id": "next-campaigns-build",
       "name": "Campaign Build",
-      "version": "1.0.2",
+      "version": "1.0.3",
       "path": "skills/next-campaigns-build/SKILL.md",
       "domain": "campaigns",
       "description": "Assemble a NEXT campaign from a doctor-cleared Build Packet, CampaignSpec/API values, prepared HTML/assets, page-kit, and starter-template contracts."
@@ -39,7 +39,7 @@
     {
       "id": "next-campaigns-polish",
       "name": "Campaign Polish",
-      "version": "1.1.1",
+      "version": "1.1.2",
       "path": "skills/next-campaigns-polish/SKILL.md",
       "domain": "campaigns",
       "description": "Run the visual/runtime polish pass after build and before QA for a Campaigns OS campaign."
@@ -47,7 +47,7 @@
     {
       "id": "next-campaigns-qa",
       "name": "Campaign QA",
-      "version": "1.3.1",
+      "version": "1.3.2",
       "path": "skills/next-campaigns-qa/SKILL.md",
       "domain": "campaigns",
       "description": "Run spec-aware QA from a Campaign Map ID and tested campaign URL after build, polish, and deploy/local evidence exist, including Playwright typed-card test-order proof."

package/src/cli.mjs

@@ -1,5 +1,6 @@
 import { withHtmlScanSnapshot, readHtmlScanText, htmlScanDigest } from "./html-scan.mjs";
 import { createHash, randomUUID } from "node:crypto";
+import { createDemo, demoArguments } from "./demo.mjs";
 import { execFileSync } from "node:child_process";
 import {
   accessSync,
@@ -22,6 +23,8 @@ import { homedir } from "node:os";
 import { basename, delimiter, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { shellToken } from "./shell-token.mjs";
+import { diagnosticExport, diagnosticTextLines } from "./diagnostic.mjs";
+import { observeProgress, PROGRESS_OBSERVATION } from "./progress-node.mjs";
 import { describeSdkIgnoredMetaTags, isSdkIgnoredMetaTag } from "./sdk-meta-tags.mjs";
 import { HIDDEN_EAGER_MEDIA_ACTIONS, requiredActionText, substitutePacket } from "./gate-actions.mjs";
 import { ORDER_PATH_DEPTH_DRIFT_CODE, orderPathDepthDriftText, orderPathDepthReconcileAction, orderPathDepthsDisagree, parseOrderPathDepthFlag } from "./proof-policy.mjs";
@@ -444,6 +447,7 @@ const HELP = `Campaigns OS toolkit
 
 Usage:
   campaigns-os help
+  campaigns-os demo --target <new-directory>   # offline inert sample; open landing/index.html; no campaign evidence
   campaigns-os start (--spec <json> | --map-id <id>) --source <html-dir> --target <page-kit-dir> --template-family <family>
                      [--brief <yaml|json>] [--proxy-base <url>] [--cached-spec] [--theme-policy <inspect_only|auto|off>]
                      [--wrapper-policy <strip_document_wrappers|preserve_document_wrappers|not_required|unknown>] [--design-manifest <path>]
@@ -472,8 +476,9 @@ Usage:
   campaigns-os validate-assembly-report --report <json> [--json]
   campaigns-os install-skills [--platform <claude|codex|agents|all>] [--target <skills-dir>] [--dry-run] [--json]
   campaigns-os tooling status [--platform <claude|codex|agents|all>] [--target <skills-dir>] [--json]   # install-mode (checkout or pinned package), git, and skill freshness preflight
+  campaigns-os tooling diagnose [--packet <packet>] [--platform <claude|codex|agents|all>] [--json]   # read-only redacted support summary
   campaigns-os install-agent-context --target <page-kit-dir> [--dry-run]
-  campaigns-os next --packet <json> [--json]                       # self-decide next stage; returns gates[] + next_actions[] (exact commands) alongside the prompt
+  campaigns-os next --packet <json> [--no-write] [--no-remit] [--proxy-base <url>] [--json]                       # self-decide next stage; returns gates[] + next_actions[] (exact commands) alongside the prompt
   campaigns-os next setup --packet <json> [--context <json>] [--report <json>] [--json]
   campaigns-os next build --packet <json> [--context <json>] [--report <json>] [--json]
   campaigns-os next polish --packet <json> --report <json> [--json]
@@ -598,6 +603,24 @@ export async function main(argv) {
   if (args._[0] === "campaigns-os") args._.shift();
   const command = args._[0] || "help";
 
+  // An offline sample must not recover sessions or emit lifecycle evidence.
+  if (command === "demo") {
+    // Validate raw tokens here: parsing loses duplicate flags. The private
+    // dispatcher then rechecks the parsed shape and extracts the target.
+    demoArguments(args, argv);
+    await dispatch(command, args);
+    return;
+  }
+
+  // Diagnostic export is an inspection, including when a run is active or
+  // stale. Bypass session sweeping, ambient resolution, and lifecycle capture
+  // so no closeout/remit or journal write can occur before the projection.
+  if (command === "tooling" && args._[1] === "diagnose") {
+    const result = toolingDiagnose(args);
+    console.log(args.json ? JSON.stringify(result, null, 2) : diagnosticTextLines(result).join("\n"));
+    return;
+  }
+
   // Ambient run session (Tier 3): when `run start` is active, every command
   // shares its run_id WITHOUT --run-id. Explicit --run-id still wins. Resolved
   // ONCE here and threaded through dispatch + persistence so the run_id a
@@ -1010,6 +1033,17 @@ const PREPARE_MODES = Object.freeze({
 });
 
 async function dispatch(command, args, recorder = NOOP_RECORDER, ambient = null, sessionHolder = null) {
+  if (command === "demo") {
+    // main() already validated raw argv before entering this private function.
+    const target = demoArguments(args);
+    if (target === null) {
+      console.log("campaigns-os demo --target <new-directory>\nOffline Apollo sample only. Open the printed landing/index.html file. Start a real campaign in a separate new Page Kit folder; preserve your sample edits.");
+      return;
+    }
+    const result = createDemo(target);
+    console.log(`Offline sample only; no campaign evidence.\nOpen: ${result.index}\nStart a real campaign in a separate new Page Kit folder. Preserve sample edits; demo is never converted automatically.`);
+    return;
+  }
   if (command === "help" || (args.help && command !== "qa")) {
     console.log(HELP);
     return;
@@ -1171,6 +1205,7 @@ async function dispatch(command, args, recorder = NOOP_RECORDER, ambient = null,
     // explicit stage (`next build`, `next polish`, etc.) is unchanged.
     const stage = args._[1] || null;
     const result = nextStage(stage, args, ambient);
+    await observeProgress(args, result, { packageVersion: packageVersion(), resolveKey: resolveCampaignsApiKeySource });
     writeResult(result, args, result.ok ? 0 : 2);
     printNextTinyPrompt(result, args);
     return;
@@ -1182,7 +1217,14 @@ async function dispatch(command, args, recorder = NOOP_RECORDER, ambient = null,
     // command a QA run prints has to agree with the run_id this session will
     // later close and remit under.
     const result = await runQaCli(args, { ambient });
-    if (args._[1] === "run" && result?.verdict) recordQaStageOutcome(args, result);
+    if (args._[1] === "run" && result?.verdict && recordQaStageOutcome(args, result)) {
+      // Observe committed QA before the existing closeout; this cannot close
+      // a run or change the QA disposition. Reuse the canonical picker.
+      try {
+        const continuation = nextStage(null, { ...args, "no-write": true }, null);
+        await observeProgress(args, continuation, { qaResult: result, packageVersion: packageVersion(), resolveKey: resolveCampaignsApiKeySource });
+      } catch { /* optional progress never changes lifecycle closeout */ }
+    }
     if (sessionHolder) sessionHolder.qaResult = result;
     return;
   }
@@ -1327,7 +1369,10 @@ async function resolveSpecPath(args, opts = {}) {
     const spec = await fetchSpecByMapId(mapId, { proxyBase, fetchImpl: opts.fetchImpl });
     mkdirSync(cacheDir, { recursive: true });
     writeFileSync(cachePath, `${JSON.stringify(spec, null, 2)}\n`);
-    return { specPath: cachePath, source: "remote", mapId, proxyBase };
+    return { specPath: cachePath, source: "remote", mapId, proxyBase,
+      savedMapRevision: { map_id: mapId, hash: spec.spec_identity?.spec_hash || spec.spec_hash || null,
+        algorithm: "map-store-v1", local_spec_material_hash: specMaterialHash(spec) },
+    };
   }
   throw new Error(
     "Either --spec <path> or --map-id <id> is required. " +
@@ -2478,6 +2523,7 @@ function prepareBuild(args, options = {}) {
       : null,
     map_id: specInput?.mapId || null,
     proxy_base: specInput?.proxyBase || null,
+    saved_map_revision: specInput?.savedMapRevision || null,
     source_root: portable(sourceRoot),
     target_repo: portable(targetRepo),
     template_family: explicitTemplateFamily || null,
@@ -9500,6 +9546,10 @@ export function nextStage(stage, args, ambient = null) {
     runRecordCloseout = null;
   }
   const finalize = (result) => {
+    Object.defineProperty(result, PROGRESS_OBSERVATION, { value: {
+      workspace: { packet, packetPath, targetRepo, contextPath, reportPath },
+      context: readJsonIfExists(contextPath), report, doctor,
+    } });
     if (divergences.length) result.divergences = divergences;
     result.gates = buildNextGates({ doctor, report, themeGate, polishGate, prepareBuildGate, packetPath });
     result.next_actions = buildNextActions({ result, packetPath, packet, themeGate, polishGate, polishCheckpointGate, prepareBuildGate, ambient, runRecordCloseout, purchaseProof, brandContract: doctor.derived?.brand_contract || null, context: readJsonIfExists(contextPath), targetRepo });
@@ -10917,7 +10967,9 @@ function toolingCommand(args) {
   } else if (install.mode !== "checkout" && cli.global_binary.status === "found_other_install") {
     // An npx cache is ephemeral: never tell the operator to put its .bin on
     // PATH. The pinned npx form is what makes the inspected copy run.
-    warnings.push(install.mode === "npx_cache"
+    warnings.push(install.mode === "global"
+      ? `The campaigns-os on PATH is a different install; use \`${cli.invocation_prefix} <command>\` to run the global copy inspected here.`
+      : install.mode === "npx_cache"
       ? `The campaigns-os on PATH (${cli.global_binary.path}) is a different install from the one inspected here (${install.location}); bare commands would run that other copy. Use \`${cli.invocation_prefix} <command>\` so the pinned copy runs.`
       : cli.bin_dir
         ? `The campaigns-os on PATH (${cli.global_binary.path}) is a different install from the one inspected here (${cli.local_bin}); bare commands would run that other copy. Run export PATH="${cli.bin_dir}:$PATH" to put this install first.`
@@ -10948,6 +11000,24 @@ function toolingCommand(args) {
   };
 }
 
+export function toolingDiagnose(args, { runTooling = toolingCommand, runDoctor = doctorCommand } = {}) {
+  let tooling = null;
+  let doctor = null;
+  let inspectionFailed = false;
+  const platform = args.platform || "all";
+  // Inputs are used only by local producers, never echoed, and mutation flags
+  // are not forwarded. Even an exception's message may contain a secret path.
+  try {
+    tooling = runTooling({ _: ["tooling", "status"], platform, ...(typeof args.target === "string" ? { target: args.target } : {}) });
+  } catch { /* unavailable, no raw producer exception in a support export */ }
+  if (args.packet !== undefined) {
+    try {
+      doctor = runDoctor({ packet: args.packet, "no-write": true, ...(typeof args.context === "string" ? { context: args.context } : {}), ...(typeof args.report === "string" ? { report: args.report } : {}) });
+    } catch { inspectionFailed = true; }
+  }
+  return diagnosticExport({ tooling, doctor, platform, inspectionFailed });
+}
+
 function localCliStatus(pkg, install = { mode: "checkout", pinned: null }) {
   const resolved = resolveInvocation(ROOT, pkg, install);
   return {

package/src/consent.mjs

@@ -298,7 +298,7 @@ let defaultOnAnnounced = false;
 export function announceDefaultOnTelemetry(endpoint, { write = (line) => process.stderr.write(line) } = {}) {
   if (defaultOnAnnounced) return false;
   defaultOnAnnounced = true;
-  write(`[campaigns-os] Run telemetry is ON by default: anonymized run records are sent to ${endpoint || CANONICAL_REMIT_SCOPE} to improve templates, tooling, and guidance. Disable with \`campaigns-os telemetry off\` or CAMPAIGNS_OS_TELEMETRY=off.\n`);
+  write(`[campaigns-os] Run telemetry is ON by default: anonymized run records and minimal stage observations are sent to ${endpoint || CANONICAL_REMIT_SCOPE} to improve templates, tooling, and guidance; stage observations support Workspace progress. Disable with \`campaigns-os telemetry off\` or CAMPAIGNS_OS_TELEMETRY=off.\n`);
   return true;
 }
 
@@ -338,7 +338,7 @@ export async function promptAndPersistConsent({
   if (!isTTY) return { state: "off", source: "default", resolved: false, prompted: false };
 
   const answer = await ask(
-    "Campaigns OS can send build telemetry to Next Commerce to improve templates, tools, and guidance. Share telemetry from this machine? [Y/n] (change any time): ",
+    "Campaigns OS can send build telemetry and minimal stage observations to Next Commerce to improve templates, tools, and guidance; stage observations support Workspace progress. Share telemetry from this machine? [Y/n] (change any time): ",
   );
   const normalized = String(answer || "").trim().toLowerCase();
   const state = (normalized === "" || ["y", "yes", "1", "true", "on"].includes(normalized)) ? "on" : "off";

package/src/demo-artifact.mjs

@@ -0,0 +1,97 @@
+// Validator for the one reviewed bundled projection; never a general sanitizer.
+import {readFileSync,readdirSync,lstatSync} from 'node:fs';
+import {createHash} from 'node:crypto';
+import {join,posix} from 'node:path';
+import {parse,parseFragment} from 'parse5';
+export const DEMO_ROUTES=['landing','checkout','upsell-bundle-stepper','receipt'];
+export const DEMO_CSP="default-src 'none'; img-src 'self'; style-src 'self' 'unsafe-inline'; font-src 'self'; form-action 'none'; base-uri 'none'; connect-src 'none'; frame-src 'none'; object-src 'none'";
+const digest=bytes=>`sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+const allowedPath=name=>/^[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_.-]+)*\.(?:html|css|svg|png|jpe?g|webp|gif|woff2?|txt|json)$/.test(name)&&!name.split('/').some(part=>part==='.'||part==='..');
+const image=name=>/\.(?:svg|png|jpe?g|webp|gif)$/.test(name);
+const inactiveTags=new Set(['script','iframe','frame','frameset','object','embed','base','form','noscript','template','foreignobject','animate','animatetransform','animatemotion','set','audio','video']);
+const resourceAttrs=new Set(['href','xlink:href','src','srcset','poster','data','action','formaction','ping','background','manifest','profile','codebase','archive','dynsrc','lowsrc','srcdoc']);
+function localReference(value,from,files,{fragment=false}={}) {
+  if(fragment&&/^#[A-Za-z_][A-Za-z0-9_.:-]*$/.test(value))return null;
+  if(typeof value!=='string'||!value||/[\\%?#\s\u0000-\u001f]/.test(value)||value.startsWith('/')||/^[A-Za-z][A-Za-z0-9+.-]*:/.test(value))throw Error('demo.resource_invalid');
+  const target=posix.normalize(posix.join(posix.dirname(from),value));
+  if(!allowedPath(target)||!files.has(target))throw Error('demo.resource_missing');
+  return target;
+}
+function cssText(text,from,files) {
+  // Decode CSS escapes before inspecting resource constructs, including escaped
+  // identifiers. This projection has no imports, image-set or active behavior.
+  const decoded=text.replace(/\\([0-9a-f]{1,6})(?:\r\n|[\t\n\r\f ])?/gi,(_,hex)=>String.fromCodePoint(Math.min(parseInt(hex,16)||0xfffd,0x10ffff))).replace(/\\([^\n\r\f])/g,'$1').replace(/\/\*[\s\S]*?\*\//g,'');
+  if(/@import\b|\b(?:image-set|expression|element)\s*\(|-moz-binding|behavior\s*:/i.test(decoded))throw Error('demo.css_active');
+  for(const match of decoded.matchAll(/url\s*\(\s*([^)]*)\)/gi)) {
+    let value=match[1].trim();if(/^(['"])[\s\S]*\1$/.test(value))value=value.slice(1,-1);
+    const target=localReference(value,from,files,{fragment:true});
+    if(target&&!image(target)&&!/\.woff2?$/.test(target))throw Error('demo.css_resource_invalid');
+  }
+  if((decoded.match(/url\s*\(/gi)||[]).length!==[...decoded.matchAll(/url\s*\(\s*([^)]*)\)/gi)].length)throw Error('demo.css_invalid');
+}
+function markup(text,from,files,{svg=false}={}) {
+  if(svg&&(/<!doctype/i.test(text)||/<\?(?!xml(?:\s|\?))/i.test(text)))throw Error('demo.svg_document_active');
+  const document=svg?parseFragment(text):parse(text);let head=null,banner=false,nav=0,csp=0;
+  function visit(node) {
+    const tag=node.tagName?.toLowerCase();const attrs=Object.fromEntries((node.attrs||[]).map(attr=>[attr.prefix?`${attr.prefix}:${attr.name}`:attr.name,attr.value]));
+    if(inactiveTags.has(tag)||node.content)throw Error('demo.markup_active');
+    if(tag==='head')head=node;
+    if(attrs.role==='button'&&attrs['aria-disabled']!=='true')throw Error('demo.control_active');
+    if(tag==='aside'&&attrs['data-demo-banner']==='true')banner=true;
+    if(['button','input','select','textarea'].includes(tag)&&!Object.hasOwn(attrs,'disabled'))throw Error('demo.control_active');
+    for(const [name,value] of Object.entries(attrs)) {
+      if(/^on/i.test(name)||/^data-next-|^os-checkout-|^next-/.test(name))throw Error('demo.attribute_active');
+      if(name==='style')cssText(value,from,files);
+      if(!resourceAttrs.has(name))continue;
+      let target;
+      if(tag==='a'&&name==='href'&&attrs['data-demo-nav']==='true') {
+        target=localReference(value,from,files);if(!DEMO_ROUTES.some(route=>target===`${route}/index.html`))throw Error('demo.navigation_invalid');nav++;
+      }else if(tag==='link'&&name==='href'&&attrs.rel==='stylesheet') {
+        target=localReference(value,from,files);if(!target.endsWith('.css'))throw Error('demo.stylesheet_invalid');
+      }else if(tag==='img'&&name==='src') {
+        target=localReference(value,from,files);if(!image(target))throw Error('demo.image_invalid');
+      }else if(['use','image'].includes(tag)&&['href','xlink:href'].includes(name)) {
+        target=localReference(value,from,files,{fragment:true});if(target&&!image(target))throw Error('demo.svg_reference_invalid');
+      }else throw Error('demo.resource_attribute_invalid');
+    }
+    if(tag==='meta'&&Object.hasOwn(attrs,'http-equiv')) {
+      if(attrs['http-equiv'].toLowerCase()!=='content-security-policy'||attrs.content!==DEMO_CSP)throw Error('demo.policy_invalid');csp++;
+    }
+    if(tag==='style')cssText((node.childNodes||[]).map(child=>child.value||'').join(''),from,files);
+    for(const child of node.childNodes||[])visit(child);
+  }
+  visit(document);
+  if(!svg) {
+    const first=(head?.childNodes||[]).find(node=>node.tagName);
+    if(csp!==1||first?.tagName!=='meta'||!banner||nav!==4)throw Error('demo.shell_invalid');
+  }
+}
+export function validateDemoArtifact(root) {
+  const files=new Map();let total=0;
+  function collect(dir,prefix='') {
+    for(const name of readdirSync(dir).sort()) {
+      const path=join(dir,name),stat=lstatSync(path),relative=prefix?`${prefix}/${name}`:name;
+      if(stat.isSymbolicLink())throw Error('demo.symlink_invalid');
+      if(stat.isDirectory()){if(!/^[A-Za-z0-9_-]+$/.test(name))throw Error('demo.path_invalid');collect(path,relative);continue;}
+      if(!stat.isFile()||!allowedPath(relative)||stat.size>2097152||(total+=stat.size)>8388608||files.size>=256)throw Error('demo.file_invalid');
+      files.set(relative,readFileSync(path));
+    }
+  }
+  collect(root);
+  const provenance=JSON.parse(files.get('provenance.json')?.toString()||'null');
+  if(provenance?.schema_version!=='campaigns-os-inert-demo/v0'||provenance.template_commit!=='11352c30c596db258679fd3a552b906086b11bb9'||provenance.page_kit_version!=='0.2.0'||provenance.tailwind_version!=='3.4.17'||JSON.stringify(provenance.routes)!==JSON.stringify(DEMO_ROUTES))throw Error('demo.provenance_invalid');
+  const expected=provenance.output_hashes;
+  const provenanceFields=['schema_version','template_commit','page_kit_version','page_kit_commit','tailwind_version','routes','typography','input_hashes','toolchain_lock_hash','output_hashes'];
+  if(Object.keys(provenance).length!==provenanceFields.length||Object.keys(provenance).some(name=>!provenanceFields.includes(name))||provenance.page_kit_commit!=='eed0679b1d02ef5cbe7f21964165c4202724d91d'||provenance.typography!=='system-ui, sans-serif'||!/^sha256:[0-9a-f]{64}$/.test(provenance.toolchain_lock_hash)||!provenance.input_hashes||Object.keys(provenance.input_hashes).length>256||Object.entries(provenance.input_hashes).some(([name,value])=>!/^(?:src\/explore|rendered|_data)\/[A-Za-z0-9_./-]+$/.test(name)||name.split('/').includes('..')||!/^sha256:[0-9a-f]{64}$/.test(value)))throw Error('demo.provenance_invalid');
+  if(!expected||Object.keys(expected).length!==files.size-1||Object.keys(expected).some(name=>!files.has(name)||name==='provenance.json'))throw Error('demo.manifest_invalid');
+  for(const [name,bytes] of files) {
+    if(name!=='provenance.json'&&expected[name]!==digest(bytes))throw Error('demo.digest_mismatch');
+    if(name.endsWith('.html')){if(!DEMO_ROUTES.some(route=>name===`${route}/index.html`))throw Error('demo.route_invalid');markup(bytes.toString(),name,files);}
+    if(name.endsWith('.svg'))markup(bytes.toString(),name,files,{svg:true});
+    if(name.endsWith('.css'))cssText(bytes.toString(),name,files);
+    if(name.endsWith('.json')&&name!=='provenance.json')throw Error('demo.json_invalid');
+  }
+  for(const route of DEMO_ROUTES)if(!files.has(`${route}/index.html`))throw Error('demo.route_missing');
+  if(!files.has('NOTICE.txt'))throw Error('demo.notice_missing');
+  return {files,provenance,totalBytes:total};
+}

package/src/demo.mjs

@@ -0,0 +1,85 @@
+import { mkdirSync, openSync, fstatSync, lstatSync, writeFileSync, closeSync, unlinkSync, rmdirSync, realpathSync } from "node:fs";
+import { resolve, dirname, basename, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { validateDemoArtifact } from "./demo-artifact.mjs";
+
+const BUNDLE = fileURLToPath(new URL("../demo/apollo-v0", import.meta.url));
+const TARGET_CHANGED_MESSAGE = "demo.target_changed: destination changed during copy; inspect and preserve its files, then retry with a different new directory";
+const same = (left, right) => left.dev === right.dev && left.ino === right.ino;
+function owns(path, stat) {
+  try { const current = lstatSync(path); return !current.isSymbolicLink() && same(current, stat); } catch { return false; }
+}
+
+export function resolveDemoTarget(target, { resolveParent = realpathSync } = {}) {
+  if (typeof target !== "string" || !target.trim()) throw Error("demo.target_required: use --target <new-directory>");
+  const destination = resolve(target), name = basename(destination);
+  if (!name) throw Error("demo.target_invalid: choose a new directory below an existing parent");
+  return join(resolveParent(dirname(destination)), name);
+}
+
+// Exclusive creation only. Failure cleanup removes precisely the entries this
+// invocation created, and never recursively removes a caller's directory.
+export function createDemo(target, { bundle = BUNDLE, writeBytes = writeFileSync } = {}) {
+  if (typeof target !== "string" || !target.trim()) throw Error("demo.target_required: use --target <new-directory>");
+  const artifact = validateDemoArtifact(bundle);
+  // Resolve the existing parent once; mkdir remains exclusive at the final
+  // component, so an existing directory, file or symlink cannot be overwritten.
+  const root = resolveDemoTarget(target);
+  const directories = [], files = [];
+  function directory(path) {
+    mkdirSync(path);
+    const stat = lstatSync(path);
+    directories.push({ path, stat });
+    return stat;
+  }
+  let rootStat;
+  try { rootStat = directory(root); } catch (error) {
+    if (error.code === "EEXIST") throw Error("demo.target_exists: choose a new directory; demo never merges or overwrites");
+    throw error;
+  }
+  const created = new Map([[root, rootStat]]);
+  try {
+    for (const [name, bytes] of artifact.files) {
+      const path = join(root, name);
+      const parts = name.split("/"); parts.pop();
+      let current = root;
+      for (const part of parts) {
+        if (!owns(current, created.get(current))) throw Error(TARGET_CHANGED_MESSAGE);
+        current = join(current, part);
+        if (!created.has(current)) created.set(current, directory(current));
+      }
+      if (!owns(current, created.get(current))) throw Error(TARGET_CHANGED_MESSAGE);
+      const fd = openSync(path, "wx");
+      try {
+        files.push({ path, stat: fstatSync(fd) });
+        writeBytes(fd, bytes);
+      } finally { closeSync(fd); }
+    }
+  } catch (error) {
+    for (const entry of files.reverse()) if (owns(entry.path, entry.stat)) { try { unlinkSync(entry.path); } catch {} }
+    for (const entry of directories.reverse()) if (owns(entry.path, entry.stat)) { try { rmdirSync(entry.path); } catch {} }
+    throw error;
+  }
+  return { index: join(root, "landing", "index.html"), files: artifact.files.size };
+}
+
+export function demoArguments(args, argv = null) {
+  if (argv) {
+    const tokens = argv[0] === "campaigns-os" ? argv.slice(1) : argv;
+    const seen = new Set();
+    for (let index = 1; index < tokens.length; index++) {
+      const flag = tokens[index];
+      if (!["--target", "--help"].includes(flag) || seen.has(flag)) throw Error("demo.unsupported_arguments: only one --target and --help are supported");
+      seen.add(flag);
+      if (flag === "--target") {
+        if (!tokens[index + 1] || tokens[index + 1].startsWith("--")) throw Error("demo.target_required: use --target <new-directory>");
+        index++;
+      }
+    }
+  }
+  const unsupported = Object.keys(args).filter(name => !["_", "target", "help"].includes(name));
+  if (unsupported.length || args._.length !== 1 || (args.help !== undefined && args.help !== true)) throw Error("demo.unsupported_arguments: supported usage is demo --target <new-directory> or demo --help; no-write and dry-run are unsupported");
+  if (args.help) return null;
+  if (typeof args.target !== "string" || !args.target.trim()) throw Error("demo.target_required: use --target <new-directory>");
+  return args.target;
+}