@bongos/core 1.25.11 → 1.25.13

package/modules/front-door-guide/routes/front-door-guide-plan.js

@@ -0,0 +1,144 @@
+// modules/front-door-guide/routes/front-door-guide-plan.js — where the start-a-project chat
+// ends (task 1005273): the visitor's plan, then the chat and plan moving onto the account
+// they sign up as.
+//
+//   POST /front-door-guide/conversations/:id/plan    write (or re-read) the plan   { token, website? }
+//   POST /front-door-guide/conversations/:id/attach  put the chat on my account    { token }
+//   GET  /front-door-guide/mine                      my newest chat and its plan
+//
+// The plan is ONE structured-output call per chat (a JSON schema, never parsed prose),
+// asked once the visitor has said something; a second request re-reads the stored plan
+// and spends nothing. Its modules come only from the live catalog (context.moduleCatalog,
+// the project-creation picker's own list). It is held to the site's daily and monthly
+// budget like a reply, and its cost lands in the same ledger; it is not one of the
+// visitor's messages.
+//
+// Attaching is the sign-up hand-off's call (task 1005274): right after the visitor signs
+// in, the page that still holds the chat's token sends it here. A chat already on another
+// account is never moved. A chat nobody attaches is deleted by the retention sweep
+// (pollers/retention-sweep.js) after BONGOS_FRONT_DOOR_GUIDE_RETENTION_DAYS.
+
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const G = require('../guide');
+const P = require('../plan');
+const db = require('../db');
+const claude = require('../claude');
+const { readSettings } = require('../settings');
+const L = require('../limits');
+const C = require('../context');
+
+const log = api.logger('front-door-guide');
+const ID_RE = /^\d{1,18}$/;
+const TOKEN_RE = /^[A-Za-z0-9_-]{16,64}$/;
+
+// The words for "write my plan now", sent as the visitor's last turn of the plan call.
+const PLAN_ASK = 'Please write my first plan now, from what I have told you.';
+
+function planAnswer(conv, settings) {
+  return {
+    ok: true, mode: 'plan', plan: conv.plan, next: P.NEXT_STEP,
+    message: G.END_REASONS.planned,
+    saved: G.savedNotice(settings.retentionDays),
+    conversation: G.conversationView(conv, settings),
+  };
+}
+
+// What a signed-in builder sees of their chat: never the visitor hash.
+function mineView(conv, settings) {
+  return {
+    id: String(conv.id),
+    status: conv.status,
+    end_reason: conv.end_reason || null,
+    attached_at: conv.attached_at || null,
+    transcript: G.transcriptView(conv.messages),
+    plan: conv.plan || null,
+    ...(conv.plan ? { next: P.NEXT_STEP } : {}),
+    messages_used: Number(conv.visitor_messages) || 0,
+    max_message_chars: settings.maxMessageChars,
+  };
+}
+
+module.exports = function buildFrontDoorGuidePlanRouter() {
+  const router = express.Router();
+  let current = readSettings();
+  const fresh = (req, res, next) => { current = readSettings(); next(); };
+  const planLimit = L.makeLimiter({ windowMs: 60_000, max: () => current.messagesPerMinute, scope: 'front-door-guide-plan' });
+
+  // rank: public — the visitor has no account yet.
+  router.post('/front-door-guide/conversations/:id/plan', fresh, planLimit, api.asyncHandler('POST /front-door-guide/conversations/:id/plan', async (req, res) => {
+    if (api.validateOrRespond(req, res, {
+      token: { required: true, type: 'string', maxLength: 64 },
+      website: { type: 'string', maxLength: 500 },
+    })) return;
+    const s = current;
+    const body = req.body || {};
+    if (!ID_RE.test(String(req.params.id)) || !TOKEN_RE.test(body.token)) return res.status(400).json({ ok: false, error: 'bad_request' });
+    const conv = await db.getConversation(req.params.id, L.tokenHash(body.token));
+    if (!conv) return res.status(404).json({ ok: false, error: 'not_found' });
+    if (conv.plan) return res.json(planAnswer(conv, s));
+    if (!(Number(conv.visitor_messages) > 0)) return res.status(409).json({ ok: false, error: 'too_early' });
+    if (G.botCheck({ body, userAgent: req.get('user-agent'), now: Date.now(), minFirstMessageMs: s.minFirstMessageMs })) {
+      return res.json(G.formAnswer('check_failed'));
+    }
+    if (!s.apiKey) return res.json(G.formAnswer('no_key'));
+
+    const catalog = await C.moduleCatalog();
+    const schema = P.planSchema(catalog.optional.map((m) => m.key));
+    const system = `${G.systemPrompt(C.productName())}\n\n${P.planInstructions(catalog)}`;
+    const messages = [...(conv.messages || []), { role: 'user', content: PLAN_ASK }];
+    const estimate = G.estimateMicro({ model: s.model, system: system + JSON.stringify(schema), messages, maxReplyTokens: s.maxPlanTokens });
+    const budget = await C.siteBudgetReason(s, estimate);
+    if (budget) return res.json(G.formAnswer(budget));
+
+    const visitor = conv.visitor_hash;
+    const release = C.reservations.take(visitor, estimate);
+    if (!release) return res.status(429).json({ ok: false, error: 'busy', retry_after_seconds: 2 });
+    let result;
+    try {
+      result = await claude.askGuide({ client: claude.createClient(s.apiKey), settings: s, system, messages, schema });
+    } finally {
+      release();
+    }
+    if (!result.ok) {
+      log.warn({ conversation_id: String(conv.id), error: result.error }, 'front-door-guide: plan call failed');
+      return res.json(G.formAnswer('unavailable'));
+    }
+    const u = result.usage || {};
+    const call = {
+      visitorHash: visitor, model: result.model, costMicro: G.costMicro(result.model, u), stopReason: result.stopReason || null,
+      inputTokens: Number(u.input_tokens) || 0, outputTokens: Number(u.output_tokens) || 0,
+      cacheReadTokens: Number(u.cache_read_input_tokens) || 0, cacheWriteTokens: Number(u.cache_creation_input_tokens) || 0,
+    };
+    // A refused or cut-off reply may not match the schema: it costs what it cost, and the
+    // visitor is offered the form rather than half a plan.
+    const plan = result.stopReason === 'end_turn' ? P.parsePlan(G.replyText(result.content), catalog) : null;
+    if (!plan) {
+      await db.recordPlanSpend(conv.id, call);
+      log.warn({ conversation_id: String(conv.id), stop_reason: result.stopReason }, 'front-door-guide: no usable plan');
+      return res.json(G.formAnswer('unavailable'));
+    }
+    const saved = await db.savePlan(conv.id, plan, call);
+    res.json(planAnswer(saved || { ...conv, plan }, s));
+  }));
+
+  // rank: builder — the visitor has just signed in; the chat moves onto their account.
+  router.post('/front-door-guide/conversations/:id/attach', api.requireBuilder, fresh, api.asyncHandler('POST /front-door-guide/conversations/:id/attach', async (req, res) => {
+    if (api.validateOrRespond(req, res, { token: { required: true, type: 'string', maxLength: 64 } })) return;
+    const token = req.body.token;
+    if (!ID_RE.test(String(req.params.id)) || !TOKEN_RE.test(token)) return res.status(400).json({ ok: false, error: 'bad_request' });
+    const conv = await db.attachToBuilder(req.params.id, L.tokenHash(token), req.builder.id);
+    if (!conv) return res.status(404).json({ ok: false, error: 'not_found' });
+    res.json({ ok: true, conversation: mineView(conv, current) });
+  }));
+
+  // rank: builder — my newest chat and plan (the creation wizard's pre-fill reads it).
+  router.get('/front-door-guide/mine', api.requireBuilder, fresh, api.asyncHandler('GET /front-door-guide/mine', async (req, res) => {
+    const conv = await db.latestForBuilder(req.builder.id);
+    res.json({ ok: true, conversation: conv ? mineView(conv, current) : null });
+  }));
+
+  return router;
+};

package/modules/front-door-guide/routes/front-door-guide.js

@@ -0,0 +1,196 @@
+// modules/front-door-guide/routes/front-door-guide.js — the start-a-project guide's HTTP
+// surface (task 1005272). A signed-out visitor talks with an AI guide about what they
+// want to build before signing up.
+//
+//   GET  /front-door-guide/status                     can the guide talk right now
+//   POST /front-door-guide/conversations              start a chat       { website? }
+//   POST /front-door-guide/conversations/:id/messages send one message   { token, text, website? }
+//   GET  /front-door-guide/conversations/:id          read it back       header x-guide-token
+//
+// The plan, attaching a chat to an account at sign-up, and "my plan" are in
+// routes/front-door-guide-plan.js (task 1005273).
+//
+// rank: public — every route. The visitor has no account yet; that is the point. What
+// stands in for one: per-visitor rate limits, a bot check, a token per conversation, and
+// every money cap enforced here before a call is made (the per-visitor message count and
+// spend, the site's daily and monthly budget). A spent budget or a missing key answers
+// `mode: 'form'`, never an error, so the front end always has somewhere to send the
+// visitor. The response shape is documented in ../CLAUDE.md.
+//
+// The visitor's words are never logged.
+
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const G = require('../guide');
+const db = require('../db');
+const claude = require('../claude');
+const { readSettings } = require('../settings');
+const L = require('../limits');
+const C = require('../context');
+const P = require('../plan');
+
+const log = api.logger('front-door-guide');
+const ID_RE = /^\d{1,18}$/;
+const TOKEN_RE = /^[A-Za-z0-9_-]{16,64}$/;
+
+module.exports = function buildFrontDoorGuideRouter() {
+  const router = express.Router();
+  const { reservations, siteBudgetReason, salt, productName } = C;
+  let current = readSettings();
+  const knobs = () => current;
+
+  const statusLimit = L.makeLimiter({ windowMs: 60_000, max: () => 60, scope: 'front-door-guide-read' });
+  const startLimit = L.makeLimiter({ windowMs: 3_600_000, max: () => knobs().startsPerHour, scope: 'front-door-guide-start' });
+  const messageLimit = L.makeLimiter({ windowMs: 60_000, max: () => knobs().messagesPerMinute, scope: 'front-door-guide-message' });
+  // Settings are re-read on every request, so an owner's change applies without a restart.
+  const fresh = (req, res, next) => { current = readSettings(); next(); };
+
+  // rank: public — the landing asks before it offers the chat.
+  router.get('/front-door-guide/status', fresh, statusLimit, api.asyncHandler('GET /front-door-guide/status', async (req, res) => {
+    const s = knobs();
+    const reason = !s.apiKey ? 'no_key' : await siteBudgetReason(s, 0);
+    res.json({
+      ok: true,
+      mode: reason ? 'form' : 'chat',
+      ...(reason ? { reason, message: G.FORM_REASONS[reason] } : {}),
+      limits: { max_messages: s.maxMessages, max_message_chars: s.maxMessageChars },
+    });
+  }));
+
+  // rank: public — start a chat. Answers the greeting and the conversation's token.
+  router.post('/front-door-guide/conversations', fresh, startLimit, api.asyncHandler('POST /front-door-guide/conversations', async (req, res) => {
+    if (api.validateOrRespond(req, res, { website: { type: 'string', maxLength: 500 } })) return;
+    const s = knobs();
+    const body = req.body || {};
+    if (G.botCheck({ body, userAgent: req.get('user-agent'), now: Date.now(), minFirstMessageMs: s.minFirstMessageMs })) {
+      return res.json(G.formAnswer('check_failed'));
+    }
+    if (!s.apiKey) return res.json(G.formAnswer('no_key'));
+    const budget = await siteBudgetReason(s, 0);
+    if (budget) return res.json(G.formAnswer(budget));
+    const visitor = L.visitorHash(L.clientIp(req), salt());
+    const used = await db.visitorUsage(visitor);
+    if (used.messages >= s.maxMessages || used.spendMicro >= s.visitorCapMicro) return res.json(G.formAnswer('visitor_limit'));
+    const token = L.newToken();
+    const conv = await db.createConversation(L.tokenHash(token), visitor);
+    res.status(201).json({
+      ok: true, mode: 'chat',
+      conversation: { ...G.conversationView(conv, s), token },
+      greeting: G.GREETING,
+      saved: G.savedNotice(s.retentionDays),
+    });
+  }));
+
+  // rank: public — one visitor message, one guide reply.
+  router.post('/front-door-guide/conversations/:id/messages', fresh, messageLimit, api.asyncHandler('POST /front-door-guide/conversations/:id/messages', async (req, res) => {
+    // The schema's ceiling on `text` is loose on purpose: the owner's own length limit is
+    // checked below, so a visitor hears `too_long` with the number, not a generic refusal.
+    if (api.validateOrRespond(req, res, {
+      token: { required: true, type: 'string', maxLength: 64 },
+      text: { required: true, type: 'string', maxLength: 100_000 },
+      website: { type: 'string', maxLength: 500 },
+    })) return;
+    const s = knobs();
+    const body = req.body || {};
+    if (!ID_RE.test(String(req.params.id)) || typeof body.token !== 'string' || !TOKEN_RE.test(body.token)) {
+      return res.status(400).json({ ok: false, error: 'bad_request' });
+    }
+    if (typeof body.text !== 'string' || !body.text.trim()) return res.status(400).json({ ok: false, error: 'empty' });
+    const text = body.text.trim();
+    if (text.length > s.maxMessageChars) {
+      return res.status(400).json({ ok: false, error: 'too_long', max_message_chars: s.maxMessageChars });
+    }
+    const conv = await db.getConversation(req.params.id, L.tokenHash(body.token));
+    if (!conv) return res.status(404).json({ ok: false, error: 'not_found' });
+    const view = () => G.conversationView(conv, s);
+    const ended = (reason) => ({
+      ok: true, mode: 'ended', reason, message: G.END_REASONS[reason] || G.END_REASONS.message_cap,
+      next_step: reason === 'planned' ? 'sign_up' : 'plan', conversation: view(),
+    });
+    if (conv.status === 'ended') return res.json(ended(conv.end_reason));
+
+    const bot = G.botCheck({
+      body, userAgent: req.get('user-agent'), now: Date.now(), minFirstMessageMs: s.minFirstMessageMs,
+      startedAt: new Date(conv.created_at).getTime(), firstMessage: Number(conv.visitor_messages) === 0,
+    });
+    if (bot) return res.json(G.formAnswer('check_failed'));
+    if (!s.apiKey) return res.json(G.formAnswer('no_key'));
+
+    // The visitor's caps count every chat they started today, not just this one.
+    const visitor = conv.visitor_hash;
+    if (reservations.busy(visitor)) return res.status(429).json({ ok: false, error: 'busy', retry_after_seconds: 2 });
+    const used = await db.visitorUsage(visitor);
+    if (used.messages >= s.maxMessages || Number(conv.visitor_messages) >= s.maxMessages) {
+      await db.endConversation(conv.id, 'message_cap');
+      return res.json(ended('message_cap'));
+    }
+
+    const system = G.systemPrompt(productName());
+    const messages = [...(conv.messages || []), { role: 'user', content: text }];
+    const estimate = G.estimateMicro({ model: s.model, system, messages, maxReplyTokens: s.maxReplyTokens });
+    if (used.spendMicro + estimate > s.visitorCapMicro) {
+      await db.endConversation(conv.id, 'visitor_budget');
+      return res.json(ended('visitor_budget'));
+    }
+    const budget = await siteBudgetReason(s, estimate);
+    if (budget) return res.json(G.formAnswer(budget));
+
+    const release = reservations.take(visitor, estimate);
+    if (!release) return res.status(429).json({ ok: false, error: 'busy', retry_after_seconds: 2 });
+    let result;
+    try {
+      result = await claude.askGuide({ client: claude.createClient(s.apiKey), settings: s, system, messages });
+    } finally {
+      release();
+    }
+    if (!result.ok) {
+      log.warn({ conversation_id: String(conv.id), error: result.error }, 'front-door-guide: call failed');
+      return res.json(G.formAnswer('unavailable'));
+    }
+
+    const cost = G.costMicro(result.model, result.usage);
+    const refused = result.stopReason === 'refusal';
+    const reply = refused ? G.REFUSAL_REPLY : (G.replyText(result.content) || G.EMPTY_REPLY);
+    // A declined message is not sent again on the next turn, or it would be declined again.
+    const kept = refused ? [...(conv.messages || []), { role: 'user', content: '(The visitor\'s message was declined.)' }] : messages;
+    const nextMessages = [...kept, { role: 'assistant', content: reply }];
+    let endReason = null;
+    if (Number(conv.visitor_messages) + 1 >= s.maxMessages || used.messages + 1 >= s.maxMessages) endReason = 'message_cap';
+    else if (used.spendMicro + cost >= s.visitorCapMicro) endReason = 'visitor_budget';
+    const u = result.usage || {};
+    const saved = await db.recordTurn(conv.id, { messages: nextMessages, status: endReason ? 'ended' : 'open', endReason }, {
+      visitorHash: visitor, model: result.model, costMicro: cost, stopReason: result.stopReason || null,
+      inputTokens: Number(u.input_tokens) || 0, outputTokens: Number(u.output_tokens) || 0,
+      cacheReadTokens: Number(u.cache_read_input_tokens) || 0, cacheWriteTokens: Number(u.cache_creation_input_tokens) || 0,
+    });
+    res.json({
+      ok: true,
+      mode: endReason ? 'ended' : 'chat',
+      ...(endReason ? { reason: endReason, message: G.END_REASONS[endReason], next_step: 'plan' } : {}),
+      ...(refused ? { declined: true } : {}),
+      reply: { text: reply },
+      conversation: G.conversationView(saved || { ...conv, visitor_messages: Number(conv.visitor_messages) + 1 }, s),
+    });
+  }));
+
+  // rank: public — the transcript, for the plan and the sign-up hand-off.
+  router.get('/front-door-guide/conversations/:id', fresh, statusLimit, api.asyncHandler('GET /front-door-guide/conversations/:id', async (req, res) => {
+    const token = String(req.get('x-guide-token') || '');
+    if (!ID_RE.test(String(req.params.id)) || !TOKEN_RE.test(token)) return res.status(400).json({ ok: false, error: 'bad_request' });
+    const conv = await db.getConversation(req.params.id, L.tokenHash(token));
+    if (!conv) return res.status(404).json({ ok: false, error: 'not_found' });
+    res.json({
+      ok: true,
+      conversation: { ...G.conversationView(conv, knobs()), status: conv.status, end_reason: conv.end_reason || null },
+      transcript: G.transcriptView(conv.messages),
+      plan: conv.plan || null,
+      ...(conv.plan ? { next: P.NEXT_STEP } : {}),
+      saved: G.savedNotice(knobs().retentionDays),
+      attached: conv.builder_id != null,
+    });
+  }));
+
+  return router;
+};

package/modules/front-door-guide/settings.js

@@ -0,0 +1,72 @@
+// modules/front-door-guide/settings.js — the owner's knobs for the start-a-project
+// guide (task 1005272): which model answers, how many messages and how much money one
+// visitor may use, the site's daily and monthly budget, and the per-message length.
+//
+// Every knob is configuration, read from the environment under the instance's prefix
+// (BONGOS_FRONT_DOOR_GUIDE_<NAME>, via the doorway's resolveEnv), and DEFAULTS below is
+// the one place the starting values are written. A value that is missing, blank or not
+// a usable number falls back to its default, so a typo never opens a cap wider.
+//
+// Money is integer micro-dollars (1 dollar = 1,000,000), the ai-studio convention, so
+// no budget comparison ever rounds a float. The env takes cents, which owners read.
+
+'use strict';
+
+// The starting values: the owner's settings for testing (2026-11-13).
+const DEFAULTS = Object.freeze({
+  MODEL: 'claude-opus-5-5',
+  EFFORT: 'low',                 // a short planning chat, not hard reasoning
+  MAX_MESSAGES: 8,               // visitor messages per visitor per day
+  VISITOR_CAP_CENTS: 50,         // what one visitor may spend per day
+  DAILY_BUDGET_CENTS: 200,       // the whole site, per UTC day
+  MONTHLY_BUDGET_CENTS: 2500,    // the whole site, per UTC calendar month
+  MAX_MESSAGE_CHARS: 1000,       // one visitor message
+  MAX_REPLY_TOKENS: 1500,        // one guide reply, thinking included
+  STARTS_PER_HOUR: 5,            // new conversations per visitor per hour
+  MESSAGES_PER_MINUTE: 6,        // messages per visitor per minute
+  MIN_FIRST_MESSAGE_MS: 1500,    // a person takes longer than this to type a first line
+  MAX_PLAN_TOKENS: 4000,         // the plan, thinking included
+  RETENTION_DAYS: 30,            // a chat nobody signed up for is deleted after this
+});
+
+const EFFORTS = new Set(['low', 'medium', 'high', 'xhigh', 'max']);
+const MODEL_RE = /^claude-[a-z0-9.-]{1,60}$/;
+
+function defaultResolve(suffix) {
+  return require('../../src/module-api').resolveEnv(suffix);
+}
+
+// A positive whole number from the env, or the default.
+function intKnob(read, name) {
+  const raw = read(`FRONT_DOOR_GUIDE_${name}`);
+  const n = Number(raw);
+  return raw !== undefined && raw !== '' && Number.isInteger(n) && n > 0 ? n : DEFAULTS[name];
+}
+
+// readSettings({ resolve }) → the resolved knobs, money in micro-dollars, plus the key.
+// The key is read here and only handed to the client builder; nothing returns it to a
+// browser. `resolve` is injectable so a test needs no environment.
+function readSettings({ resolve = defaultResolve } = {}) {
+  const read = (s) => { try { return resolve(s); } catch (_) { return undefined; } };
+  const model = String(read('FRONT_DOOR_GUIDE_MODEL') || '').trim();
+  const effort = String(read('FRONT_DOOR_GUIDE_EFFORT') || '').trim();
+  const key = String(read('FRONT_DOOR_GUIDE_ANTHROPIC_API_KEY') || '').trim();
+  return {
+    model: MODEL_RE.test(model) ? model : DEFAULTS.MODEL,
+    effort: EFFORTS.has(effort) ? effort : DEFAULTS.EFFORT,
+    apiKey: key || null,
+    maxMessages: intKnob(read, 'MAX_MESSAGES'),
+    visitorCapMicro: intKnob(read, 'VISITOR_CAP_CENTS') * 10_000,
+    dailyBudgetMicro: intKnob(read, 'DAILY_BUDGET_CENTS') * 10_000,
+    monthlyBudgetMicro: intKnob(read, 'MONTHLY_BUDGET_CENTS') * 10_000,
+    maxMessageChars: intKnob(read, 'MAX_MESSAGE_CHARS'),
+    maxReplyTokens: intKnob(read, 'MAX_REPLY_TOKENS'),
+    startsPerHour: intKnob(read, 'STARTS_PER_HOUR'),
+    messagesPerMinute: intKnob(read, 'MESSAGES_PER_MINUTE'),
+    minFirstMessageMs: intKnob(read, 'MIN_FIRST_MESSAGE_MS'),
+    maxPlanTokens: intKnob(read, 'MAX_PLAN_TOKENS'),
+    retentionDays: intKnob(read, 'RETENTION_DAYS'),
+  };
+}
+
+module.exports = { readSettings, DEFAULTS };

package/modules/provisioning/module.json

@@ -39,7 +39,8 @@
     "provisioning.projectPlanets",
     "provisioning.projectOwnedBy",
     "provisioning.projectPublishIdentity",
-    "provisioning.selfUpdateChannel"
+    "provisioning.selfUpdateChannel",
+    "provisioning.moduleCatalog"
   ],
   "consumes": []
 }

package/modules/provisioning/seams.js

@@ -7,6 +7,7 @@ const api = require('../../src/module-api');
 const { pool } = api;
 const provisioning = require('./provisioning');
 const { selfUpdateChannel } = require('./core-upgrade');
+const { ALWAYS_ON_CORE, optionalModules } = require('./starter-bundles');
 
 // The `provisioning.projectPublishIdentity` port (task 1003578, ADR 0247 D4): the name and
 // description the publish gate judges, for the control-plane project a hub catalog row was
@@ -44,6 +45,11 @@ async function projectPublishIdentity(db, { slug, host } = {}) {
 //     question names both halves of the ADR 0246 projection.
 //   • PROVIDES port `provisioning.projectPublishIdentity` ({ slug, host }) → { name,
 //     description } | null — see projectPublishIdentity above.
+//   • PROVIDES port `provisioning.moduleCatalog` () → { core: [key], optional: [{ key,
+//     label, summary }] } — the modules a NEW project gets and may opt into, with the
+//     owner-facing words the creation picker shows (task 1005273). The start-a-project
+//     guide recommends only from this list, so its plan can never name a module the
+//     picker does not offer. Read-only; no database.
 function registerProvisioningSeams() {
   if (api.hasProvider('provisioning.instanceState')) return;
   api.registerProvider('provisioning.instanceState', (slug) => provisioning.instanceStateForSlug(pool, slug));
@@ -51,6 +57,10 @@ function registerProvisioningSeams() {
   api.registerProvider('provisioning.projectOwnedBy', (target) => provisioning.projectOwnedBy(pool, target));
   api.registerProvider('provisioning.projectPublishIdentity', (target) => projectPublishIdentity(pool, target));
   api.registerProvider('provisioning.selfUpdateChannel', () => selfUpdateChannel(pool));
+  api.registerProvider('provisioning.moduleCatalog', () => ({
+    core: [...ALWAYS_ON_CORE],
+    optional: optionalModules().map(({ key, label, summary }) => ({ key, label, summary })),
+  }));
 }
 
 module.exports = { registerProvisioningSeams, projectPublishIdentity };

package/modules/provisioning/starter-bundles.js

@@ -82,7 +82,9 @@ const ALWAYS_ON_CORE = Object.freeze([
 // bills AI generation through Cloud Bongos's own payment processor account, so it stays on
 // the hub until a project can bring its own billing. `market-watch` sat here while it was
 // empty; task 1004938 shipped the owner's on/off switch and moved it to OPTIONAL_MODULES.
-const HUB_ONLY_MODULES = Object.freeze(['platform-identity', 'provisioning', 'npm-release', 'render-deploy', 'raise', 'ai-studio']);
+// `front-door-guide` (task 1005272) is the hub's start-a-project chat on Cloud Bongos's own
+// Anthropic key, so a new project gains nothing by switching it on.
+const HUB_ONLY_MODULES = Object.freeze(['platform-identity', 'provisioning', 'npm-release', 'render-deploy', 'raise', 'ai-studio', 'front-door-guide']);
 
 // The OPT-IN catalog as the creation picker renders it (BV1.R20, task 1002339):
 // every module an owner may actually choose, in the order the picker lists them,

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.25.11",
+  "version": "1.25.13",
   "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

@@ -11772,5 +11772,21 @@
       "id": "1005268",
       "text": "An Archon can now switch the card requirement on or off for a builder straight from the People roster."
     }
+  ],
+  "1.25.12": [
+    {
+      "id": "1005272",
+      "text": "Visitors who press start a project can now talk with an AI guide about what they want to build, with strict limits on messages and spending, and a plain form whenever the guide is unavailable."
+    },
+    {
+      "id": "1005288",
+      "text": "Decided how every project gets a sandbox: a free copy of the app that always shows the newest finished work, while the real site only changes when a person presses promote. Fake data and test keys by default. Costs the owner n"
+    }
+  ],
+  "1.25.13": [
+    {
+      "id": "1005273",
+      "text": "The project guide now ends with a written plan (with recommended features drawn only from what Bongos really offers), saves the chat so visitors can come back to it, moves it onto their account when they sign up, and deletes i"
+    }
   ]
 }

package/scripts/bongos/publish-manifest.js

@@ -78,6 +78,7 @@ const PUBLISH_ALLOWLIST = [
   'modules/render-deploy/',  // the deploy page of a project whose app deploys through Render (task 1004270). default:false. MUST be here for the npm-release reason: modules/hall-ui/ ships as one subtree, so a released core without it carries deploy.js's loader for #rd-panel with no routes behind it.
   'modules/market-watch/',   // the weekly AI market watch (task 1004935, goal 1000137). default:false and empty for now, but MUST be here: shipped is not enabled, and a released core without it answers "unknown module" to an instance that turns it on; tests/market_watch_module.mjs (publishable) also reads its manifest.
   'modules/ai-studio/',      // AI generation for artists (task 1004916, ADR 0392): keys, prepaid balance, generate. default:false.
+  'modules/front-door-guide/', // the start-a-project guide (task 1005272): a capped AI chat for a signed-out visitor on the platform's key. default:false, hub first; shipped is not enabled.
   'modules/raise/',           // the /raise investor page (task 1004847, ADR 0384) — ships in core, enabled ONLY on the hub, like platform-identity. Owner decision 2026-10-25: the whole page, its copy and starting numbers included, lives in the repo so builders can contribute to it, accepting that it publishes with the core. Secrets never do: the investor password is RAISE_PASSWORD_HASH in the instance env. default:false.
   'modules/platform-identity/', // hub identity provider (ADR 0141) — ships in core, enabled ONLY on the hub (cloudbongos.com). MUST be here or the hub's enabledModules() throws "unknown module" and provision.js's federation load MODULE_NOT_FOUNDs (task 1002235, same rationale as provisioning above). default:false — shipped ≠ enabled; a vanilla/self-hosted instance never turns it on.
   // --- neutral (customer-0) config starters + their schemas (the filled-in *.json twins are denied) ---

package/scripts/bongos/run-unit-tests.js

@@ -100,6 +100,10 @@ const INTEGRATION = new Set([
   // task 1004941: a rules proposal round-trips to a new version the weekly run's loader
   // reads, on real SQL (the one-active index, the CHECKs). DB-free sibling: market_watch_rules.
   'market_watch_rules_db',
+  // tasks 1005272/1005273: the start-a-project guide's SQL on a real engine: the migrations,
+  // the one-account attach rule, and the retention sweep keeping spend on the books.
+  // DB-free siblings: front_door_guide, front_door_guide_plan.
+  'front_door_guide_db',
   // task 1004940: the weekly ask's SQL store — once per week by constraint, one pooled
   // proposal per similar answer, the project guard on an answer. DB-free sibling:
   // market_watch_ask.

package/src/bongos/module-scope-map.js

@@ -186,6 +186,12 @@ const MODULE_GLOBS = {
   'ai-studio': [
     'modules/ai-studio/',
   ],
+  // The start-a-project guide (task 1005272, goal 1000106): a capped AI chat for a
+  // signed-out visitor. Its test sits at the repo root, listed by exact path.
+  'front-door-guide': [
+    'modules/front-door-guide/', 'tests/front_door_guide.mjs',
+    'tests/front_door_guide_plan.mjs', 'tests/front_door_guide_db.mjs',
+  ],
   // The /raise investor page (task 1004847, ADR 0384): hub-only.
   raise: [
     'modules/raise/',

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.11'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.25.13'; // 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');