create-kai 0.1.4 → 0.2.1

package/README.md

@@ -15,8 +15,17 @@ history + the kit's local mock: a project that streams a reply on the first
 
 **First slice of v1.** A `ready` framework has been scaffolded, installed from
 the registry, built by its own build script, and driven in a browser — a message
-sent, and a reply streaming into `<kai-thread>`. Remaining frameworks, layouts
-and gateways are declared in the tables but not offered.
+sent, and a reply streaming into `<kai-thread>`. Remaining frameworks, layouts,
+features and gateways are declared in the tables but not offered.
+
+**The prompt offers only what scaffolds, and states the rest.** One surface runs
+today — the hand-composed workspace, with conversation history — so the CLI says
+so rather than showing a menu of six and refusing five of them after the last
+question. Where an axis has one possible answer it is stated, not asked, and
+`--features <id>` for anything unavailable fails immediately with what IS
+available, before a file is written. `test/menu-honesty.test.ts` drives every
+option the prompt offers through `generate()`, so a menu item that cannot be
+scaffolded fails a test rather than a user.
 
 **`create-kai --list` is the roster.** This paragraph used to name which
 frameworks were ready, and it was wrong within a day of each one landing — so

package/dist/index.js

@@ -789,6 +789,29 @@ ${import_picocolors2.default.gray(d2)}  ${t}
 
 `);
 };
+var M2 = { message: (t = "", { symbol: n = import_picocolors2.default.gray(o) } = {}) => {
+  const r2 = [`${import_picocolors2.default.gray(o)}`];
+  if (t) {
+    const [i, ...s] = t.split(`
+`);
+    r2.push(`${n}  ${i}`, ...s.map((c) => `${import_picocolors2.default.gray(o)}  ${c}`));
+  }
+  process.stdout.write(`${r2.join(`
+`)}
+`);
+}, info: (t) => {
+  M2.message(t, { symbol: import_picocolors2.default.blue(q) });
+}, success: (t) => {
+  M2.message(t, { symbol: import_picocolors2.default.green(D) });
+}, step: (t) => {
+  M2.message(t, { symbol: import_picocolors2.default.green(C) });
+}, warn: (t) => {
+  M2.message(t, { symbol: import_picocolors2.default.yellow(U) });
+}, warning: (t) => {
+  M2.warn(t);
+}, error: (t) => {
+  M2.message(t, { symbol: import_picocolors2.default.red(K2) });
+} };
 var J2 = `${import_picocolors2.default.gray(o)}  `;
 var Y2 = ({ indicator: t = "dots" } = {}) => {
   const n = V2 ? ["\u25D2", "\u25D0", "\u25D3", "\u25D1"] : ["\u2022", "o", "O", "0"], r2 = V2 ? 80 : 120, i = process.env.CI === "true";
@@ -856,7 +879,13 @@ var openai = {
   // Both model and tools come from the browser. \`tools\` is undefined unless the
   // front end declared any, and JSON.stringify drops it, so the same handler
   // serves a tool archetype and a plain chat.
-  const { model, messages, tools } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { model, messages, tools } = chatBody;
 
   const upstream = await fetch('https://api.openai.com/v1/chat/completions', {
     method: 'POST',
@@ -1223,7 +1252,13 @@ function reframeToOpenAISse(body: ReadableStream<Uint8Array>): ReadableStream<Ui
 async function chatHandler(request: Request): Promise<Response> {
   // Both model and tools come from the browser. \`tools\` arrives in OpenAI
   // function form and is converted to this API's shape below.
-  const { model, messages, tools } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { model, messages, tools } = chatBody;
   const { system, messages: anthropicMessages } = toAnthropicBody(messages);
   const anthropicTools = toAnthropicTools(tools);
 
@@ -1353,7 +1388,13 @@ var openrouter = {
   webRoute: `async function chatHandler(request: Request): Promise<Response> {
   // tools is undefined unless the front end sent one; JSON.stringify drops it,
   // so the same handler serves a tool archetype and a plain chat.
-  const { model, messages, tools } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { model, messages, tools } = chatBody;
 
   const upstream = await fetch('https://openrouter.ai/api/v1/chat/completions', {
     method: 'POST',
@@ -1582,7 +1623,13 @@ const FINISH_REASONS: Record<string, string> = {
 };
 
 async function chatHandler(request: Request): Promise<Response> {
-  const { messages, tools } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { messages, tools } = chatBody;
   const toolSet = toToolSet(tools);
   const prompt = toModelMessages(messages);
 
@@ -1833,7 +1880,13 @@ const agent = createReactAgent({
 
 // Stream a compiled LangGraph agent to the browser as OpenAI-format SSE.
 async function chatHandler(request: Request): Promise<Response> {
-  const { messages } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { messages } = chatBody;
 
   // agent.stream() coerces plain {role, content} objects into BaseMessage
   // instances itself, including OpenAI-shaped tool_calls, so the wire messages
@@ -1952,9 +2005,44 @@ import type { OpenAIWireMessage } from '@kitn.ai/ui/wire';
  */
 type ChatRequestBody = { messages: OpenAIWireMessage[] };
 
+class ChatRequestError extends Error {
+  constructor(readonly status: number, message: string) { super(message); }
+}
+
+/** Narrow the JSON body once, at the edge. A bare GET, a malformed body, or a
+ *  missing messages array is a ChatRequestError with a status \u2014 NEVER an
+ *  unhandled SyntaxError (findings F-10). */
+async function readChatRequest(request: Request): Promise<ChatRequestBody> {
+  if (request.method !== 'POST') {
+    throw new ChatRequestError(405, \`Method \${request.method} not allowed \u2014 POST /api/chat.\`);
+  }
+  let parsed: unknown;
+  try { parsed = await request.json(); } catch {
+    throw new ChatRequestError(400, 'Request body is not valid JSON.');
+  }
+  const body = parsed as ChatRequestBody;
+  if (!Array.isArray(body?.messages)) {
+    throw new ChatRequestError(400, 'Request body must carry a messages array.');
+  }
+  return body;
+}
+
+/** Map a guard rejection to the Response its status demands; rethrow anything
+ *  else \u2014 an unexpected error should be loud, not laundered into a 400. */
+function toChatErrorResponse(error: unknown): Response {
+  if (error instanceof ChatRequestError) return Response.json({ error: error.message }, { status: error.status });
+  throw error;
+}
+
 export default {
   async fetch(req: Request, env: Env): Promise<Response> {
-    const { messages } = (await req.json()) as ChatRequestBody;
+    let chatBody: ChatRequestBody;
+    try {
+      chatBody = await readChatRequest(req);
+    } catch (error) {
+      return toChatErrorResponse(error);
+    }
+    const { messages } = chatBody;
 
     let nativeStream: ReadableStream<Uint8Array>;
     try {
@@ -2029,7 +2117,13 @@ export default {
   },
   webRoute: `async function chatHandler(request: Request): Promise<Response> {
   // Proxy Workers AI over its OpenAI-compatible HTTP endpoint, token server-side.
-  const { messages } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { messages } = chatBody;
 
   const upstream = await fetch(
     \`https://api.cloudflare.com/client/v4/accounts/\${process.env.CF_ACCOUNT_ID}/ai/v1/chat/completions\`,
@@ -2123,7 +2217,13 @@ var ollama = {
   // The model is pinned here, not sent by the browser. tools IS forwarded:
   // it is undefined unless the front end declared any, and JSON.stringify
   // drops it, so the same handler serves a tool archetype and a plain chat.
-  const { messages, tools } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { messages, tools } = chatBody;
 
   const upstream = await fetch('http://localhost:11434/v1/chat/completions', {
     method: 'POST',
@@ -2220,7 +2320,13 @@ const mastra = new MastraClient({ baseUrl: MASTRA_URL });
 
 // Proxy a Mastra agent to the browser as OpenAI-format SSE.
 async function chatHandler(request: Request): Promise<Response> {
-  const { messages } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { messages } = chatBody;
 
   // MastraClient's Agent.stream() takes AI-SDK CoreMessage[], not the OpenAI
   // wire format: each message has ONE literal role (not a union) and content
@@ -2387,9 +2493,64 @@ import type { OpenAIWireMessage } from '@kitn.ai/ui/wire';
 const app = express();
 app.use(express.json());
 
+class ChatRequestError extends Error {
+  constructor(readonly status: number, message: string) { super(message); }
+}
+
+/** Narrow the JSON body once, at the edge. A bare GET or a missing messages
+ *  array is a ChatRequestError with a status \u2014 NEVER an unhandled throw
+ *  (findings F-10). Malformed JSON is rejected upstream by express.json(),
+ *  which the error handler below turns into a JSON 400. */
+function readChatRequest(req: express.Request): { messages: OpenAIWireMessage[] } {
+  if (req.method !== 'POST') {
+    throw new ChatRequestError(405, \`Method \${req.method} not allowed \u2014 POST /api/chat.\`);
+  }
+  const body = (req.body ?? {}) as { messages?: OpenAIWireMessage[] };
+  if (!Array.isArray(body.messages)) {
+    throw new ChatRequestError(400, 'Request body must carry a messages array.');
+  }
+  return body as { messages: OpenAIWireMessage[] };
+}
+
+/** Map a guard rejection to the response its status demands; rethrow anything
+ *  else \u2014 an unexpected error should be loud, not laundered into a 400. */
+function toChatErrorResponse(error: unknown, res: express.Response): void {
+  if (error instanceof ChatRequestError) {
+    res.status(error.status).json({ error: { message: error.message } });
+    return;
+  }
+  throw error;
+}
+
+// express.json() rejects a malformed body at the MIDDLEWARE level, before any
+// handler runs \u2014 without this it surfaces as Express's default HTML error page.
+app.use(
+  (
+    err: { status?: number; message?: string },
+    _req: express.Request,
+    res: express.Response,
+    _next: express.NextFunction,
+  ) => {
+    res.status(err?.status ?? 500).json({ error: { message: err?.message ?? 'Request failed.' } });
+  },
+);
+
+// A bare GET is a 405 with the method named, not Express's default 404 \u2014
+// the resource exists, the verb is wrong.
+app.get('/api/chat', (_req, res) => {
+  res.status(405).json({ error: { message: 'Method not allowed \u2014 POST /api/chat.' } });
+});
+
 // POST /api/chat: bridge a Pi RPC session to the browser as SSE.
 app.post('/api/chat', (req, res) => {
-  const { messages } = req.body as { messages: OpenAIWireMessage[] };
+  let chatBody: { messages: OpenAIWireMessage[] };
+  try {
+    chatBody = readChatRequest(req);
+  } catch (error) {
+    toChatErrorResponse(error, res);
+    return;
+  }
+  const { messages } = chatBody;
   const last = messages.at(-1)?.content;
   // \`content\` is a plain string until the turn carries an attachment, at which
   // point it is an ARRAY of content parts. Pi's RPC mode takes a TEXT prompt and
@@ -2600,24 +2761,86 @@ var mock = {
   streamFormat: "native",
   envVars: [],
   routeTemplates: {},
-  streamMapping: "No backend and no provider, but a real wire. createMockResponder() from @kitn.ai/ui/state yields canned SSE frames and the scaffold reads them with readOpenAIStream from @kitn.ai/ui/wire, on the same code path a real route's response takes: same reader, same part folding, same abort handling. The frames carry the OpenAI chat-completions shape because the mock stands in for your /api/chat ROUTE, not for a provider (every other integration here re-frames its provider to that shape server-side), so going live replaces ONE expression: mockResponse(value) becomes the awaited response from your own chat route, and nothing else in the handler changes. Nothing here can be mistaken for a real turn: the stream opens with a ': kai-mock' SSE comment, every frame carries a _kai_mock field naming createMockResponder, model reports as 'kai-mock' (no provider serves it), and usage is all zeros.",
-  runNote: "No backend or API key needed: the reply is generated in the browser and parsed by the same reader a real route feeds. Run the front-end as-is; swap `integration` for a real provider (openai, anthropic, openrouter, ollama) when ready, and the emitted handler differs by one expression.",
+  webRoute: `import { createMockResponder } from '@kitn.ai/ui/state';
+
+// The kit's own mock responder \u2014 no provider, no key, no upstream. MODULE
+// scope, not per-request: the responder owns the cursor into its canned
+// replies, so rebuilding it per turn would answer with the first one forever.
+const mockResponse = createMockResponder();
+
+async function chatHandler(request: Request): Promise<Response> {
+  // The responder cycles its replies whatever you send, so the prompt is a
+  // courtesy \u2014 but the body is still read exactly the way a real route reads
+  // it, so swapping this handler for a provider's changes nothing upstream of
+  // this file.
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { messages } = chatBody;
+  const last = [...messages].reverse().find((m) => m.role === 'user');
+  const prompt = last && typeof last.content === 'string' ? last.content : '';
+
+  // createMockResponder() yields COMPLETE OpenAI chat-completions SSE frames \u2014
+  // the same strings the front end's local preview streams \u2014 so this route only
+  // writes them out verbatim. No framing is built here; the browser parses them
+  // with readOpenAIStream from @kitn.ai/ui/wire, exactly as it would a real
+  // route's response. Every frame is marked as a mock (a ': kai-mock' banner, a
+  // _kai_mock field, model 'kai-mock', zero usage).
+  const encoder = new TextEncoder();
+  let open = true;
+  const body = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      for await (const frame of mockResponse(prompt)) {
+        // The browser hangs up when the user asks a new question mid-answer;
+        // stop producing frames rather than writing into a cancelled stream.
+        if (!open) return;
+        controller.enqueue(encoder.encode(frame));
+      }
+      controller.close();
+    },
+    cancel() {
+      open = false;
+    },
+  });
+
+  return new Response(body, {
+    status: 200,
+    headers: {
+      'Content-Type': 'text/event-stream; charset=utf-8',
+      // no-transform stops a proxy buffering the stream into one blob.
+      'Cache-Control': 'no-cache, no-transform',
+      Connection: 'keep-alive',
+      // A proxy in front of a preview build would otherwise buffer the whole
+      // stream and the reply would land all at once instead of streaming.
+      'X-Accel-Buffering': 'no',
+    },
+  });
+}`,
+  streamMapping: "No backend and no provider, but a real wire. createMockResponder() from @kitn.ai/ui/state yields canned SSE frames and the scaffold reads them with readOpenAIStream from @kitn.ai/ui/wire, on the same code path a real route's response takes: same reader, same part folding, same abort handling. The frames carry the OpenAI chat-completions shape because the mock stands in for your /api/chat ROUTE, not for a provider (every other integration here re-frames its provider to that shape server-side), so going live replaces ONE expression: mockResponse(value) becomes the awaited response from your own chat route, and nothing else in the handler changes. Nothing here can be mistaken for a real turn: the stream opens with a ': kai-mock' SSE comment, every frame carries a _kai_mock field naming createMockResponder, model reports as 'kai-mock' (no provider serves it), and usage is all zeros. Block (2) serves the same frames over HTTP as an OPTIONAL route, so the /api/chat seam can be stood up before any provider exists.",
+  runNote: "No backend or API key needed: the reply is generated in the browser and parsed by the same reader a real route feeds. Run the front-end as-is; swap `integration` for a real provider (openai, anthropic, openrouter, ollama) when ready, and the emitted handler differs by one expression. Block (2) is the OPTIONAL server half: the same mock frames served over HTTP, for standing up the /api/chat seam before any provider exists.",
   docsSlug: "integrations/mock",
-  // Nothing: there is no HTTP request at all. The frames are produced in-process
-  // by createMockResponder(), so there is no body to forward a model or a tools
-  // array on, and no route that would read one.
+  // Nothing: the front end makes no HTTP request at all, and the optional route
+  // reads only `messages` — and only as a courtesy prompt the responder is free
+  // to ignore. There is no model to pick and no tools array anything would run.
   forwardsFromClient: [],
-  // Nothing to install: there is no route to install anything for.
+  // Nothing to install: the route's one import is the kit itself, which every
+  // scaffold already depends on (registry.test.ts pins deps.npm to the route's
+  // imports minus @kitn.ai/ui).
   deps: { npm: [], pip: [] },
-  // The other 'frontend-safe' entry, and the only one that is true by absence:
-  // no routeTemplates, no webRoute, no envVars. There is no request, no upstream
-  // and no secret, so there is nothing a public bundle could give away. This is
-  // the one place where "declares nothing" genuinely means safe — which is
-  // precisely why it still has to SAY so rather than be left blank.
+  // The other 'frontend-safe' entry. The route now exists (G-04) but changes
+  // nothing here: it holds no credential, sends no auth header and reaches no
+  // upstream, so there is still nothing a public bundle could give away. The
+  // schema's own refinement re-checks that claim against the route source.
   keyExposure: "frontend-safe",
-  // Nothing at all, and here that is the literal truth rather than a shorthand:
-  // there is no route, no upstream and no process. This is the "No backend"
-  // group of create-kai's gateway prompt all by itself.
+  // Nothing to supply out of band: no upstream, no process, no runtime. The
+  // route is optional — the emitted app streams locally without it — which is
+  // what keeps mock in the "No backend" group of create-kai's gateway prompt
+  // (listGatewayGroups derives that from frontend-safe + outOfBand 'none', not
+  // from the absence of a route, precisely because this route is one nobody
+  // NEEDS).
   outOfBand: "none"
 };
 var mock_default = mock;
@@ -2652,9 +2875,41 @@ var archetypes = [
     defaultPlacement: "side",
     docsSlug: "examples/agentic-assistant"
   },
+  /**
+   * THE FIRST OFFICIAL BLOCK (recast spec 2026-08-20 § 3b; F-16).
+   *
+   * This preset used to carry `kai-artifact` + `kai-resizable` — an UNWIRED
+   * artifact split — while omitting the conversation rail, the one thing its
+   * name promised (rung-3 finding F-16). It now names the workspace BLOCK: the
+   * chat-agnostic `kai-workspace` layout shell, a WIRED `kai-conversations`
+   * rail, `kai-chat` in the main region, and the `@kitn.ai/ui/state` thread
+   * helpers (bindThreadMessages / createThreadSessions / createSaveScheduler /
+   * parseStoredThread) with the persistence POLICY left in consumer-owned
+   * lines. `examples/apps/workspace/` is the block's reference implementation.
+   *
+   * The artifact split did not vanish — it moved to `artifact-split` below, so
+   * its renderer branch keeps its cells in `verify:scaffold`.
+   */
   {
     id: "workspace",
     title: "Agentic workspace",
+    components: ["kai-chat", "kai-workspace", "kai-conversations"],
+    defaultPlacement: "full-page",
+    docsSlug: "examples/workspace"
+  },
+  /**
+   * THE PRESET THAT KEEPS A CAPABILITY ON THE AXIS — the same reason the
+   * `attachments` preset exists (see its comment below): `listCapabilityGroups`
+   * derives the gate's surface axis from this table, so when the recast moved
+   * the artifact pair off `workspace`, this entry is what kept
+   * `kai-artifact`+`kai-resizable` compiling in `verify:scaffold` instead of
+   * silently losing every cell. The pair is ONE capability because `isArtifactSplit`
+   * in scaffold.ts requires both: a split with no preview pane is an empty
+   * panel, and a preview with no split has nowhere to sit.
+   */
+  {
+    id: "artifact-split",
+    title: "Artifact preview split",
     components: ["kai-chat", "kai-artifact", "kai-resizable"],
     defaultPlacement: "side",
     docsSlug: "examples/workspace"
@@ -2765,9 +3020,33 @@ var CHAT_REQUEST_BODY_DECL = [
   `  tools?: unknown[];`,
   `};`,
   ``,
-  `/** Narrow the JSON body once, at the edge. */`,
+  `class ChatRequestError extends Error {`,
+  `  constructor(readonly status: number, message: string) { super(message); }`,
+  `}`,
+  ``,
+  `/** Narrow the JSON body once, at the edge. A bare GET, a malformed body, or a`,
+  ` *  missing messages array is a ChatRequestError with a status \u2014 NEVER an`,
+  ` *  unhandled SyntaxError: one killed a Vite dev server (findings F-10). */`,
   `async function readChatRequest(request: Request): Promise<ChatRequestBody> {`,
-  `  return (await request.json()) as ChatRequestBody;`,
+  `  if (request.method !== 'POST') {`,
+  `    throw new ChatRequestError(405, \`Method \${request.method} not allowed \u2014 POST /api/chat.\`);`,
+  `  }`,
+  `  let parsed: unknown;`,
+  `  try { parsed = await request.json(); } catch {`,
+  `    throw new ChatRequestError(400, 'Request body is not valid JSON.');`,
+  `  }`,
+  `  const body = parsed as ChatRequestBody;`,
+  `  if (!Array.isArray(body?.messages)) {`,
+  `    throw new ChatRequestError(400, 'Request body must carry a messages array.');`,
+  `  }`,
+  `  return body;`,
+  `}`,
+  ``,
+  `/** Map a guard rejection to the Response its status demands; rethrow anything`,
+  ` *  else \u2014 an unexpected error should be loud, not laundered into a 400. */`,
+  `function toChatErrorResponse(error: unknown): Response {`,
+  `  if (error instanceof ChatRequestError) return Response.json({ error: error.message }, { status: error.status });`,
+  `  throw error;`,
   `}`
 ];
 var CONTENT_PARTS_DECL = [
@@ -2865,6 +3144,11 @@ function rendererComponents() {
   }
   return known;
 }
+function wirableGateways(framework) {
+  return listGateways().filter(
+    (g2) => g2.wired && wirableGateway(g2.integration.id, framework) === null
+  );
+}
 function listGateways() {
   const all = listIntegrations();
   const mock2 = all.filter((i) => i.id === "mock");
@@ -2926,13 +3210,16 @@ function getFeature(id) {
 var DEFAULT_FEATURES = FEATURES.filter((f) => f.default).map(
   (f) => f.id
 );
+var GENERATED_SURFACES_WIRED = false;
+var GENERATED_SURFACE_GAP = "generated feature surfaces are not wired in this release \u2014 no such project has been run end to end, so emitting one would hand back an app nobody has seen work. The composed workspace is the surface that runs today";
 var COMPOSED_ONLY = /* @__PURE__ */ new Set(["conversations"]);
 function featureEmit(feature, framework) {
   if (COMPOSED_ONLY.has(feature.id)) {
     return framework.composedWorkspace ? "composed" : "unavailable";
   }
   const known = rendererComponents();
-  return feature.components.every((c) => known.has(c)) ? "renderer" : "unavailable";
+  if (!feature.components.every((c) => known.has(c))) return "unavailable";
+  return GENERATED_SURFACES_WIRED ? "renderer" : "unavailable";
 }
 function featureUnavailableReason(feature, framework) {
   if (featureEmit(feature, framework) !== "unavailable") return null;
@@ -2941,11 +3228,17 @@ function featureUnavailableReason(feature, framework) {
   }
   const known = rendererComponents();
   const missing = feature.components.filter((c) => !known.has(c));
-  return `feature '${feature.id}' cannot be emitted for ${framework.label}: no renderer branches on ${missing.join(" / ")}, so the emitted project would compile and run without the feature in it. Compose those components in a kit archetype and this resolves itself.`;
+  if (missing.length > 0) {
+    return `feature '${feature.id}' cannot be emitted for ${framework.label}: no renderer branches on ${missing.join(" / ")}, so the emitted project would compile and run without the feature in it. Compose those components in a kit archetype and this resolves itself.`;
+  }
+  return `feature '${feature.id}' cannot be emitted: ${GENERATED_SURFACE_GAP}.`;
 }
 function availableFeatures(framework) {
   return FEATURES.filter((f) => featureEmit(f, framework) !== "unavailable");
 }
+function composedWorkspaceFeatures(framework) {
+  return FEATURES.filter((f) => featureEmit(f, framework) === "composed");
+}
 function resolveSurface(featureIds, framework) {
   const chosen = [];
   for (const id of featureIds) {
@@ -2956,7 +3249,7 @@ function resolveSurface(featureIds, framework) {
     chosen.push(feature);
   }
   const composed = chosen.filter((f) => featureEmit(f, framework) === "composed");
-  if (composed.length > 0) {
+  if (composed.length > 0 || chosen.length === 0 && !GENERATED_SURFACES_WIRED) {
     if (chosen.length > composed.length) {
       const extra = chosen.filter((f) => !composed.includes(f)).map((f) => f.id);
       return {
@@ -2964,10 +3257,30 @@ function resolveSurface(featureIds, framework) {
         reason: `'${composed.map((f) => f.id).join("', '")}' comes from the hand-composed workspace template, which this release cannot combine with generated features ('${extra.join("', '")}'). Pick one or the other.`
       };
     }
-    return { ok: true, surface: { kind: "composed", features: featureIds } };
+    const emitted = composedWorkspaceFeatures(framework);
+    if (emitted.length === 0) {
+      return {
+        ok: false,
+        reason: `'${framework.label}' has no composed workspace starter, and ${GENERATED_SURFACE_GAP}. There is no surface to emit for it.`
+      };
+    }
+    const asked = new Set(featureIds);
+    return {
+      ok: true,
+      surface: {
+        kind: "composed",
+        features: emitted.map((f) => f.id),
+        unasked: emitted.filter((f) => !asked.has(f.id)).map((f) => f.id)
+      }
+    };
   }
-  const components = ["kai-chat", ...new Set(chosen.flatMap((f) => f.components))];
-  return { ok: true, surface: { kind: "generated", features: featureIds, components } };
+  return {
+    ok: true,
+    surface: { kind: "generated", features: featureIds, components: surfaceComponents(chosen) }
+  };
+}
+function surfaceComponents(chosen) {
+  return ["kai-chat", ...new Set(chosen.flatMap((f) => f.components))];
 }
 
 // src/routes.ts
@@ -3456,6 +3769,75 @@ function validateProjectName(name) {
   return null;
 }
 
+// src/layouts.ts
+var LAYOUTS = [
+  {
+    id: "full-screen",
+    label: "Full-screen app",
+    hint: "the chat is the page",
+    placement: "full-page",
+    status: "ready"
+  },
+  {
+    id: "widget",
+    label: "Embedded widget",
+    hint: "the chat sits on top of an existing page",
+    placement: "docked-widget",
+    // A widget has no composed-workspace starter — it is a generated surface at
+    // `docked-widget` placement — so it lands on the same unwired path the
+    // generated features do. Offered once that path has been run.
+    status: "planned",
+    note: "needs the generated-surface path, not wired in this release"
+  }
+];
+function getLayout(id) {
+  return LAYOUTS.find((l2) => l2.id === id);
+}
+function readyLayouts() {
+  return LAYOUTS.filter((l2) => l2.status === "ready");
+}
+
+// src/axes.ts
+function decideAxis(axis) {
+  if (axis.options.length === 0) return { ask: false, only: null, statement: null };
+  if (axis.options.length > 1) return { ask: true, only: null, statement: null };
+  const only = axis.options[0];
+  const statement = axis.because.length > 0 ? `${only.label} \u2014 ${only.hint}; ${axis.because}` : null;
+  return { ask: false, only, statement };
+}
+function layoutAxis() {
+  const options = readyLayouts().map((l2) => ({ id: l2.id, label: l2.label, hint: l2.hint }));
+  return {
+    id: "layout",
+    label: "Layout",
+    question: "Where does the chat live?",
+    options,
+    because: "the only layout this release can scaffold, and `--list` shows the rest"
+  };
+}
+function gatewayAxis(framework) {
+  const options = wirableGateways(framework).map((g2) => ({
+    id: g2.integration.id,
+    label: g2.integration.id === "mock" ? "None" : g2.integration.title,
+    hint: g2.integration.id === "mock" ? "local mock, no key, no backend" : `${g2.integration.envVars.join(", ")} \u2014 a server route is scaffolded for you`
+  }));
+  return {
+    id: "gateway",
+    label: "Backend",
+    question: "Wire a model gateway?",
+    options,
+    because: `the only gateway wirable for ${framework.label} in this release. A keyed gateway needs a server route and this framework declares no destination for one, so \`--list --json\` is where to see which do`
+  };
+}
+async function answerAxis(axis, opts, io) {
+  if (opts.override !== void 0) return opts.override;
+  const decision = decideAxis(axis);
+  if (opts.nonInteractive) return decision.only?.id ?? opts.fallback;
+  if (decision.ask) return io.ask(axis, opts.initialValue ?? opts.fallback);
+  if (decision.statement) io.state(axis.label, decision.statement);
+  return decision.only?.id ?? opts.fallback;
+}
+
 // src/generate.ts
 import { cp, mkdir, mkdtemp, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
@@ -3957,10 +4339,9 @@ async function generate(plan, options = {}) {
   const surface = resolveSurface(plan.featureIds, framework);
   if (!surface.ok) throw new Error(`create-kai: ${surface.reason}`);
   if (surface.surface.kind === "generated") {
-    throw new Error(
-      "create-kai: generated feature surfaces are not wired in this release \u2014 the composed workspace (conversation history) is the path that runs today"
-    );
+    throw new Error(`create-kai: ${GENERATED_SURFACE_GAP}`);
   }
+  const emittedFeatures = surface.surface.features;
   const templateRoot = options.templateRoot ?? defaultTemplateRoot();
   const templateDir = path.join(templateRoot, framework.templateDir);
   if (!existsSync(templateDir)) {
@@ -3995,7 +4376,7 @@ async function generate(plan, options = {}) {
     const routeFiles = await writeGateway(plan, framework, integration, out, thread);
     await writeFile(
       path.join(out, "kai.json"),
-      stringifyKaiJson(buildKaiJson(plan, framework)),
+      stringifyKaiJson(buildKaiJson({ ...plan, featureIds: emittedFeatures }, framework)),
       "utf8"
     );
     await writeFile(
@@ -4180,34 +4561,6 @@ async function listFiles(dir, prefix = "") {
   return out.sort();
 }
 
-// src/layouts.ts
-var LAYOUTS = [
-  {
-    id: "full-screen",
-    label: "Full-screen app",
-    hint: "the chat is the page",
-    placement: "full-page",
-    status: "ready"
-  },
-  {
-    id: "widget",
-    label: "Embedded widget",
-    hint: "the chat sits on top of an existing page",
-    placement: "docked-widget",
-    // A widget has no composed-workspace starter — it is a generated surface at
-    // `docked-widget` placement — so it lands on the same unwired path the
-    // generated features do. Offered once that path has been run.
-    status: "planned",
-    note: "needs the generated-surface path, not wired in this release"
-  }
-];
-function getLayout(id) {
-  return LAYOUTS.find((l2) => l2.id === id);
-}
-function readyLayouts() {
-  return LAYOUTS.filter((l2) => l2.status === "ready");
-}
-
 // src/pm.ts
 var KNOWN = {
   npm: { name: "npm", install: ["npm", "install"], run: "npm run dev" },
@@ -4222,7 +4575,10 @@ function detectPackageManager(userAgent = process.env.npm_config_user_agent) {
 }
 
 // src/index.ts
-var DEFAULT_KIT_RANGE = "^0.25.2";
+var OFFERABLE_FEATURE_IDS = [
+  ...new Set(readyFrameworks().flatMap((f) => availableFeatures(f).map((feature) => feature.id)))
+];
+var DEFAULT_KIT_RANGE = "^0.27.0";
 var HELP = `
 ${import_picocolors3.default.bold("create-kai")} \u2014 scaffold a runnable @kitn.ai/ui chat app
 
@@ -4232,7 +4588,7 @@ ${import_picocolors3.default.bold("create-kai")} \u2014 scaffold a runnable @kit
 Options
   --framework <id>     ${readyFrameworks().map((f) => f.id).join(", ")}
   --layout <id>        ${readyLayouts().map((l2) => l2.id).join(", ")}
-  --features <a,b>     ${FEATURES.map((f) => f.id).join(", ")}  (or 'none')
+  --features <a,b>     ${OFFERABLE_FEATURE_IDS.join(", ")}  (or 'none')
   --gateway <id>       none${[...WIRED_GATEWAYS].filter((g2) => g2 !== "mock").map((g2) => `, ${g2}`).join("")}
   --kit <spec>         @kitn.ai/ui spec to pin (default ${DEFAULT_KIT_RANGE})
   -y, --yes            accept every default (zero-config: React + full-screen + mock)
@@ -4253,7 +4609,7 @@ async function main() {
     return 0;
   }
   if (args.version) {
-    console.log("0.1.4");
+    console.log("0.2.1");
     return 0;
   }
   if (args.list) {
@@ -4291,45 +4647,70 @@ async function main() {
       `'${framework.id}' is not scaffoldable yet (${framework.note ?? "no template"}). Available: ${readyFrameworks().map((f) => f.id).join(", ")}`
     );
   }
-  const layoutId = args.layout ?? (nonInteractive ? ZERO_CONFIG.layout : await ask(
-    ve({
-      message: "Where does the chat live?",
-      initialValue: ZERO_CONFIG.layout,
-      options: readyLayouts().map((l2) => ({ value: l2.id, label: l2.label, hint: l2.hint }))
-    })
-  ));
+  const layouts = layoutAxis();
+  if (layouts.options.length === 0) {
+    return fail("no layout in this release can be scaffolded \u2014 this build is broken");
+  }
+  const layoutId = await answerAxis(
+    layouts,
+    { override: args.layout, nonInteractive, fallback: ZERO_CONFIG.layout },
+    clackAxisIo
+  );
   const layout = getLayout(layoutId);
   if (!layout) return fail(`unknown layout '${layoutId}'`);
   if (layout.status !== "ready") {
-    return fail(`layout '${layout.id}' is not scaffoldable yet (${layout.note ?? "no template"})`);
+    return fail(
+      `layout '${layout.id}' is not scaffoldable yet (${layout.note ?? "no template"}). Available: ${layouts.options.map((l2) => l2.id).join(", ")}`
+    );
   }
   const offered = availableFeatures(framework);
-  const featureIds = args.features ?? (nonInteractive ? DEFAULT_FEATURES.filter((id) => offered.some((f) => f.id === id)) : await ask(
+  const included = composedWorkspaceFeatures(framework);
+  const optional = offered.filter((f) => !included.includes(f));
+  const withheld = FEATURES.filter((f) => !offered.includes(f));
+  const featureIds = args.features ?? (nonInteractive || optional.length === 0 ? DEFAULT_FEATURES.filter((id) => offered.some((f) => f.id === id)) : await ask(
     fe({
       message: "Which features?",
       required: false,
-      initialValues: DEFAULT_FEATURES.filter((id) => offered.some((f) => f.id === id)),
-      options: offered.map((f) => ({ value: f.id, label: f.label, hint: f.hint }))
+      initialValues: DEFAULT_FEATURES.filter((id) => optional.some((f) => f.id === id)),
+      options: optional.map((f) => ({ value: f.id, label: f.label, hint: f.hint }))
     })
   ));
   for (const id of featureIds) {
-    if (!getFeature(id)) return fail(`unknown feature '${id}'`);
+    const feature = getFeature(id);
+    if (!feature) {
+      return fail(`unknown feature '${id}'. Available: ${featureList(offered)}`);
+    }
+    const unavailable = featureUnavailableReason(feature, framework);
+    if (unavailable) {
+      return fail(`${unavailable}
+Available for ${framework.label}: ${featureList(offered)}`);
+    }
+  }
+  const surface = resolveSurface(featureIds, framework);
+  if (!surface.ok) return fail(surface.reason);
+  if (surface.surface.kind === "composed" && surface.surface.unasked.length > 0) {
+    stated(
+      "Also included",
+      `${surface.surface.unasked.join(", ")} \u2014 the ${framework.label} starter is one reviewed tree, so it comes as a whole`
+    );
+  }
+  if (!nonInteractive) {
+    if (optional.length === 0 && included.length > 0) {
+      stated("Features", included.map((f) => `${f.label} \u2014 ${f.hint}`).join("; "));
+    }
+    if (withheld.length > 0) {
+      stated(
+        "Not offered yet",
+        `${withheld.map((f) => f.id).join(", ")} \u2014 ${import_picocolors3.default.dim("see `--list` for the whole table")}`
+      );
+    }
   }
   const gateways = listGateways();
-  const wired = gateways.filter(
-    (g2) => g2.wired && wirableGateway(g2.integration.id, framework) === null
+  const gatewayId = normalizeGateway(args.gateway) ?? await answerAxis(
+    gatewayAxis(framework),
+    { nonInteractive, fallback: ZERO_CONFIG.gateway, initialValue: ZERO_CONFIG.gateway },
+    clackAxisIo
   );
-  const gatewayId = normalizeGateway(args.gateway) ?? (nonInteractive || wired.length === 1 ? ZERO_CONFIG.gateway : await ask(
-    ve({
-      message: "Wire a model gateway?",
-      initialValue: ZERO_CONFIG.gateway,
-      options: wired.map((g2) => ({
-        value: g2.integration.id,
-        label: g2.integration.id === "mock" ? "None" : g2.integration.title,
-        hint: g2.integration.id === "mock" ? "local mock, no key, no backend" : `${g2.integration.envVars.join(", ")} \u2014 a server route is scaffolded for you`
-      }))
-    })
-  ));
   if (!gateways.some((g2) => g2.integration.id === gatewayId)) {
     return fail(`unknown gateway '${gatewayId}'`);
   }
@@ -4348,7 +4729,7 @@ async function main() {
     // which kit the CLI was built against, which stays true when `--kit` sends
     // the dependency somewhere else — the emitted files are this version's shape
     // whatever the project ends up installing.
-    kitBuiltAgainst: "0.25.2"
+    kitBuiltAgainst: "0.27.0"
   };
   const spinner = Y2();
   spinner.start("Scaffolding");
@@ -4405,6 +4786,22 @@ function fail(message) {
   xe(import_picocolors3.default.red(message));
   return 1;
 }
+function stated(label, value) {
+  M2.info(`${import_picocolors3.default.dim(`${label}:`)} ${value}`);
+}
+var clackAxisIo = {
+  ask: (axis, initialValue) => ask(
+    ve({
+      message: axis.question,
+      initialValue,
+      options: axis.options.map((o2) => ({ value: o2.id, label: o2.label, hint: o2.hint }))
+    })
+  ),
+  state: stated
+};
+function featureList(features) {
+  return features.length > 0 ? features.map((f) => f.id).join(", ") : "none";
+}
 function run(command, cwd) {
   return new Promise((resolve) => {
     const child = spawn(command[0], command.slice(1), { cwd, stdio: "ignore", shell: false });
@@ -4414,12 +4811,12 @@ function run(command, cwd) {
 }
 function printMatrix(asJson) {
   const matrix = {
-    cli: "0.1.4",
+    cli: "0.2.1",
     kit: DEFAULT_KIT_RANGE,
     // The same pair `kai.json` carries. An agent reading this to decide what to
     // install gets the range; one reasoning about which kit the templates match
     // gets the exact version, without having to parse the range for a floor.
-    kitBuiltAgainst: "0.25.2",
+    kitBuiltAgainst: "0.27.0",
     frameworks: FRAMEWORKS.map((f) => ({
       id: f.id,
       label: f.label,
@@ -4433,7 +4830,16 @@ function printMatrix(asJson) {
       ...f.note ? { note: f.note } : {}
     })),
     layouts: LAYOUTS.map((l2) => ({ id: l2.id, status: l2.status, ...l2.note ? { note: l2.note } : {} })),
-    features: FEATURES.map((f) => ({ id: f.id, components: f.components, default: f.default })),
+    features: FEATURES.map((f) => ({
+      id: f.id,
+      components: f.components,
+      default: f.default,
+      // Derived, never restated — and the field the six-item menu needed: the
+      // ready frameworks whose prompt actually offers this feature. An empty
+      // array means the row is catalogued and cannot be scaffolded by anything,
+      // which is what an agent reading this has to be able to see.
+      frameworks: readyFrameworks().filter((framework) => availableFeatures(framework).includes(f)).map((framework) => framework.id)
+    })),
     gateways: listGateways().map((g2) => ({
       id: g2.integration.id,
       title: g2.integration.title,
@@ -4461,6 +4867,12 @@ function printMatrix(asJson) {
   for (const l2 of matrix.layouts) {
     console.log(`  ${mark(l2.status === "ready")} ${l2.id.padEnd(16)}${l2.note ?? ""}`);
   }
+  console.log(import_picocolors3.default.bold("\nFeatures"));
+  for (const f of matrix.features) {
+    console.log(
+      `  ${mark(f.frameworks.length > 0)} ${f.id.padEnd(16)}${f.frameworks.length > 0 ? "" : "not scaffoldable in this release"}`
+    );
+  }
   console.log(import_picocolors3.default.bold("\nGateways"));
   for (const g2 of matrix.gateways) {
     console.log(`  ${mark(g2.wired)} ${g2.id.padEnd(16)}${g2.envVars.join(", ")}`);

package/dist/templates/nextjs/app/components/ThreadView.tsx

@@ -19,6 +19,13 @@ interface ThreadViewProps {
  * is that same channel repeated: a NEW array reference per chunk, which is why
  * mutating the existing array in place would render nothing.
  *
+ * The full rule is BOTH halves, and streaming only satisfies them by accident:
+ * the fresh array is what notifies, and a new object for the message that changed
+ * is what makes the change visible (the row list is a reference-keyed `<For>`).
+ * `createAssistantStream` rebuilds the streaming message as a new object every
+ * delta, so streaming gets the second half for free — editing a message or a
+ * conversation title by hand does not. See the framework guide.
+ *
  * This component just bakes the per-message actions onto the assistant turns and
  * wires the custom `speak` action to the browser's speech synthesis. `copy` (and
  * the feedback votes) are handled inside the element.

package/dist/templates/tanstack-start/src/components/ThreadView.tsx

@@ -19,6 +19,13 @@ interface ThreadViewProps {
  * is that same channel repeated: a NEW array reference per chunk, which is why
  * mutating the existing array in place would render nothing.
  *
+ * The full rule is BOTH halves, and streaming only satisfies them by accident:
+ * the fresh array is what notifies, and a new object for the message that changed
+ * is what makes the change visible (the row list is a reference-keyed `<For>`).
+ * `createAssistantStream` rebuilds the streaming message as a new object every
+ * delta, so streaming gets the second half for free — editing a message or a
+ * conversation title by hand does not. See the framework guide.
+ *
  * This component just bakes the per-message actions onto the assistant turns and
  * wires the custom `speak` action to the browser's speech synthesis. `copy` (and
  * the feedback votes) are handled inside the element.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-kai",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "type": "module",
   "description": "Scaffold a runnable @kitn.ai/ui chat app. `npm create kai@latest`",
   "license": "MIT",