@bongos/core 1.20.61 → 1.20.62

package/docs/recipes/upgrading-the-core.md

@@ -90,7 +90,7 @@ The sections above are the *manual* `bongos upgrade`. The **subscription** runs
 
 A **major** is never automatic; prereleases are never auto-targeted.
 
-**Where the channel comes from** ([ADR 0357](../adr/0357-the-update-rule-set-on-deploy-is-the-one-the-sweep-follows.md), task [1004468](https://cloudbongos.com/builders#/task/1004468)): the rule set on **/deploy** (`provisioning_instances.update_channel`) wins for any roster entry whose `slug` matches a project row. The roster's `channel` below is only the fallback, used when no row matches or the sweep can't read the database. The sweep reads the control plane's DB from its own `DATABASE_URL` / `PGDATABASE`, so the unit needs one of them set. Every run prints each entry's channel and its source.
+**Where the channel comes from** ([ADR 0357](../adr/0357-the-update-rule-set-on-deploy-is-the-one-the-sweep-follows.md), task [1004468](https://cloudbongos.com/builders#/task/1004468)): the rule set on **/deploy** (`provisioning_instances.update_channel`) wins for any roster entry whose `slug` matches a project row. The roster's `channel` below is only the fallback, used when no row matches or the sweep can't read the database. The sweep reads the control plane's DB from `UPDATE_CHANNEL_DB` (a db name or connection string), else `DATABASE_URL` / `PGDATABASE`. On a control plane, set `UPDATE_CHANNEL_DB`, never `PGDATABASE`: the sweep's env reaches every upgrade it spawns, so a tenant entry with no database of its own would migrate against the control plane's. Every run prints each entry's channel and its source.
 
 **Enrolling an instance** — add it to `config/update-subscriptions.json` (instance-side) (ships empty). `env` carries per-instance vars merged into the upgrade child — set `PGDATABASE` so `migrate` hits the right DB (see the Gotchas):
 
@@ -118,6 +118,35 @@ Each subscribed instance: read its installed core → ask the registry (`npm vie
 
 **Triple-gated, so nothing moves by accident:** the `core-update-subscription` routine is `requiresAutonomy: true` + **default OFF** in [`config/scheduled-routines.json`](../../config/scheduled-routines.json), the roster ships empty, and every upgrade is health-gated. Arm it by enabling the routine's timer on the control plane once autonomy is on.
 
+#### Run the sweep from the installed core (task 1004307)
+
+The sweep's body is `scripts/gds/update-sweep.js`, which ships in every core release.
+`.claude/scheduled-tasks/core-update-subscription/subscribe.js` is only a shim. A control plane
+should run the body **straight from the core it installs**, so each upgrade brings the next sweep
+current code. A sweep run from a checkout is only as new as that checkout, and on cloudbongos.com
+one sat frozen for a month while every fix to the lane went inert. The roster stays where it is;
+`--instance` names it.
+
+```ini
+# /etc/systemd/system/<instance>-core-update-subscription.service.d/run-from-core.conf
+[Service]
+ExecStart=
+ExecStart=/usr/bin/node <served-root>/node_modules/@bongos/core/scripts/gds/update-sweep.js --apply --instance <roster-root>
+Environment=UPDATE_CHANNEL_DB=<control-plane-db>
+```
+
+`<served-root>` is the root the sweep keeps current (the roster entry for the control plane itself);
+`<roster-root>` is where `config/update-subscriptions.json` lives. Prove it with a dry run as the
+unit's user before restarting anything. Its first line names the core doing the sweeping, and each
+entry's line names its channel and source:
+
+```bash
+sudo -u <user> env UPDATE_CHANNEL_DB=<control-plane-db> node <served-root>/node_modules/@bongos/core/scripts/gds/update-sweep.js --instance <roster-root>
+```
+
+Every run prints `update-sweep · running from <core dir> (core <version>) · roster <root>`, so
+`journalctl -u <instance>-core-update-subscription.service` answers "is the box running current code?".
+
 #### How often it sweeps — the lag knob (task 1003674)
 
 **This timer's period IS the delay between a builder's merge and the live site

package/modules/provisioning/demo.js

@@ -0,0 +1,176 @@
+'use strict';
+
+// modules/provisioning/demo.js — THE DEMO ROUTE: training wheels, a soft time box, and
+// "keep your planet?" (task 1004420 / BV2.PS09, goal 1000121; spec
+// docs/specs/bongos-v2-project-startup.md D3 + D9; design of record
+// docs/design/mocks/project-startup/DemoSetup|DemoReady|DemoKeep.dc.html).
+//
+// A DEMO IS A NORMAL PROJECT MARKED "DEMO" (D9). It is created by the same POST
+// /provisioning/instances as any project, with one more field, and it builds in the
+// normal hall. What makes it a demo is the `demo` jsonb column (provisioning_035):
+//   { people, hours_each, started_at, ends_at, outcome, settled_at, warned_at, offline_at }
+// and the defaults the demo picks for its founder: Monarchy / BDFL is already every new
+// project's government (the government module's default board), so the demo adds only
+// "no rewards" and "all managed" as answers (`detail`), and "private to the team" as
+// settings (the map door closed, joinable by invite only). Everyone uses their own AI
+// plan, which is how every project already works.
+//
+// THE TIME BOX IS SOFT (D3). `ends_at` is the start plus the hours each person said they
+// have, and it only ever drives a countdown and the "keep your planet?" question. Nothing
+// reads it to block or freeze work.
+//
+// A DEMO NOBODY KEEPS GOES OFFLINE AFTER 30 DAYS (D9). The demo-archive poller takes
+// it offline through the existing teardown path, so it is restorable the way any
+// torn-down project is ("bring it back"), with the repo, database and backups kept. The
+// owner is told first: its own project page shows the date from the start, and from
+// three days before it says plainly that the demo is about to go offline. "Carry it over" makes it a real project and the clock never applies again;
+// "keep it as a demo" settles the question but leaves the 30-day rule in place.
+//
+// No route or SQL lives here beyond the small reads and writes the demo needs, so the
+// two oversized files (provisioning.js, routes/provisioning.js) each gain a line, not a
+// feature.
+
+const DEMO_LIMITS = Object.freeze({ people: Object.freeze([1, 12]), hours_each: Object.freeze([1, 40]) });
+const DEMO_OFFLINE_DAYS = 30;
+const DEMO_WARN_DAYS = 3;
+const DAY_MS = 86400000;
+// The demo's picked answers (DemoReady): no rewards, all managed by Bongos. An owner's
+// own answer to either always wins.
+const DEMO_DETAIL = Object.freeze({ reward_intents: Object.freeze([]), framing: 'managed' });
+// Private to the team: off the public map, and joinable by invite only.
+const DEMO_SETTINGS = Object.freeze({ visibility: 'private', joinability: 'invite_only' });
+const OUTCOMES = Object.freeze(['carried', 'kept']);
+
+const intIn = (v, [lo, hi]) => Number.isInteger(v) && v >= lo && v <= hi;
+
+// parseDemo(raw) — PURE. The create request's `demo` field, or why it is refused.
+function parseDemo(raw) {
+  if (raw === undefined || raw === null) return { ok: true, demo: null };
+  if (typeof raw !== 'object' || Array.isArray(raw)) return { ok: false, reason: 'demo must be an object: { people, hours_each }.' };
+  const extra = Object.keys(raw).filter((k) => !['people', 'hours_each'].includes(k));
+  if (extra.length) return { ok: false, reason: `Unknown demo field "${extra[0]}": a demo takes people and hours_each.` };
+  if (!intIn(raw.people, DEMO_LIMITS.people)) return { ok: false, reason: 'people is a whole number from 1 to 12, you included.' };
+  if (!intIn(raw.hours_each, DEMO_LIMITS.hours_each)) return { ok: false, reason: 'hours_each is a whole number from 1 to 40.' };
+  return { ok: true, demo: { people: raw.people, hours_each: raw.hours_each } };
+}
+
+// fitCheck(people, hours) — PURE. The setup screen's first read: builder-hours and what
+// fits in them. The wizard carries a copy of these sentences, held equal by test.
+function fitCheck(people, hours) {
+  const total = people * hours;
+  const verdict = total < 8 ? 'tight' : total < 20 ? 'small' : 'plenty';
+  const sentence = {
+    tight: 'Too tight for this idea. Try one list with voting only, or add hours.',
+    small: 'Enough for a small version. Trim it to one shared list, voting and a winner reveal; accounts and notifications will not fit.',
+    plenty: 'Plenty for this idea, with room for one extra feature.',
+  }[verdict];
+  return { total, verdict, sentence };
+}
+
+// withDemoDetail(detail) — PURE. The demo's picked answers under the owner's own.
+function withDemoDetail(detail) {
+  const own = detail && typeof detail === 'object' && !Array.isArray(detail) ? detail : {};
+  return { ...DEMO_DETAIL, reward_intents: [], ...own };
+}
+
+// demoRecord(demo, now) — PURE. What the column holds at the start.
+function demoRecord(demo, now = new Date()) {
+  return {
+    people: demo.people,
+    hours_each: demo.hours_each,
+    started_at: now.toISOString(),
+    ends_at: new Date(now.getTime() + demo.hours_each * 3600000).toISOString(),
+    outcome: null,
+  };
+}
+
+const ms = (v) => { const t = v ? new Date(v).getTime() : NaN; return Number.isFinite(t) ? t : NaN; };
+
+// demoView(row, now) — PURE. The demo as an owner read shows it, or null for a project
+// that is not one (or was carried over: it is a real project now).
+function demoView(row, now = new Date()) {
+  const d = row && row.demo;
+  if (!d || typeof d !== 'object' || d.outcome === 'carried') return null;
+  const start = ms(d.started_at);
+  const end = ms(d.ends_at);
+  if (!Number.isFinite(start) || !Number.isFinite(end)) return null;
+  const offline = start + DEMO_OFFLINE_DAYS * DAY_MS;
+  return {
+    people: d.people,
+    hours_each: d.hours_each,
+    builder_hours: fitCheck(d.people, d.hours_each).total,
+    started_at: d.started_at,
+    ends_at: d.ends_at,
+    remaining_seconds: Math.max(0, Math.round((end - now.getTime()) / 1000)),
+    time_up: now.getTime() >= end,
+    outcome: OUTCOMES.includes(d.outcome) ? d.outcome : null,
+    offline_on: new Date(offline).toISOString(),
+    offline_soon: now.getTime() >= offline - DEMO_WARN_DAYS * DAY_MS,
+  };
+}
+
+// The writes. `db` is the pool (or a client); every write is one statement on the row.
+async function startDemo(db, instanceId, demo, now = new Date()) {
+  await db.query('UPDATE provisioning_instances SET demo = $2::jsonb WHERE id = $1', [instanceId, JSON.stringify(demoRecord(demo, now))]);
+}
+
+// startDemoProject — right after the create files a demo's row: mark it, and make it
+// private to the team. Returns the updated row, so the catalog projection that follows
+// sees the closed door rather than the public default for a moment. `provisioning` is
+// passed in (this file must not require it: provisioning.js requires this one).
+async function startDemoProject(db, provisioning, instanceId, demo, now = new Date()) {
+  await startDemo(db, instanceId, demo, now);
+  return provisioning.updateInstanceSettings(db, instanceId, { ...DEMO_SETTINGS });
+}
+
+// settleDemo — the "keep your planet?" answer. Carry it over: the marker's outcome says
+// so and the project is a real one from here on. Keep it as a demo: the question is
+// settled and the 30-day rule still applies. Answered once; a second answer is refused.
+async function settleDemo(db, inst, outcome, now = new Date()) {
+  if (!OUTCOMES.includes(outcome)) return { ok: false, reason: 'bad_outcome' };
+  const d = inst && inst.demo;
+  if (!d || typeof d !== 'object') return { ok: false, reason: 'not_a_demo' };
+  if (d.outcome) return { ok: false, reason: 'already_settled' };
+  const next = { ...d, outcome, settled_at: now.toISOString() };
+  await db.query('UPDATE provisioning_instances SET demo = $2::jsonb WHERE id = $1', [inst.id, JSON.stringify(next)]);
+  return { ok: true, demo: next };
+}
+
+// sweepDemos — the demo-archive poller's tick. For every demo nobody carried over that
+// is still up: stamp the warning three days before (the project page says it is about to go),
+// and at 30 days take it offline through the existing teardown path.
+async function sweepDemos(db, { enqueueTeardown, recordEvent, now = new Date() } = {}) {
+  const { rows } = await db.query(
+    `SELECT id, owner_builder_id, demo, status FROM provisioning_instances
+      WHERE demo IS NOT NULL
+        AND COALESCE(demo->>'outcome', '') <> 'carried'
+        AND demo->>'offline_at' IS NULL
+        AND status NOT IN ('tearing_down', 'torn_down')`,
+  );
+  const out = { warned: 0, offline: 0 };
+  for (const row of rows) {
+    const start = ms(row.demo.started_at);
+    if (!Number.isFinite(start)) continue;
+    const offlineAt = start + DEMO_OFFLINE_DAYS * DAY_MS;
+    if (now.getTime() >= offlineAt) {
+      await enqueueTeardown(db, row.id, null);
+      const next = { ...row.demo, offline_at: now.toISOString() };
+      await db.query('UPDATE provisioning_instances SET demo = $2::jsonb WHERE id = $1', [row.id, JSON.stringify(next)]);
+      if (recordEvent) {
+        await recordEvent(db, { instanceId: row.id, ownerBuilderId: row.owner_builder_id, event: 'demo-offline',
+          detail: { days: DEMO_OFFLINE_DAYS }, actor: 'system:demo-archive' }).catch(() => {});
+      }
+      out.offline += 1;
+    } else if (now.getTime() >= offlineAt - DEMO_WARN_DAYS * DAY_MS && !row.demo.warned_at) {
+      const next = { ...row.demo, warned_at: now.toISOString() };
+      await db.query('UPDATE provisioning_instances SET demo = $2::jsonb WHERE id = $1', [row.id, JSON.stringify(next)]);
+      out.warned += 1;
+    }
+  }
+  return out;
+}
+
+module.exports = {
+  DEMO_LIMITS, DEMO_OFFLINE_DAYS, DEMO_WARN_DAYS, DEMO_DETAIL, DEMO_SETTINGS, OUTCOMES,
+  parseDemo, fitCheck, withDemoDetail, demoRecord, demoView, startDemo, startDemoProject, settleDemo, sweepDemos,
+};

package/modules/provisioning/migrations/provisioning_035_demo.sql

@@ -0,0 +1,26 @@
+-- provisioning_035_demo.sql — the demo marker on a project (task 1004420, BV2.PS09; goal
+-- 1000121, spec docs/specs/bongos-v2-project-startup.md D3 + D9).
+--
+-- WHY THIS EXISTS. The front door's "Try the demo" route creates a normal project marked
+-- "demo" (D9): a small team tries Bongos in a few hours and keeps what they made. The mark
+-- has to live on the project row, because the hub reads it for the countdown and the
+-- "keep your planet?" question, and the demo-archive poller reads it to take a demo
+-- nobody kept offline after 30 days.
+--
+-- WHAT IT ADDS.
+--   provisioning_instances.demo — NULL for every ordinary project. For a demo:
+--     { people, hours_each, started_at, ends_at, outcome, settled_at, warned_at, offline_at }
+--     written at create (modules/provisioning/demo.js demoRecord), then by the "keep your
+--     planet?" answer (outcome 'carried' | 'kept') and by the poller (warned_at, offline_at).
+--
+-- A column and not a `detail` key: detail is what the OWNER said, editable and
+-- un-answerable by them; this is platform state an owner must not be able to erase to
+-- dodge the archive. Nullable, no backfill: no project before this was a demo.
+--
+-- Additive and namespaced (ADR 0083): no down-migration, idempotent — safe to re-run.
+
+BEGIN;
+
+ALTER TABLE provisioning_instances ADD COLUMN IF NOT EXISTS demo jsonb;
+
+COMMIT;

package/modules/provisioning/module.json

@@ -1,7 +1,7 @@
 {
   "key": "provisioning",
   "title": "Instance provisioning",
-  "description": "Stand up + operate a Cloud Bongos instance's own infrastructure (server, database, domain, DNS, TLS) via the API, so an owner does not manage infra by hand (ADR 0111). Owns the web-tier REQUEST + STATE surface only: it enqueues provisioning intents + reads instance state \u2014 it holds NO cloud-provider tokens and calls NO cloud API. A separate control-plane runner (scripts/gds/provision.js, task P3) is the sole token-holder that drains the intents. Distinct from the `hosting` module (ADR 0092), which brokers compute WORKLOADS.",
+  "description": "Stand up + operate a Cloud Bongos instance's own infrastructure (server, database, domain, DNS, TLS) via the API, so an owner does not manage infra by hand (ADR 0111). Owns the web-tier REQUEST + STATE surface only: it enqueues provisioning intents + reads instance state — it holds NO cloud-provider tokens and calls NO cloud API. A separate control-plane runner (scripts/gds/provision.js, task P3) is the sole token-holder that drains the intents. Distinct from the `hosting` module (ADR 0092), which brokers compute WORKLOADS.",
   "version": "1.0.0",
   "coreVersion": "^1.14.0",
   "default": false,
@@ -20,13 +20,15 @@
       "env-manifest",
       "repo-private",
       "render-standup",
-      "look"
+      "look",
+      "demo"
     ],
     "migrations": true,
     "pollers": [
       "liveness-sweep",
       "catalog-backfill",
-      "app-liveness"
+      "app-liveness",
+      "demo-archive"
     ]
   },
   "provides": [

package/modules/provisioning/pollers/demo-archive.js

@@ -0,0 +1,61 @@
+'use strict';
+
+// modules/provisioning/pollers/demo-archive.js — a demo nobody kept goes offline after 30
+// days, and its owner is told first (task 1004420, BV2.PS09; spec D9).
+//
+// One sweep an hour over the demo-marked projects (demo.js sweepDemos): from three days
+// before, a demo carries its offline date on its own card (the warning); at 30 days it is
+// taken offline through the existing teardown intent, so it is restorable the way any
+// torn-down project is. A demo carried over is a real project and is never swept.
+// Kill-switched by PROVISIONING_DEMO_ARCHIVE_DISABLED=1; the liveness sweep's shape
+// (self-rescheduling, jittered, unref'd, idempotent start).
+
+const api = require('../../../src/module-api');
+const provisioning = require('../provisioning');
+const demo = require('../demo');
+
+const log = api.logger('provisioning');
+
+const INTERVAL_MS = 60 * 60 * 1000;
+const FIRST_SWEEP_DELAY_MS = 5 * 60 * 1000;
+const JITTER_MS = 5 * 60 * 1000;
+
+let started = false;
+let timer = null;
+
+async function sweepOnce(deps = {}) {
+  const db = deps.pool || api.pool;
+  const out = await demo.sweepDemos(db, {
+    enqueueTeardown: deps.enqueueTeardown || provisioning.enqueueTeardown,
+    recordEvent: deps.recordEvent || provisioning.recordEvent,
+    now: deps.now,
+  });
+  if (out.warned || out.offline) log.info(`[demo-archive] warned ${out.warned}, took ${out.offline} offline`);
+  return out;
+}
+
+function arm(deps, delay) {
+  timer = setTimeout(() => {
+    sweepOnce(deps)
+      .catch((e) => log.error(`[demo-archive] sweep crashed: ${e && e.message ? e.message : e}`))
+      .then(() => { if (started) arm(deps, INTERVAL_MS + Math.floor(Math.random() * JITTER_MS)); });
+  }, delay);
+  if (timer.unref) timer.unref();
+}
+
+function start(deps = {}) {
+  if (process.env.PROVISIONING_DEMO_ARCHIVE_DISABLED === '1') {
+    log.info('[demo-archive] disabled (PROVISIONING_DEMO_ARCHIVE_DISABLED=1)');
+    return;
+  }
+  if (started) return;
+  started = true;
+  arm(deps, FIRST_SWEEP_DELAY_MS);
+}
+
+function stop() {
+  started = false;
+  if (timer) { clearTimeout(timer); timer = null; }
+}
+
+module.exports = { start, stop, sweepOnce, INTERVAL_MS };

package/modules/provisioning/provisioning.js

@@ -23,7 +23,7 @@ const { normalizeModuleSelection, effectiveModules } = require('./starter-bundle
 // pure declarations beside this file, for the same reason: storage and the read
 // projection both have to read them.
 const { PLANET_PHYSICS_QUESTIONS, canonicalAnswer } = require('./planet-physics');
-const { softLimitsFor } = require('./soft-limits');
+const { softLimitsFor } = require('./soft-limits'); const { demoView } = require('./demo');   // the demo marker's owner view (task 1004420)
 const { LOOK_SETTINGS_VOCAB, LOOK_DEFAULTS, LOOK_COMPANION_ENV } = require('./look');
 
 // ---------------------------------------------------------------------------
@@ -450,7 +450,7 @@ function publicInstance(row) {
     detail,
     // Which startup options those answers hide, grey or annotate, each with its reason
     // (BV2.PS02, spec D6). Advice only — `enforced: false` says so on every read.
-    soft_limits: softLimitsFor(detail),
+    soft_limits: softLimitsFor(detail), demo: demoView(row),   // null unless a demo nobody carried over (task 1004420, ./demo.js)
     // The creation picker's module set (task 1002339): the always-on core, what
     // the owner ends up with, and whether that came from their own toggles or
     // from the type's starter bundle because they never answered. Resolved, not

package/modules/provisioning/routes/demo.js

@@ -0,0 +1,54 @@
+'use strict';
+
+// modules/provisioning/routes/demo.js — "keep your planet?" (task 1004420, BV2.PS09).
+//
+// POST /provisioning/instances/:id/demo { outcome: 'carried' | 'kept' } — the owner's
+// answer at the end of a demo. Carried over: the project is a real one from here on, and
+// the 30-day archive never applies. Kept as a demo: settled, and the archive still does.
+// The demo itself is started by the ordinary create (POST /provisioning/instances with a
+// `demo` field), so this is the only route the demo adds. Owner-only, like every other
+// per-project write here; answered once.
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const { pool, validateOrRespond, parseId } = api;
+const provisioning = require('../provisioning');
+const demo = require('../demo');
+const { failFrom } = require('../public-refusal');
+
+const log = api.logger('provisioning');
+
+const REFUSALS = {
+  not_a_demo: [409, 'This project is not a demo.'],
+  already_settled: [409, 'This demo already has its answer.'],
+  bad_outcome: [400, 'outcome is carried or kept.'],
+};
+
+module.exports = function buildDemoRouter() {
+  const router = express.Router();
+
+  router.post('/provisioning/instances/:id/demo', api.requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, {
+      outcome: { required: true, type: 'string', enum: [...demo.OUTCOMES] },
+    })) return;
+    const id = parseId(req, res);
+    if (!id) return;
+    try {
+      const inst = await provisioning.getInstanceById(pool, id);
+      if (!inst || String(inst.owner_builder_id) !== String(req.builder.id)) return res.fail('instance_not_found', 404);
+      const r = await demo.settleDemo(pool, inst, req.body.outcome);
+      if (!r.ok) {
+        const [status, message] = REFUSALS[r.reason] || [409, r.reason];
+        return res.fail(r.reason, { status, message });
+      }
+      await provisioning.recordEvent(pool, { instanceId: id, ownerBuilderId: inst.owner_builder_id, event: 'demo-settled',
+        detail: { outcome: req.body.outcome }, actor: 'api:self' }).catch(() => {});
+      res.json({ ok: true, outcome: req.body.outcome, demo: demo.demoView({ demo: r.demo }) });
+    } catch (err) {
+      log.error('[provisioning] POST /provisioning/instances/:id/demo', err);
+      failFrom(res, err, 'demo_settle_failed');
+    }
+  });
+
+  return router;
+};

package/modules/provisioning/routes/provisioning.js

@@ -61,7 +61,7 @@ const catalogBridge = require('../catalog-bridge');
 const capacity = require('../capacity');   // the box's slot ceiling (ADR 0285, task 1003927)
 const { callbackPage } = require('./callback-page');
 // the LOUD body validators (task 1003504) — lifted out when this file hit the size ratchet
-const { badProjectDetail, badModuleSelection, badProjectType, screenedOut } = require('./body-validators');
+const { badProjectDetail, badModuleSelection, badProjectType, screenedOut } = require('./body-validators'); const demo = require('../demo');
 const { failFrom } = require('../public-refusal');   // every catch: a declared refusal reaches the owner, anything else stays opaque (task 1004126)
 const { settingsPush, failPushConflict } = require('../settings-push');   // a settings save's push + receipt, shared with routes/look.js (task 1004421)
 // the kernel ports this module provides (moved out at the size ratchet, task 1003578)
@@ -324,7 +324,7 @@ module.exports = function provisioningRoutes() {
       // exactly the set the panel preselected. An explicit [] is the different
       // answer "none of them". maxItems is a sanity ceiling well above a catalog
       // that is three modules wide today.
-      modules: { type: 'array', itemsType: 'string', maxItems: 50 }, terms_acknowledged: { type: 'boolean' },   // the latter: the wizard's terms tick (task 1004417, ../terms-ack.js)
+      modules: { type: 'array', itemsType: 'string', maxItems: 50 }, terms_acknowledged: { type: 'boolean' }, demo: { type: 'object' },   // the wizard's terms tick (task 1004417, ../terms-ack.js); the demo route's { people, hours_each } (task 1004420, ../demo.js)
     })) return;
     const body = req.body || {};
     const detailFault = badProjectDetail(body.detail);
@@ -333,6 +333,8 @@ module.exports = function provisioningRoutes() {
     if (modulesFault) return res.fail(modulesFault.code, { status: 400, message: modulesFault.message });
     const screened = screenedOut(body.description); // the stop screen (task 1004416): before anything exists
     if (screened) return res.fail('screened_out', screened);
+    const demoAsk = demo.parseDemo(body.demo);   // a demo is a normal project marked demo, its picked answers under the owner's own (task 1004420)
+    if (!demoAsk.ok) return res.fail('bad_demo', { status: 400, message: demoAsk.reason });
     const slug = String(body.slug || '').trim().toLowerCase();
     if (!provisioning.isValidSlug(slug)) {
       return res.fail('bad_slug', 400, { reason: 'lowercase, 2–40 chars of [a-z0-9-], no leading/trailing/double dash' });
@@ -424,7 +426,7 @@ module.exports = function provisioningRoutes() {
         type: body.type,
         // The optional detail step's answers (task 1002334) — absent means the
         // owner skipped it, which is the supported default, not an error.
-        description: body.description, detail: body.detail,
+        description: body.description, detail: demoAsk.demo ? demo.withDemoDetail(body.detail) : body.detail,
         // The picker's selection (task 1002339) — absent for the same reason and
         // with the same standing: skipped, and resolved from the bundle on read.
         modules: body.modules, termsAck: termsAcknowledgement(body),
@@ -456,7 +458,8 @@ module.exports = function provisioningRoutes() {
       // description exists — the publish gate alone decides that — but the row has to be
       // there for the gate to have anything to decide about, and for the wizard's invite
       // step to have a project to invite into while standup is still running.
-      await catalogBridge.publishInstanceToCatalog(pool, instance).catch(() => {});
+      const demoRow = created && demoAsk.demo ? await demo.startDemoProject(pool, provisioning, instance.id, demoAsk.demo) : null;
+      await catalogBridge.publishInstanceToCatalog(pool, demoRow || instance).catch(() => {});
       // A re-request cannot change an existing instance's domain — SAY so instead of
       // silently dropping it (task 1002692); the domain route is the real path.
       let domainIgnored;

package/modules/public-landing/public/projects-demo.states.json

@@ -0,0 +1,53 @@
+{
+  "_": "The demo route (task 1004420) on a demo project's own page: the time box has run out, so the Demo planet card asks keep your planet, with the offline date beside it. The page is projects.states.json's; only the instance read differs (provisioning-instances-demo.json).",
+  "page": "/projects",
+  "surface": "public-landing",
+  "stub": {
+    "fixtures": {
+      "provisioning-instances": "provisioning-instances-demo"
+    }
+  },
+  "modes": [
+    "dark"
+  ],
+  "modeQuery": false,
+  "ignoreRequests": [
+    "/api/(gds|bongos)/me$",
+    "/my-projects",
+    "/provisioning/instances/999",
+    "/provisioning/instances/101$",
+    "/api/bongos/instance$",
+    "/github/repos$",
+    "/provisioning/onboard-plan"
+  ],
+  "ignoreConsole": [
+    "/api/(gds|bongos)/me",
+    "\\b401\\b",
+    "\\b404\\b",
+    "Unauthorized"
+  ],
+  "states": {
+    "in-manage-demo": {
+      "auth": true,
+      "url": "/projects?view=manage&id=101",
+      "expect": {
+        "visible": [
+          "#mDemo",
+          "#mDemoClock",
+          "#mDemoKeep",
+          "#mDemoOffline"
+        ],
+        "text": [
+          [
+            "#mDemoKeep .demoKeepH",
+            "Keep your planet?"
+          ]
+        ]
+      }
+    }
+  },
+  "ignoreControls": [
+    ".skip",
+    ".vh"
+  ]
+}