@bongos/core 1.25.15 → 1.25.16

package/modules/public-landing/public/index.html

@@ -43,6 +43,9 @@
      then styles new markup with an old sheet). -->
 <link rel="stylesheet" href="/modules/ui-design/public/tokens.css">
 <link rel="stylesheet" href="/assets/world.css">
+<!-- the start-a-project guide, as a scene in the game (task 1005275): drawn only when the
+     front-door-guide module is on and its server can talk -->
+<link rel="stylesheet" href="/assets/guide-scene.css">
 <style>
 /* ── PAGE-LOCAL SHEET ────────────────────────────────────────────────────
    The composition: how this page arranges the world's sculpture, and nothing
@@ -574,6 +577,12 @@ body{
     --orb-x:4vw;
     --orb-y:-6vh;
     --doors-cx:0;--doors-cy:0;
+    /* the start-a-project guide (assets/guide-scene.css, task 1005275): one column, the
+       frame the whole screen, the plan over the talk from its Plan button */
+    --gd-pad:0;--gd-frame-w:100%;--gd-frame-h:100%;--gd-cols:minmax(0,1fr);--gd-side:0px;
+    --gd-gutter:var(--ds-space-gutter-narrow);--gd-face:56px;--gd-face-img:48px;
+    --gd-planbtn:inline-flex;--gd-planx:inline-grid;--gd-go-w:100%;
+    --gd-plan-show:none;--gd-plan-pos:absolute;--gd-plan-edge:0px;--gd-talk-under-plan:hidden;
   }
   :root[data-mode="dark"] body{
     --layer-pos:relative;
@@ -779,7 +788,7 @@ composition A; landing composition v3, picked by the owner 2026-08-27. No roll,
       <div class="doors">
         <div class="doorbar">
           <a class="door" href="/projects">Find a project to join</a>
-          <a class="door door--go" href="/projects?view=new">Start a project</a>
+          <a class="door door--go" href="/projects?view=new" data-guide-door>Start a project</a>
         </div>
       </div>
     </div>
@@ -945,7 +954,7 @@ composition A; landing composition v3, picked by the owner 2026-08-27. No roll,
     <div class="wrap">
       <div class="closemark" aria-hidden="true"></div>
       <div class="doorbar">
-        <a class="door door--go" href="/projects?view=new">Start a project</a>
+        <a class="door door--go" href="/projects?view=new" data-guide-door>Start a project</a>
         <a class="door" href="/projects">Find a project</a>
       </div>
       <div class="cli" data-cli hidden>
@@ -957,6 +966,53 @@ composition A; landing composition v3, picked by the owner 2026-08-27. No roll,
   </section>
 </main>
 
+<!-- THE GUIDE (task 1005275): the start-a-project conversation as a scene in the game.
+     Hidden, and never opened, unless the front-door-guide module is on and its status read
+     says it can talk (assets/guide-scene.js); with it off the doors above are plain links. -->
+<div class="gd" id="guide" role="dialog" aria-modal="true" aria-labelledby="gdTitle" hidden>
+  <div class="gd__frame">
+    <section class="gd__talk" aria-labelledby="gdTitle">
+      <div class="gd__head">
+        <h2 class="gd__title" id="gdTitle">Start a project</h2>
+        <button type="button" class="gd__x" data-gd="close" aria-label="Close"><svg viewBox="0 0 20 20" aria-hidden="true"><path d="M5 5l10 10M15 5L5 15"/></svg></button>
+      </div>
+      <div class="gd__who-row">
+        <span class="gd__face"><img src="/modules/hall-ui/public/characters/patron.png" alt="" width="64" height="64"></span>
+        <div class="gd__meta">
+          <p class="gd__name">Your guide</p>
+          <p class="gd__left" data-gd="left" aria-live="polite" hidden></p>
+          <span class="gd__segs" data-gd="segs" aria-hidden="true" hidden></span>
+        </div>
+        <button type="button" class="gd__planbtn" data-gd="plan-toggle" aria-expanded="false" aria-controls="gdPlan">Plan</button>
+      </div>
+      <ol class="gd__log" data-gd="log" aria-live="polite" aria-label="Conversation"></ol>
+      <p class="gd__err" data-gd="err" role="alert" hidden></p>
+      <form class="gd__say" data-gd="form" hidden>
+        <label class="vh" for="gdText">Your message</label>
+        <textarea class="gd__text" id="gdText" data-gd="text" rows="2" maxlength="1000" placeholder="What do you want to build?"></textarea>
+        <input class="gd__hp" type="text" name="website" data-gd="website" tabindex="-1" autocomplete="off" aria-hidden="true">
+        <button type="submit" class="gd__send" data-gd="send">Send</button>
+        <div class="gd__sayfoot">
+          <button type="button" class="gd__more" data-gd="make-plan" hidden>Make my plan</button>
+          <a class="gd__skip" data-gd="skip" href="/projects?view=new">Skip to sign up</a>
+        </div>
+      </form>
+      <div class="gd__end" data-gd="end" hidden>
+        <button type="button" class="gd__more" data-gd="plan-again" hidden>Make my plan</button>
+        <a class="gd__go" data-gd="go" href="/projects?view=new">Sign up and get started</a>
+      </div>
+    </section>
+    <aside class="gd__plan" id="gdPlan" aria-labelledby="gdPlanH">
+      <div class="gd__planhead">
+        <h3 class="gd__planh" id="gdPlanH">Your plan</h3>
+        <button type="button" class="gd__x" data-gd="plan-close" aria-label="Back to the chat"><svg viewBox="0 0 20 20" aria-hidden="true"><path d="M5 5l10 10M15 5L5 15"/></svg></button>
+      </div>
+      <div class="gd__planbody" data-gd="plan-body"><p class="gd__planwait">When the chat ends, your guide writes your plan here.</p></div>
+      <p class="gd__saved" data-gd="saved" hidden></p>
+    </aside>
+  </div>
+</div>
+
 <footer>
   <div class="footrow">
     <p><!--apex-only:start-->A non-profit, capture-resistant commons. <!--apex-only:end-->Built by agents, on Cloud&nbsp;Bongos. <a href="https://www.npmjs.com/package/@bongos/core" target="_blank" rel="noopener">Open source</a> (<a href="https://www.gnu.org/licenses/agpl-3.0.html" target="_blank" rel="noopener">AGPL-3.0</a>).</p>
@@ -1035,6 +1091,8 @@ composition A; landing composition v3, picked by the owner 2026-08-27. No roll,
   json(API + '/me').then(function (data) {
     var me = data && (data.builder || data.me);
     if (!me || !me.github_login) return;
+    /* the start-a-project guide is for a visitor who has not signed up (task 1005275) */
+    document.querySelectorAll('[data-guide-door]').forEach(function (d) { d.removeAttribute('data-guide-door'); });
     var slot = document.getElementById('who');
     if (!slot) return;
     slot.textContent = '';
@@ -1302,6 +1360,8 @@ composition A; landing composition v3, picked by the owner 2026-08-27. No roll,
   });
 })();
 </script>
+<!-- the start-a-project guide (task 1005275) -->
+<script src="/assets/guide-scene.js"></script>
 <!-- the Artist review button: signed-in builders only (task 1004499) -->
 <script src="/assets/artist-review.js" data-hall="{{buildersOrigin}}"></script>
 </body>

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.25.15",
+  "version": "1.25.16",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.25.15",
+      "version": "1.25.16",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.25.15",
+  "version": "1.25.16",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -11807,7 +11807,19 @@
       "text": "The project guide now asks whether you are starting fresh or already have something, and for an existing project plans from your own description, without ever reading your files or code."
     }
   ],
-  "1.25.15": [
+  "1.25.16": [
+    {
+      "id": "1005110",
+      "text": "Genesis setup now shows each stage's work as a checklist that fills in as tasks ship, and a step that must wait for the one before it is clearly locked until then."
+    },
+    {
+      "id": "1005114",
+      "text": "The project's first setup step now asks the founder real questions — what they are making and why, who it is for, what success looks like in two years, and what others in the area get wrong. Answers are saved as answers, 'not"
+    },
+    {
+      "id": "1005275",
+      "text": "Visitors pressing Start a project can now talk with a game-style guide about their idea, see a plan form and their messages left, then sign up; when the guide is off it works exactly as before."
+    },
     {
       "id": "1005116",
       "text": "Founders now write their own strategy. Each setup stage can be done three ways: answer guided questions, write it freely, or get help from your own AI — and you can switch at any time without losing anything. Your answers are"

package/scripts/bongos/genesis.js

@@ -37,7 +37,9 @@ const ORIGIN_LABEL = { assisted: ' (with AI help)', carried_over: ' (carried ove
 function formatStage(s) {
   const out = [`${s.stage[0].toUpperCase()}${s.stage.slice(1)} — working ${s.door}` +
     (s.adopted ? ` · ${s.counts.answered} answered, ${s.counts.not_sure} not sure, ${s.counts.skipped} skipped, ${s.counts.empty} empty` : '')];
+  let group = null;
   for (const q of s.questions) {
+    if (q.group && q.group !== group) { group = q.group; out.push(`  — ${group} —`); }
     out.push(`  ${q.id}: ${q.ask}`);
     if (!q.answer) { out.push('    (empty)'); continue; }
     const a = q.answer;

package/src/module-api.js

@@ -81,7 +81,7 @@ const { sleep } = require('./sleep');
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.25.15'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.25.16'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/genesis_home.mjs

@@ -46,17 +46,54 @@ test('genesis files a task per stage, keyed by a ref that names the step, not it
 
 test('the seeder files every genesis step once, under the catch-all, and never twice', async () => {
   const filed = [];
+  const edges = [];
   const deps = {
     pool: { query: async () => ({ rows: [{ id: 'V1' }] }) },
-    createTask: async (row) => { filed.push(row); },
+    createTask: async (row) => { filed.push({ ...row, id: 100 + filed.length }); },
     findTaskBySourceRef: async ({ source, sourceRef }) => filed.find((r) => r.source === source && r.sourceRef === sourceRef) || null,
+    addTaskDependency: async (id, dep) => { edges.push([id, dep]); },
   };
   const first = await seed.seedGenesisStages({ builderId: 1 }, deps);
   assert.equal(first.seeded, 5);
   assert.ok(filed.every((r) => r.status === 'ready' && r.source === 'genesis' && r.allowCatchAll === true && r.versionId === 'V1'));
+  assert.deepEqual(edges, [], 'a new project: every stage has one step, nothing waits on anything');
   const again = await seed.seedGenesisStages({ builderId: 1, existing: true }, deps);
   assert.equal(again.seeded, 1, 'a second run files only the step that was not there (the brownfield one)');
   assert.equal(filed.length, 6);
+  const scope = filed.find((r) => r.sourceRef === 'genesis:scope');
+  const gather = filed.find((r) => r.sourceRef === 'genesis:scope:existing');
+  assert.deepEqual(edges, [[scope.id, gather.id]], 'writing the scope waits on gathering what exists (task 1005110)');
+});
+
+test('the checklist declares order only where it is real: brownfield scope (task 1005110)', () => {
+  const fresh = genesisChecklist({});
+  assert.ok(Object.values(fresh).flat().every((t) => t.after === null), 'a new project: all open');
+  const old = genesisChecklist({ existing: true });
+  assert.deepEqual(old.scope.map((t) => [t.ref, t.after]), [
+    ['genesis:scope:existing', null],
+    ['genesis:scope', 'genesis:scope:existing'],
+  ]);
+  for (const k of ['strategize', 'charter', 'legalize', 'legislation']) assert.equal(old[k][0].after, null);
+});
+
+test('the board read says what each task waits on, from the dependency edges (task 1005110)', async () => {
+  let seen = '';
+  const pool = { query: async (sql) => {
+    seen = sql;
+    return { rows: [
+      { id: 1, title: 'Gather', status: 'ready', description: '', source_ref: 'genesis:scope:existing', waits_on: [] },
+      { id: 2, title: 'Write', status: 'ready', description: '', source_ref: 'genesis:scope', waits_on: [{ id: 1, title: 'Gather' }] },
+    ] };
+  } };
+  const out = await seed.genesisStageTasks({ pool });
+  assert.match(seen, /FROM dependencies d/);
+  assert.match(seen, /x\.status <> 'shipped'/, 'the claim gate\'s own rule: only a shipped task stops blocking');
+  assert.deepEqual(out.scope[1].waits_on, [{ id: '1', title: 'Gather' }]);
+  const g = gh.shapeGenesis({ mode: { stage: 'scope', stage_number: 1, stage_count: 5, day: 1 }, plan: gh.parsePlan({}).plan, tasks: out });
+  assert.deepEqual(g.stages[0].tasks.map((t) => t.state), ['open', 'locked']);
+  const done = gh.shapeGenesis({ mode: { stage: 'scope', stage_number: 1, stage_count: 5, day: 1 }, plan: gh.parsePlan({}).plan,
+    tasks: { scope: [{ id: '1', title: 'Gather', status: 'shipped' }, { id: '2', title: 'Write', status: 'ready', waits_on: [] }] } });
+  assert.deepEqual(done.stages[0].tasks.map((t) => t.state), ['done', 'open'], 'once the first ships, the second opens');
 });
 
 test('the board read groups genesis tasks by the stage their ref names', async () => {
@@ -389,7 +426,7 @@ function bootCard({ founding, data = { genesis: null } }) {
   const attrs = founding ? { 'data-founding': 'on' } : {};
   const sandbox = {
     window: {
-      OTB: { escapeHtml: (s) => String(s), statusPill: (s) => `<span>${s}</span>`, contributeHallWidget: (w) => { widget = w; }, toast: (m) => toasts.push(m) },
+      OTB: { escapeHtml: (s) => String(s), statusPill: (s) => `<span>${s}</span>`, contributeHallWidget: (w) => { widget = w; }, toast: (m) => toasts.push(m), CHECK_SVG: '<svg/>' },
       BongosClient: { createClient: () => ({ request: async (m, p) => { calls.push(`${m} ${p}`); return { ok: true, status: 200, data }; } }) },
     },
     navigator: { clipboard: { writeText: async (t) => { copied.push(t); } } },
@@ -537,6 +574,37 @@ test('each open stage task has Copy prompt, and it copies the task\'s own words
   assert.match(b.toasts.join(' '), /copied/i);
 });
 
+test('the stage reads as a checklist: done, open and locked, and a locked row offers no prompt (task 1005110)', async () => {
+  const genesis = gh.shapeGenesis({
+    mode: { stage: 'scope', stage_number: 1, stage_count: 5, day: 1 },
+    plan: gh.parsePlan({}).plan,
+    tasks: { scope: [
+      { id: '301', title: 'Gather what already exists', status: 'ready', description: 'Link it.' },
+      { id: '302', title: 'Write the scope', status: 'ready', description: 'Write it.', waits_on: [{ id: '301', title: 'Gather what already exists' }] },
+    ], strategize: [{ id: '303', title: 'Strategy', status: 'shipped' }] },
+  });
+  const b = bootCard({ founding: true, data: { genesis, viewer_id: '1' } });
+  await mountClickable(b);
+  const html = b.host.innerHTML;
+  const row = (id) => html.split('<li ').find((x) => x.includes(`/task/${id}"`)) || '';
+  assert.match(row('301'), /class="genesis__task is-open"/);
+  assert.match(row('301'), /data-genesis-copy="301"/, 'the open row has Copy prompt');
+  assert.match(row('302'), /class="genesis__task is-locked"/);
+  assert.match(row('302'), /after Gather what already exists/, 'a locked row says what it waits on');
+  assert.doesNotMatch(row('302'), /data-genesis-copy/, 'a locked row offers no prompt for work it cannot claim');
+  assert.doesNotMatch(html, /is-finished|line-through/, 'nothing is drawn struck through');
+  // The "done" row: the earlier stage is not the one on screen, so check the shape directly.
+  const done = gh.shapeGenesis({ mode: { stage: 'scope', stage_number: 1, stage_count: 5, day: 1 }, plan: gh.parsePlan({}).plan,
+    tasks: { scope: [{ id: '304', title: 'Gathered', status: 'shipped' }, { id: '305', title: 'Next', status: 'ready' }] } });
+  const b2 = bootCard({ founding: true, data: { genesis: done, viewer_id: '1' } });
+  await mountClickable(b2);
+  const r304 = b2.host.innerHTML.split('<li ').find((x) => x.includes('/task/304"')) || '';
+  assert.match(r304, /class="genesis__task is-done"/);
+  assert.match(r304, /<span class="genesis__mark" aria-hidden="true"><svg/, 'done fills its circle with the hall\'s tick');
+  assert.match(r304, /class="sr-only">Done: /, 'and says so to a screen reader');
+  assert.doesNotMatch(r304, /data-genesis-copy/);
+});
+
 test('the hall carries the five life plates byte-identical to the world\'s', () => {
   const world = path.join(ROOT, 'modules', 'public-landing', 'public', 'assets', 'world');
   const hall = path.join(ROOT, 'modules', 'hall-ui', 'public', 'genesis');

package/tests/genesis_work.mjs

@@ -152,6 +152,41 @@ export async function contract(test, label, deps, A) {
     assert.match(markdown, /https:\/\/example\.com\/strategy/);
     assert.doesNotMatch(markdown, /## Scope/, 'a stage with nothing in it is left out');
   });
+
+  // ── the scope interview (task 1005114) ──
+  await test(`${label}: scope's interview is its guided door: six questions, all empty, guided first`, async () => {
+    const r = await gw.readStage('scope', deps);
+    assert.equal(r.work.door, 'guided');
+    assert.deepEqual(r.work.questions.map((q) => q.id),
+      ['what_creating', 'goal_impact', 'success_two_years', 'reach_who', 'work_with_who', 'others_wrong']);
+    assert.deepEqual([...new Set(r.work.questions.map((q) => q.group))], ['What and why', 'Who', 'The bet']);
+    assert.equal(r.work.counts.empty, 6);
+  });
+
+  await test(`${label}: scope stores answers, "not sure yet", a skip, an un-answer and a revision`, async () => {
+    await gw.setAnswer('scope', 'what_creating', { text: 'A live picture of each business you run.' }, A, deps);
+    await gw.setAnswer('scope', 'success_two_years', { state: 'not_sure', text: 'depends on whether others want it' }, A, deps);
+    await gw.setAnswer('scope', 'work_with_who', { state: 'skipped' }, A, deps);
+    await gw.setAnswer('scope', 'others_wrong', { text: 'They value a business from the outside.' }, A, deps);
+    await gw.clearAnswer('scope', 'work_with_who', A, deps);
+    let r = await gw.setAnswer('scope', 'what_creating', { text: 'A live picture of each business you run, and your worth across them.' }, A, deps);
+    assert.deepEqual(r.work.counts, { total: 6, answered: 2, not_sure: 1, skipped: 0, empty: 3 });
+    assert.equal(qOf(r, 'work_with_who').answer, null, 'un-answered is empty, not skipped');
+    const h = await gw.answerHistory('scope', 'what_creating', deps);
+    assert.equal(h.history.length, 2, 'the founder can see what the answer used to say');
+    assert.equal(h.history[1].text, 'A live picture of each business you run.');
+    r = await gw.setAnswer('scope', 'success_two_years', { text: 'Three other founders run their estate on it.' }, A, deps);
+    assert.equal(qOf(r, 'success_two_years').answer.state, 'answered', '"not sure yet" is easy to come back to');
+  });
+
+  await test(`${label}: a session planning a goal reads the scope answers, scope first`, async () => {
+    const { markdown } = await gw.readContext(deps);
+    assert.ok(markdown.indexOf('## Scope') < markdown.indexOf('## Strategize'), 'genesis order');
+    assert.match(markdown, /In a few sentences, what are you creating with this project\?\*\*\n  A live picture of each business you run, and your worth across them\./);
+    assert.match(markdown, /Three other founders run their estate on it\./);
+    assert.match(markdown, /They value a business from the outside\./);
+    assert.doesNotMatch(markdown, /Who do you want working on it with you/, 'an empty question is not printed');
+  });
 }
 
 if (import.meta.url === url.pathToFileURL(process.argv[1]).href) {
@@ -220,6 +255,20 @@ if (import.meta.url === url.pathToFileURL(process.argv[1]).href) {
     assert.equal(gw.assistPrompt('decide'), null);
   });
 
+  await test('the assisted door for scope walks the same interview, ids included, and drafts only from the answers', async () => {
+    const p = gw.assistPrompt('scope');
+    for (const q of gw.QUESTIONS.scope) assert.ok(p.includes(`[${q.id}] ${q.ask}`), `asks: ${q.id}`);
+    assert.match(p, /draft page built only from my answers/);
+  });
+
+  await test('CLI: the scope interview prints under its group headings', async () => {
+    const deps = { store: memStore() };
+    const r = await gw.readStage('scope', deps);
+    const out = formatStage(r.work);
+    assert.ok(out.indexOf('— What and why —') < out.indexOf('— Who —'));
+    assert.ok(out.indexOf('— Who —') < out.indexOf('— The bet —'));
+  });
+
   await test('question ids are unique and fit the stored shape', async () => {
     for (const [stage, qs] of Object.entries(gw.QUESTIONS)) {
       assert.ok(gw.STAGES.includes(stage));