@bongos/core 1.19.419 → 1.19.420

package/docs/file-map.md

@@ -349,6 +349,7 @@ tests/
 ├── sandbox_stage.mjs             ← (#927, ADR 0046): sandbox-first review gate — box detection, BOX_PREVIEW_HOSTNAME parsing, previewable-surface matching, decideShipGate table, tree-stamp freshness (temp git repo), runShipGate composition with injected fs/exec/prompt.
 ├── session_start_freshness.mjs   ← (#1277, ADR 0067): the SessionStart freshness decision (decideFreshness) — pull ONLY on a clean `main` full clone strictly behind origin/main; warn in every other behind case; skip when up to date.
 ├── own_scope_guard.mjs           ← (task 1003343, goal 1000045 criterion own-scope-held-by-a-test): the OWN-SCOPE structural guard, generalised out of memory_isolation.mjs. An explicit inventory of own-scoped route files; inside them the route's declared PATH decides — a path naming no builder must never read a subject from the request (direct, optional-chained, destructured, aliased, computed-key or header), a path that DOES name one needs a per-route exemption whose gate the guard verifies is present. Repo-wide backstop: any file mounting a `/me` route must be in the inventory. Source-grepping, so it runs in the DB-free `unit` lane.
+├── account_existence_rate_limit.mjs ← (task 1003339, goal 1000045, ADR 0209): the two PUBLIC account-existence probes (onboarding GET /access-requests/status + core GET /auth/web/admission-status) share ONE per-IP budget. Counts to the limit on each route, proves the budget is shared in both directions and when alternated, moves Date.now to prove the window slides on the real mounted route, and proves a refused probe issues no query. DB-free; mutation-checked three ways.
 └── public_task_resolver.mjs      ← (#604): the public `/public/tasks/:id` projection — title/value_summary exposed only for shipped|confirmed; withheld for in-flight so unshipped/security task names can't leak.
 ```
 

package/docs/module-api-changelog.md

@@ -1275,5 +1275,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.417 with no explicit bump. run 33264139544. (task 1002620)
   1.19.419 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.418 with no explicit bump. run 33265382684. (task 1002620)
+  1.19.420 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.419 with no explicit bump. run 33266034679. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/dev-box/app/src/vendor/bongos-client.cjs

@@ -640,6 +640,8 @@ function createClient(opts = {}) {
       postProvisioningInstances: (args) => request("POST", "/provisioning/instances", { hasBody: true }, args),
       // GET /provisioning/instances/{id} — rank: any-builder — GET /provisioning/instances/:id
       getProvisioningInstancesId: (args) => request("GET", "/provisioning/instances/{id}", { hasBody: false }, args),
+      // PATCH /provisioning/instances/{id}/detail — rank: any-builder — PATCH /provisioning/instances/:id/detail
+      patchProvisioningInstancesIdDetail: (args) => request("PATCH", "/provisioning/instances/{id}/detail", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/domain — rank: any-builder — POST /provisioning/instances/:id/domain
       postProvisioningInstancesIdDomain: (args) => request("POST", "/provisioning/instances/{id}/domain", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/force-teardown — rank: metic+archon — POST /provisioning/instances/:id/force-teardown

package/modules/onboarding/routes/access-requests.js

@@ -28,7 +28,10 @@
 //
 // The global IP rate-limiter (mounted in routes.js before every router) guards
 // the public POST against spam. A partial unique index on lower(github_login)
-// stops one username piling up duplicate open requests.
+// stops one username piling up duplicate open requests. The global limiter
+// meters WRITES only, so the public GET /access-requests/status carries its own
+// per-IP read cap — api.accountExistenceReadRateLimit, shared with core's
+// admission-status twin (task 1003339, ADR 0209).
 
 const express = require('express');
 // Carved into modules/onboarding/ (BV1.R81 / ADR 0093 §1). The auth gates, the
@@ -38,7 +41,7 @@ const express = require('express');
 const api = require('../../../src/module-api');
 const auth = { requireBuilder: api.requireBuilder, requirePermission: api.requirePermission };
 const { pool } = api;
-const { validateOrRespond, parseId } = api;
+const { validateOrRespond, parseId, accountExistenceReadRateLimit } = api;
 const approvalBroadcast = require('../approval-broadcast');
 const log = api.logger('onboarding');
 
@@ -137,7 +140,17 @@ module.exports = function buildAccessRequestsRouter() {
   // rank: public — a would-be builder is by definition outside the system.
   // Declared BEFORE `GET /access-requests` so the literal `/status` path is matched
   // as its own route (not swallowed as a query on the list route).
-  router.get('/access-requests/status', async (req, res) => {
+  //
+  // RATE-LIMITED (task 1003339 / ADR 0209). Public + unthrottled, this was a
+  // login→membership oracle an attacker could script at line rate to learn who
+  // builds here. accountExistenceReadRateLimit is the doorway's SHARED 120/60s
+  // per-IP budget: core's GET /auth/web/admission-status (the boolean twin of
+  // this answer) mounts the very same instance, so the two cannot be alternated
+  // for double the rate. The limiter runs before the queries, so a refused probe
+  // costs no DB work. Whether the ANSWER should also collapse — so a caller who
+  // is not the subject cannot tell pending/dismissed/none apart — is the owner's
+  // call and is filed as a blocker, not decided here.
+  router.get('/access-requests/status', accountExistenceReadRateLimit, async (req, res) => {
     const login = normalizeLogin(req.query.github_login);
     if (!GITHUB_LOGIN_RE.test(login)) {
       return res.fail('bad_github_login', { status: 400, message: 'That does not look like a GitHub username.' });

package/modules/platform-identity/platform-identity.js

@@ -201,7 +201,7 @@ async function getAccount(githubId, { pool = defaultPool } = {}) {
 // (task #1002109) calls this with a freshly generated secret; the plaintext is
 // hashed here and never stored. Upsert-on-client_id so re-provisioning rotates
 // the secret + redirect_uris without a duplicate row.
-async function registerClient({ clientId, secret, name, redirectUris, origin, ownerGithubId, type }, { pool = defaultPool } = {}) {
+async function registerClient({ clientId, secret, name, redirectUris, origin, ownerGithubId, type, description }, { pool = defaultPool } = {}) {
   const secretHash = sha256hex(secret);
   const uris = Array.isArray(redirectUris) ? redirectUris : [];
   const { rows } = await pool.query(
@@ -218,11 +218,11 @@ async function registerClient({ clientId, secret, name, redirectUris, origin, ow
      RETURNING id, client_id, name, redirect_uris, origin, owner_github_id, status`,
     [clientId, secretHash, name, uris, origin ?? null, ownerGithubId ?? null],
   );
-  // Auto-catalogue the project (unfeatured) so it appears in the Archon curation
-  // list the moment it federates (ADR 0141 §5). Best-effort — a catalog hiccup must
-  // never fail client registration. Only when an origin is known.
+  // Auto-catalogue the project (unfeatured) so it appears in the Archon curation list the
+  // moment it federates (ADR 0141 §5). Best-effort — a hiccup must never fail registration;
+  // only when an origin is known. `description` rides along like `type` (ADR 0182 D4, task 1002334).
   if (origin) {
-    try { await upsertProject({ origin, name, ownerGithubId, type }, { pool }); }
+    try { await upsertProject({ origin, name, description, ownerGithubId, type }, { pool }); }
     catch (err) { console.error('[platform-identity] auto-catalogue failed (non-fatal):', err.message); }
   }
   return rows[0];

package/modules/platform-identity/tests/platform-identity.mjs

@@ -406,6 +406,26 @@ await ta('registerClient auto-catalogues the project (2nd query) when an origin
   assert.match(pool.calls[1].text, /INSERT INTO platform_identity_projects/);
 });
 
+await ta('registerClient forwards the project-detail description into the catalog row (task 1002334)', async () => {
+  // Half the publish gate (ADR 0182 D4). It is given on the platform before this
+  // row exists, so if this hop drops it a project that DID describe itself sits
+  // in dark matter and the optional step is decorative.
+  const pool = mockPool([{ rows: [{ client_id: 'c1', origin: 'https://p' }] }, { rows: [{ id: '9' }] }]);
+  await P.registerClient(
+    { clientId: 'c1', secret: 'z'.repeat(64), name: 'Proj', redirectUris: [], origin: 'https://p', ownerGithubId: 7, description: 'A weather sim.' },
+    { pool },
+  );
+  assert.ok(pool.calls[1].params.includes('A weather sim.'), 'the description reaches the catalog upsert');
+});
+
+await ta('registerClient with a SKIPPED interview passes no description — and COALESCE nulls nothing', async () => {
+  const pool = mockPool([{ rows: [{ client_id: 'c1', origin: 'https://p' }] }, { rows: [{ id: '9' }] }]);
+  await P.registerClient({ clientId: 'c1', secret: 'z'.repeat(64), name: 'Proj', redirectUris: [], origin: 'https://p' }, { pool });
+  assert.equal(pool.calls[1].params[3], null, 'absent travels as null');
+  assert.match(pool.calls[1].text, /description     = COALESCE\(EXCLUDED\.description/,
+    'so a re-registration can never erase a description the owner added later');
+});
+
 console.log('\nproject memberships (§3 check-in directory):');
 
 await ta('recordFederatedSignin is the ONE path that creates a membership, and stamps the witness', async () => {

package/modules/provisioning/migrations/provisioning_013_project_detail.sql

@@ -0,0 +1,54 @@
+-- provisioning_013_project_detail.sql — the optional project-detail interview's
+-- storage (BV1.R15, task 1002334; goal 1000046 criterion `proj-detail-interview`).
+--
+-- The creation sequence gains ONE optional, skippable step — "tell us about your
+-- project" — and its answers have to live somewhere real the moment they are
+-- given. A standalone project never federates into the hub catalog at create
+-- time, so this mirrors exactly what provisioning_007 did for the declared
+-- `type`: the answer rides the provisioning request, and the control-plane
+-- runner carries it into platform_identity_projects whenever a catalog row
+-- materializes.
+--
+-- TWO columns, deliberately not one:
+--
+--   description  a REAL column, because it is half of the publish gate (ADR 0182
+--                D4: publishable iff name AND description are both present). It
+--                mirrors platform_identity_projects.description, which
+--                platform_identity_011 added for the same reason. NOT `tagline` —
+--                ADR 0182 refuses to collapse them, since a description is the
+--                publish bar and editing your card must never unpublish you.
+--
+--   detail       jsonb, because the interview grows one answer at a time as R17
+--                (rule-based recommendations), R19 (starter bundles) and R27
+--                (invites) land, and a new question must not cost a migration
+--                each time. Same contract as `settings` (provisioning_009): the
+--                column is a dumb store, the known keys + their vocabularies are
+--                enforced in code (provisioning.PROJECT_DETAIL_VOCAB +
+--                normalizeProjectDetail), and an unknown or off-vocabulary stored
+--                value is dropped at read time rather than leaking out.
+--
+-- SKIPPING IS THE DEFAULT, not a failure: both columns are nullable/empty, and an
+-- empty description is precisely what leaves a project dark-matter until its
+-- owner fills it in (ADR 0182 D4 — the bar exists to keep empty husks off the
+-- map, not to enforce completeness). Nothing here changes live behaviour; R16
+-- (task 1002335) is the surface that computes publishability and names what is
+-- missing.
+--
+-- Additive + provisioning_-namespaced (ADR 0083 §5): ADD COLUMN only, so the
+-- previous code release still runs against this schema. Idempotent: safe to re-run.
+
+BEGIN;
+
+ALTER TABLE provisioning_instances
+  ADD COLUMN IF NOT EXISTS description text;
+
+ALTER TABLE provisioning_instances
+  ADD COLUMN IF NOT EXISTS detail jsonb NOT NULL DEFAULT '{}'::jsonb;
+
+COMMENT ON COLUMN provisioning_instances.description IS
+  'What the owner said they are building — the answer to the optional project-detail step (BV1.R15). Half of the publish gate (ADR 0182 D4: publishable iff name AND description are present), mirrored into platform_identity_projects.description when a catalog row materializes. NULL = the step was skipped, which is a supported default, not a failure: the project stays dark-matter until it is filled in.';
+
+COMMENT ON COLUMN provisioning_instances.detail IS
+  'The rest of the optional project-detail interview, as a dumb jsonb store (the `settings` contract from provisioning_009). Known keys + vocabularies live in provisioning.PROJECT_DETAIL_VOCAB and are enforced at the API layer; an unknown or off-vocabulary stored value is dropped at read time. jsonb so the interview can grow an answer at a time (R17 recommendations, R19 bundles, R27 invites) without a migration each time. {} = skipped.';
+
+COMMIT;

package/modules/provisioning/onboard-plan.js

@@ -9,6 +9,15 @@
 //
 // PURE — no I/O, no core imports. Safe to require from a script, a route, or a test.
 //
+// `optional: true` (task 1002334) marks a step every form must OFFER and every
+// owner may SKIP — today just `project-detail`, the "tell us about your project"
+// interview. It is a real step in the sequence rather than a wizard-only flourish
+// because all four forms have to ask it the same way; skipping is a supported
+// default that leaves the project dark-matter (off the map, un-joinable) until its
+// description is filled in later, never a dead end (ADR 0182 D4). A form that can
+// only render a linear checklist may treat an optional step as any other; one that
+// takes answers must let the owner past it without one.
+//
 // Each step: { key, kind: 'auto' | 'human', label }. `kind: 'human'` marks the
 // irreducibly-manual owner actions (create the GitHub repo, wire GitHub sign-in, first
 // sign-in, enter the hall) that every form renders UI-first; `kind: 'auto'` steps the
@@ -36,6 +45,10 @@ function onboardPlan(mode = 'greenfield', opts = {}) {
   const domain = typeof opts.domain === 'string' && opts.domain.trim() ? opts.domain.trim() : null;
   return [
     { key: 'name-address', kind: 'auto', label: 'Decide name + address (interview)' },
+    // 'auto' like name-address above, and for the same reason: the form itself
+    // collects it, so it is not one of the irreducibly-manual legs a done panel
+    // lists. `optional` is what makes it skippable — see the header.
+    { key: 'project-detail', kind: 'auto', optional: true, label: 'Tell us about your project — optional, skip it and add it later' },
     { key: 'github-repo', kind: 'human', label: adopt ? 'Use your EXISTING GitHub repository' : 'Create the empty GitHub repository' },
     { key: 'dns-preflight', kind: 'auto', shapes: CONTROL_PLANE_SHAPES, label: 'DNS token preflight — before the address step (task 1980)' },
     { key: 'init', kind: 'auto', label: adopt ? 'bongos init --adopt — LAYER onto the existing repo (pre-flight + accept)' : 'bongos init — scaffold the instance config' },

package/modules/provisioning/provisioning.js

@@ -124,6 +124,34 @@ const SETTINGS_VOCAB = Object.freeze({
 });
 const DEFAULT_SETTINGS = Object.freeze({ platform_visibility: 'public', joinability: 'apply' });
 
+// The optional project-detail interview (BV1.R15, task 1002334) — the "tell us
+// about your project" step every creation form offers and every owner may skip.
+// The interview asks two things, and the vocabulary is the contract for the
+// closed-answer half:
+//
+//   team_shape   who is going to build it — the input R17 (task 1002336) maps to a
+//                recommended governance preset and to invite suggestions.
+//
+// (The module bundle R19 recommends comes off the separately-declared `type`, so
+// the interview deliberately does not ask it a second time.)
+//
+// The free-text half of the interview is NOT here: `description` is a real column
+// (migration provisioning_013) because it is half of the publish gate (ADR 0182
+// D4), while these are jsonb so a later question costs no migration — same dumb-
+// store contract as SETTINGS_VOCAB above.
+//
+// There is deliberately NO default. Settings describe a policy the instance must
+// obey, so an absent one has to resolve to today's behaviour; a detail answer is
+// something the owner SAID, and inventing one they never said would feed R17 a
+// recommendation nobody asked for. Absent stays absent, and skipped stays skipped.
+const PROJECT_DETAIL_VOCAB = Object.freeze({
+  team_shape: ['solo', 'small-team', 'community'],
+});
+// The publish-gate half of the interview is prose, so it needs a ceiling. Long
+// enough for a real paragraph, short enough that the column is never a document —
+// the Explore card renders `tagline`, not this.
+const DESCRIPTION_MAX = 600;
+
 // Monthly cost estimate (USD) for a dedicated droplet tier — VISIBILITY only
 // (ADR 0111 §6), never a bill. A small local table so this module needs no
 // sibling-module import; P2 (shared control-plane client extraction) is where a
@@ -257,6 +285,14 @@ function publicInstance(row) {
     // instances so a declaration shows before the catalog carries it. Nullable:
     // rows predating provisioning_007, or a declined answer, project null.
     type: row.type || null,
+    // The optional project-detail interview (task 1002334): what the owner said
+    // they are building, and the answers that feed R17's recommendations. Both
+    // are legitimately empty — the step is skippable by design — and `description`
+    // being null is exactly what keeps the project dark-matter until it is filled
+    // in (ADR 0182 D4). Surfaced so a form can render "here's what's still
+    // missing" from a plain instance read, without a second endpoint.
+    description: row.description || null,
+    detail: projectDetail(row),
     // The verification overlay (task 1002696, redesign direction §3): what the
     // heartbeat last OBSERVED, which is NOT what `status` claims. null = never
     // probed — a different claim from last_verified_up=false, and the UI renders
@@ -330,6 +366,40 @@ function effectiveSettings(row) {
   return out;
 }
 
+// A description as it may be STORED: trimmed, collapsed of runaway whitespace,
+// capped, and empty-means-absent. Returns null for anything that isn't real prose,
+// because null is what leaves the project dark-matter — an empty string stored in a
+// nullable column would look answered to `description IS NOT NULL` and publish an
+// husk, which is the one thing the gate exists to prevent (ADR 0182 D4). PURE.
+function normalizeDescription(input) {
+  if (typeof input !== 'string') return null;
+  const text = input.replace(/\s+/g, ' ').trim();
+  if (!text) return null;
+  return text.slice(0, DESCRIPTION_MAX);
+}
+
+// The detail answers as they may be STORED: on-vocabulary keys only, everything
+// else dropped. An off-vocabulary value is dropped rather than defaulted — a
+// recommendation built on an answer the owner never gave is worse than no
+// recommendation (see PROJECT_DETAIL_VOCAB). Always returns a plain object, so a
+// skipped interview stores `{}` rather than null. PURE.
+function normalizeProjectDetail(input) {
+  const given = input && typeof input === 'object' && !Array.isArray(input) ? input : {};
+  const out = {};
+  for (const [key, vocab] of Object.entries(PROJECT_DETAIL_VOCAB)) {
+    if (vocab.includes(given[key])) out[key] = given[key];
+  }
+  return out;
+}
+
+// What a row's detail answers READ as — the stored object filtered through the
+// same vocabulary, so a value that was valid when written and has since left the
+// vocabulary never leaks out of the read surface. Mirrors effectiveSettings, minus
+// the defaults it deliberately has none of. PURE.
+function projectDetail(row) {
+  return normalizeProjectDetail(row && row.detail);
+}
+
 // ---------------------------------------------------------------------------
 // GitHub App Manifest flow — PURE builders (task 2080, ADR 0133).
 // GitHub has no create-an-OAuth-App API, but the App *Manifest* flow lets the owner
@@ -479,6 +549,35 @@ async function updateInstanceSettings(db, id, patch) {
   return rows[0] || null;
 }
 
+// Fill in (or change) the project-detail answers AFTER creation — the other half
+// of "skippable" (task 1002334). Skipping the step at creation is a supported
+// default, but it is only a default and not a dead end if there is a way back; this
+// is that way back, and it is what turns a dark-matter project publishable once its
+// owner writes a description (ADR 0182 D4).
+//
+// `detail` MERGES (the settings `||` precedent — a form may send one answer without
+// resending the rest) while `description` REPLACES, because prose has no keys to
+// merge. Passing description: null clears it — and un-publishes the project, which
+// is the honest consequence of deleting half the identity gate, not a bug.
+// Undefined leaves the column alone.
+async function updateInstanceDetail(db, id, { description, detail } = {}) {
+  const sets = ['updated_at = now()'];
+  const params = [id];
+  if (description !== undefined) {
+    params.push(description);
+    sets.push(`description = $${params.length}`);
+  }
+  if (detail !== undefined) {
+    params.push(JSON.stringify(normalizeProjectDetail(detail)));
+    sets.push(`detail = detail || $${params.length}::jsonb`);
+  }
+  const { rows } = await db.query(
+    `UPDATE provisioning_instances SET ${sets.join(', ')} WHERE id = $1 RETURNING *`,
+    params
+  );
+  return rows[0] || null;
+}
+
 // Record an instance's domain — the ONLY columns this touches (task 1002692;
 // `releasing` added by task 1003237). Status changes stay setInstanceStatus's job;
 // keeping this narrow means the domain-attach route can never drift an instance's
@@ -630,7 +729,7 @@ async function listAllInstances(db, { status } = {}) {
 // re-fetches the existing row and returns { created:false } so the ROUTE can
 // decide (same owner → idempotent re-request; different owner → 409). Never
 // silently reassigns ownership.
-async function createInstance(db, { ownerBuilderId, slug, targetRef, hostingShape, domain, dbName, port, tier, onboardMode, type }) {
+async function createInstance(db, { ownerBuilderId, slug, targetRef, hostingShape, domain, dbName, port, tier, onboardMode, type, description, detail }) {
   const shape = HOSTING_SHAPES.includes(hostingShape) ? hostingShape : 'co-tenant';
   // Unknown/absent → 'greenfield', matching the column default. Falling back to the
   // SAFE mode matters: greenfield refuses to push over existing history (no --force
@@ -639,15 +738,22 @@ async function createInstance(db, { ownerBuilderId, slug, targetRef, hostingShap
   const mode = ONBOARD_MODES.includes(onboardMode) ? onboardMode : 'greenfield';
   // Type is a declaration — off-vocabulary or absent stores null, never a guess.
   const declaredType = PROJECT_TYPES.includes(type) ? type : null;
+  // The optional project-detail step (task 1002334). Skipping it is the SUPPORTED
+  // default, so both of these legitimately land empty — a null description is what
+  // leaves the project dark-matter until its owner fills it in (ADR 0182 D4), and
+  // updateInstanceDetail is the way back.
+  const told = normalizeDescription(description);
+  const answers = normalizeProjectDetail(detail);
   const cost = costEstimateUsd({ hostingShape: shape, tier });
   try {
     const { rows } = await db.query(
       `INSERT INTO provisioning_instances
-         (owner_builder_id, slug, target_ref, hosting_shape, domain, db_name, port, tier, cost_estimate_usd, onboard_mode, type)
-       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)
+         (owner_builder_id, slug, target_ref, hosting_shape, domain, db_name, port, tier, cost_estimate_usd, onboard_mode, type, description, detail)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13::jsonb)
        RETURNING *`,
       [ownerBuilderId, slug, targetRef ?? null, shape, domain ?? null,
-       dbName ?? null, port ?? null, tier ?? null, cost, mode, declaredType]
+       dbName ?? null, port ?? null, tier ?? null, cost, mode, declaredType,
+       told, JSON.stringify(answers)]
     );
     return { instance: rows[0], created: true };
   } catch (e) {
@@ -959,10 +1065,11 @@ module.exports = {
   SETTINGS_APPLY_FROM, SETTINGS_APPLY_SHAPES,
   RESTART_FROM, RESTART_SHAPES,
   TIER_MONTHLY_USD, CERT_ELIGIBLE_STATES,
-  SETTINGS_VOCAB, DEFAULT_SETTINGS,
+  SETTINGS_VOCAB, DEFAULT_SETTINGS, PROJECT_DETAIL_VOCAB, DESCRIPTION_MAX,
   // pure
   isValidSlug, costEstimateUsd, publicInstance, normalizeHostname,
   defaultDomainForSlug, isReservedHostname, effectiveSettings,
+  normalizeDescription, normalizeProjectDetail, projectDetail,
   // pure — GitHub App Manifest flow (task 2080)
   githubAppName, buildGithubAppManifest, manifestPostUrl, publicGithubApp,
   // data access
@@ -970,6 +1077,7 @@ module.exports = {
   getInstanceById, getInstanceBySlug, getInstanceByDomain, listInstancesForOwner, listAllInstances,
   // data access — verification overlay (task 1002696)
   listActiveInstancesForLiveness, recordLivenessProbe, recordDnsNote, clearErrorNote,
+  createInstance, setInstanceStatus, updateInstanceDomain, updateInstanceSettings, updateInstanceDetail,
   createInstance, setInstanceStatus, updateInstanceDomain, clearReleasedDomains, updateInstanceSettings,
   enqueueIntent, enqueueTeardown, enqueueSettingsApply, enqueueRestart, getOpenIntent, claimNextIntent, resolveIntent,
   recordEvent, instanceStateForSlug, costLedger,

package/modules/provisioning/routes/provisioning.js

@@ -86,6 +86,30 @@ function ownerFromTargetRef(ref) {
   return m ? m[1] : null;
 }
 
+// The project-detail answers, validated LOUDLY (task 1002334). `detail` arrives as
+// a nested object, and the strict body validator only reaches top-level fields — so
+// without this a typo'd answer key would be dropped by normalizeProjectDetail and
+// the caller would be told nothing, which is exactly the silent-drop failure the
+// strict validator exists to prevent (and that a re-request's type_ignored receipt
+// was written to avoid). Returns null when clean, or a { code, message } to fail
+// with. Both the create route and PATCH …/detail run it, so they cannot drift.
+function badProjectDetail(detail) {
+  if (detail === undefined || detail === null) return null;
+  if (typeof detail !== 'object' || Array.isArray(detail)) {
+    return { code: 'bad_detail', message: 'detail must be an object of answers.' };
+  }
+  const vocab = provisioning.PROJECT_DETAIL_VOCAB;
+  for (const [key, value] of Object.entries(detail)) {
+    if (!Object.prototype.hasOwnProperty.call(vocab, key)) {
+      return { code: 'bad_detail', message: `Unknown detail answer "${key}" — the interview asks: ${Object.keys(vocab).join(', ')}.` };
+    }
+    if (!vocab[key].includes(value)) {
+      return { code: 'bad_detail', message: `"${key}" must be one of: ${vocab[key].join(', ')}.` };
+    }
+  }
+  return null;
+}
+
 // Minimal HTML escaper for the callback landing page (no template engine here).
 function esc(s) {
   return String(s == null ? '' : s).replace(/[&<>"']/g, (c) => (
@@ -388,8 +412,16 @@ module.exports = function provisioningRoutes() {
       onboard_mode: { type: 'string', maxLength: 20 },
       // the declared project Type (task 1002772) — optional, closed vocabulary
       type: { type: 'string', enum: [...provisioning.PROJECT_TYPES] },
+      // The optional project-detail step (task 1002334) — "tell us about your
+      // project", skippable everywhere. Absent means SKIPPED, which is a supported
+      // default: the project simply stays dark-matter until a description exists
+      // (ADR 0182 D4), and PATCH …/detail is the way back.
+      description: { type: 'string', maxLength: provisioning.DESCRIPTION_MAX },
+      detail: { type: 'object' },
     })) return;
     const body = req.body || {};
+    const detailFault = badProjectDetail(body.detail);
+    if (detailFault) return res.fail(detailFault.code, { status: 400, message: detailFault.message });
     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' });
@@ -472,6 +504,9 @@ module.exports = function provisioningRoutes() {
         targetRef: body.target_ref, hostingShape: shape,
         domain, tier: body.tier, onboardMode,
         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,
       });
       // Slug already taken by ANOTHER builder — refuse (never reassign ownership).
       if (!created && String(instance.owner_builder_id) !== String(req.builder.id)) {
@@ -525,6 +560,16 @@ module.exports = function provisioningRoutes() {
           hint: "a re-request never changes an existing instance's declared type",
         };
       }
+      // …and the same for the detail answers (task 1002334). Unlike type this one
+      // HAS a mutation route, so the receipt names it instead of just refusing —
+      // otherwise an owner who came back to fill in the description they skipped
+      // would be told nothing and left dark-matter with no idea why.
+      let detailIgnored;
+      if (!created && (body.description !== undefined || body.detail !== undefined)) {
+        detailIgnored = {
+          hint: `a re-request never changes an existing instance's project detail — PATCH /provisioning/instances/${instance.id}/detail instead`,
+        };
+      }
       res.status(created ? 201 : 200).json({
         instance: provisioning.publicInstance(instance),
         open_intent: intent ? { action: intent.action, state: intent.state } : null,
@@ -533,6 +578,7 @@ module.exports = function provisioningRoutes() {
         ...(domainIgnored ? { domain_ignored: domainIgnored } : {}),
         ...(noAddressIgnored ? { no_address_ignored: noAddressIgnored } : {}),
         ...(typeIgnored ? { type_ignored: typeIgnored } : {}),
+        ...(detailIgnored ? { detail_ignored: detailIgnored } : {}),
       });
     } catch (err) {
       log.error('[provisioning] POST /provisioning/instances', err);
@@ -644,6 +690,65 @@ module.exports = function provisioningRoutes() {
     }
   });
 
+  // ── The optional project detail (task 1002334, goal 1000046) ──────────────
+  // PATCH /provisioning/instances/:id/detail — answer (or re-answer) the
+  // "tell us about your project" step after creation. Body: any subset of
+  // { description, detail }. rank: any authenticated builder (own resource;
+  // archon may change any — same gate as settings).
+  //
+  // THIS ROUTE IS WHAT MAKES THE STEP SKIPPABLE. Skipping at creation leaves the
+  // project dark-matter — off the map and un-joinable (ADR 0182 D4) — and that is
+  // a supported default only because there is a way back. Without this route
+  // "optional" would mean "permanently unpublishable", i.e. a dead end, which is
+  // precisely what criterion `proj-detail-interview` refuses.
+  //
+  // Deliberately NOT a settings-apply: nothing here is a policy the running
+  // instance obeys, so there is no web.env to patch and no restart to queue. The
+  // answers live on the platform row until a catalog row materializes (the
+  // provisioning_007 `type` precedent), and R16 (task 1002335) is the surface that
+  // reads `description` to compute publishability and name what is still missing.
+  router.patch('/provisioning/instances/:id/detail', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res); // (req, res) — parseId sends 400 bad_id + returns null on failure
+    if (!id) return;
+    if (validateOrRespond(req, res, {
+      description: { type: 'string', maxLength: provisioning.DESCRIPTION_MAX },
+      detail: { type: 'object' },
+    })) return;
+    const body = req.body || {};
+    const detailFault = badProjectDetail(body.detail);
+    if (detailFault) return res.fail(detailFault.code, { status: 400, message: detailFault.message });
+    if (body.description === undefined && body.detail === undefined) {
+      return res.fail('bad_detail', { status: 400,
+        message: 'The body carries nothing to change — send description, detail, or both.' });
+    }
+    try {
+      const inst = await provisioning.getInstanceById(pool, id);
+      if (instanceAccessDenied(inst, req.builder)) return res.fail('instance_not_found', 404);
+      const actor = String(inst.owner_builder_id) === String(req.builder.id) ? 'api:self' : `api:archon:${req.builder.id}`;
+      // An empty description is CLEARING it, not a no-op string: normalize here so
+      // the column never holds '' — a blank string would read as answered to a
+      // `description IS NOT NULL` publish check and put an empty husk on the map.
+      const patch = {};
+      if (body.description !== undefined) patch.description = provisioning.normalizeDescription(body.description);
+      if (body.detail !== undefined) patch.detail = body.detail;
+      const updated = await provisioning.updateInstanceDetail(pool, id, patch);
+      await provisioning.recordEvent(pool, {
+        instanceId: id, ownerBuilderId: inst.owner_builder_id, event: 'detail',
+        detail: `project detail changed: ${Object.keys(patch).join(', ')}`,
+        actor,
+      }).catch(() => {});
+      res.json({
+        ok: true,
+        description: updated.description || null,
+        detail: provisioning.projectDetail(updated),
+        options: provisioning.PROJECT_DETAIL_VOCAB,
+      });
+    } catch (err) {
+      log.error('[provisioning] PATCH /provisioning/instances/:id/detail', err);
+      res.fail('detail_update_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // ── Per-project settings (task 1003040, goal 1000058) ─────────────────────
   // The foundation the manage-page wave hangs off: effective settings are the
   // DEFAULTS (today's behavior — public surfaces, apply-to-join) overlaid with

package/modules/provisioning/tests/provisioning.mjs

@@ -298,5 +298,89 @@ await ta('updateInstanceSettings: jsonb MERGE (||) + updated_at, parameterized,
   assert.deepEqual(params, [18, JSON.stringify({ joinability: 'open' })]);
 });
 
+console.log('');
+console.log('the optional project-detail interview (BV1.R15, task 1002334):');
+
+t('normalizeDescription: collapses whitespace, caps, and empty means ABSENT (never an empty string)', () => {
+  const NL = String.fromCharCode(10);
+  assert.equal(P.normalizeDescription('  A co-op   farming' + NL + '  game.  '), 'A co-op farming game.');
+  // null, not '' — the publish gate reads `description IS NOT NULL`, so a blank
+  // string stored in a nullable column would publish an empty husk (ADR 0182 D4)
+  assert.equal(P.normalizeDescription('   '), null);
+  assert.equal(P.normalizeDescription(''), null);
+  assert.equal(P.normalizeDescription(null), null);
+  assert.equal(P.normalizeDescription(42), null);
+  assert.equal(P.normalizeDescription('x'.repeat(P.DESCRIPTION_MAX + 50)).length, P.DESCRIPTION_MAX);
+});
+
+t('normalizeProjectDetail: on-vocabulary keys only — an unknown key or value is DROPPED, never defaulted', () => {
+  assert.deepEqual(P.normalizeProjectDetail({ team_shape: 'community' }), { team_shape: 'community' });
+  assert.deepEqual(P.normalizeProjectDetail({ team_shape: 'enormous' }), {}, 'an off-vocabulary answer is not stored');
+  assert.deepEqual(P.normalizeProjectDetail({ favourite_colour: 'blue' }), {}, 'an unknown question is not stored');
+  // skipping is the supported default, so every not-an-object shape reads as {}
+  for (const skipped of [undefined, null, 'solo', ['solo'], 7]) {
+    assert.deepEqual(P.normalizeProjectDetail(skipped), {}, 'a skipped interview stores {}');
+  }
+});
+
+t('projectDetail: a stored value that has since LEFT the vocabulary never leaks out of the read surface', () => {
+  assert.deepEqual(P.projectDetail({ detail: { team_shape: 'solo' } }), { team_shape: 'solo' });
+  assert.deepEqual(P.projectDetail({ detail: { team_shape: 'guild' } }), {});
+  assert.deepEqual(P.projectDetail({}), {}, 'a row predating the migration reads as skipped');
+  assert.deepEqual(P.projectDetail(null), {});
+});
+
+t('PROJECT_DETAIL_VOCAB carries NO defaults — an unanswered question stays unanswered', () => {
+  // The deliberate asymmetry with SETTINGS_VOCAB: a setting is a policy the
+  // instance must obey, so it needs a default; a detail answer is something the
+  // owner SAID, and a default would feed R17 a recommendation nobody asked for.
+  assert.equal(P.DEFAULT_PROJECT_DETAIL, undefined, 'there is no defaults table to drift from');
+  for (const vocab of Object.values(P.PROJECT_DETAIL_VOCAB)) {
+    assert.ok(Array.isArray(vocab) && vocab.length, 'every question has a closed answer list');
+  }
+});
+
+t('publicInstance surfaces both halves, and both are legitimately empty when skipped', () => {
+  const answered = P.publicInstance({ id: 1, slug: 'mercury', description: 'A thing.', detail: { team_shape: 'solo' } });
+  assert.equal(answered.description, 'A thing.');
+  assert.deepEqual(answered.detail, { team_shape: 'solo' });
+  const skipped = P.publicInstance({ id: 2, slug: 'venus' });
+  assert.equal(skipped.description, null, 'no description is null — what keeps the project dark-matter');
+  assert.deepEqual(skipped.detail, {}, 'and a skipped interview reads as {}, never undefined');
+});
+
+await ta('createInstance: the answers ride the INSERT, and a skipped interview inserts null + {}', async () => {
+  let params = null;
+  const db = { query: async (q, p) => { params = p; return { rows: [{ id: 3 }] }; } };
+  await P.createInstance(db, {
+    ownerBuilderId: 1, slug: 'mercury', description: '  A co-op  game. ',
+    detail: { team_shape: 'community', bogus: 'x' },
+  });
+  assert.equal(params[11], 'A co-op game.', 'the description is normalized before it is stored');
+  assert.equal(params[12], JSON.stringify({ team_shape: 'community' }), 'and off-vocabulary keys never reach the column');
+  await P.createInstance(db, { ownerBuilderId: 1, slug: 'venus' });
+  assert.equal(params[11], null, 'a skipped interview stores null — not an empty string');
+  assert.equal(params[12], '{}');
+});
+
+await ta('updateInstanceDetail: detail MERGES, description REPLACES, and neither is written unasked', async () => {
+  let sql = '', params = null;
+  const db = { query: async (q, p) => { sql = q; params = p; return { rows: [{ id: 18 }] }; } };
+
+  await P.updateInstanceDetail(db, 18, { detail: { team_shape: 'small-team' } });
+  assert.ok(sql.includes('detail = detail || $2::jsonb'), 'one answer does not erase the others');
+  assert.ok(!sql.includes('description ='), 'an unsent description is left alone, never nulled');
+  assert.deepEqual(params, [18, JSON.stringify({ team_shape: 'small-team' })]);
+
+  await P.updateInstanceDetail(db, 18, { description: 'Filled in later.' });
+  assert.ok(sql.includes('description = $2'), 'the way back for a skipped step');
+  assert.ok(!sql.includes('detail = detail'), 'and it touches no answers it was not given');
+
+  // clearing is allowed and un-publishes — the honest consequence of deleting
+  // half the identity gate, not a bug to guard against
+  await P.updateInstanceDetail(db, 18, { description: null });
+  assert.deepEqual(params, [18, null]);
+});
+
 console.log(`\nprovisioning module: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);