@kitn.ai/ui 0.21.0 → 0.22.1

package/dist/mcp.es.js

@@ -737,14 +737,14 @@ Call component_reference with no name (or name: "list") to list all ${all.length
       lines.push(`- **${slot.name}**${desc ? ` — ${desc}` : ""}`);
     }
   }
-  const parts = el.cssParts ?? [];
-  if (parts.length > 0) {
+  const parts2 = el.cssParts ?? [];
+  if (parts2.length > 0) {
     lines.push(
       "",
       "### Styleable parts (`::part`)",
       "Restyle these from outside the Shadow DOM via `" + tag + "::part(name) { … }`."
     );
-    for (const part of parts) {
+    for (const part of parts2) {
       const desc = part.description?.trim() ?? "";
       lines.push(`- **${part.name}**${desc ? ` — ${desc}` : ""}`);
       if (part.recipe) {
@@ -805,12 +805,15 @@ const StreamFormat = z$1.enum(["openai-sse", "ai-sdk", "native"]);
 const Framework = z$1.enum(["html", "react", "next", "vue", "svelte", "angular", "solid", "fastapi", "express", "worker", "tanstack-start"]);
 const Placement = z$1.enum(["side", "full-page", "docked-widget", "inline"]);
 const KeyExposure = z$1.enum(["frontend-safe", "needs-proxy"]);
+const OutOfBand = z$1.enum(["none", "local-server", "local-binary", "language-runtime"]);
 const DepsSchema = z$1.object({
   npm: z$1.array(z$1.string()).default([]),
   pip: z$1.array(z$1.string()).default([])
 });
 const SECRET_ENV_VAR = /(?:KEY|TOKEN|SECRET|PASSWORD)$/;
 const AUTH_HEADER = /Authorization\s*:|['"]x-api-key['"]\s*:/i;
+const LOOPBACK_FETCH = /\b(?:fetch|URL)\s*\(\s*['"`]https?:\/\/(?:localhost|127\.0\.0\.1)/;
+const SPAWNS_PROCESS = /\bfrom\s+['"]node:child_process['"]|\bspawn\s*\(/;
 z$1.object({
   id: z$1.string(),
   title: z$1.string(),
@@ -897,7 +900,14 @@ z$1.object({
    * failed, so a plain required field would report "Invalid input" and this is
    * the one field where the reader needs to be told what is at stake.
    */
-  keyExposure: KeyExposure.optional()
+  keyExposure: KeyExposure.optional(),
+  /**
+   * See {@link OutOfBand}. Optional in the TYPE only so the refinement below owns
+   * the error message — Zod skips refinements when the base object already
+   * failed, so a plain required field would report "Invalid input" and this is a
+   * field whose reader needs to be told what the four values mean.
+   */
+  outOfBand: OutOfBand.optional()
 }).superRefine((integration, ctx) => {
   if (integration.forwardsFromClient.includes("tools") && integration.clientToolFormat === void 0) {
     ctx.addIssue({
@@ -934,6 +944,40 @@ z$1.object({
       });
     }
   }
+  if (integration.outOfBand === void 0) {
+    ctx.addIssue({
+      code: z$1.ZodIssueCode.custom,
+      path: ["outOfBand"],
+      message: `integration '${integration.id}' declares no outOfBand. State what the developer must supply BEYOND an install and a key, because that is the group create-kai's gateway prompt puts it in: 'none' (a remote endpoint, or the agent runs inside the route), 'local-server' (a process must already be listening, e.g. 'ollama serve'), 'local-binary' (an executable on PATH that the route spawns), or 'language-runtime' (the emitted backend needs a runtime the JS toolchain does not provide, e.g. python + uvicorn). Read the route and the runNote to decide, not the category: 'provider' holds both openai and ollama. There is no default on purpose — a missing value read as 'none' is a scaffold that says "npm run dev" to someone who has nothing to connect to.`
+    });
+  }
+  if (integration.outOfBand === "none") {
+    const routeSources = [
+      ...Object.values(integration.routeTemplates),
+      ...integration.webRoute ? [integration.webRoute] : []
+    ];
+    if (integration.language === "python") {
+      ctx.addIssue({
+        code: z$1.ZodIssueCode.custom,
+        path: ["outOfBand"],
+        message: `integration '${integration.id}' claims outOfBand 'none' but its route is python, so a consumer whose whole toolchain is node cannot run it without an interpreter and an ASGI server they start themselves. Use 'language-runtime'.`
+      });
+    }
+    if (routeSources.some((code) => SPAWNS_PROCESS.test(code))) {
+      ctx.addIssue({
+        code: z$1.ZodIssueCode.custom,
+        path: ["outOfBand"],
+        message: `integration '${integration.id}' claims outOfBand 'none' but its route spawns a child process, so the program it spawns has to be installed on the host — nothing in package.json puts it there. Use 'local-binary'.`
+      });
+    }
+    if (routeSources.some((code) => LOOPBACK_FETCH.test(code))) {
+      ctx.addIssue({
+        code: z$1.ZodIssueCode.custom,
+        path: ["outOfBand"],
+        message: `integration '${integration.id}' claims outOfBand 'none' but its route fetches a loopback address, so something local has to be listening before the first message works. Use 'local-server'.`
+      });
+    }
+  }
 });
 z$1.object({
   id: z$1.string(),
@@ -1022,7 +1066,9 @@ const openai = {
   deps: { npm: [], pip: [] },
   // The route reads OPENAI_API_KEY and puts it in an `Authorization: Bearer`
   // header. A static bundle carrying that is a published key.
-  keyExposure: "needs-proxy"
+  keyExposure: "needs-proxy",
+  // A remote HTTPS endpoint and a key. Nothing to install, nothing to start.
+  outOfBand: "none"
 };
 const anthropic = {
   id: "anthropic",
@@ -1037,10 +1083,19 @@ const anthropic = {
   // No per-framework templates: the handler below is web-standard, so the
   // scaffolder wraps it in whatever the target framework routes with.
   routeTemplates: {},
-  webRoute: `/** One Anthropic content block. Open union on the wire; these are the four the
+  webRoute: `/** Where an image or document's bytes come from. Anthropic takes both forms
+ *  for both block types, which is why this route has no gap where the
+ *  OpenAI-shaped one does: a chat-completions \`file\` part is base64-only. */
+type AnthropicSource =
+  | { type: 'base64'; media_type: string; data: string }
+  | { type: 'url'; url: string };
+
+/** One Anthropic content block. Open union on the wire; these are the ones the
  *  scaffold's own thread can produce. */
 type AnthropicBlock =
   | { type: 'text'; text: string }
+  | { type: 'image'; source: AnthropicSource }
+  | { type: 'document'; source: AnthropicSource }
   | { type: 'tool_use'; id: string; name: string; input: unknown }
   | { type: 'tool_result'; tool_use_id: string; content: string };
 
@@ -1123,12 +1178,24 @@ function toAnthropicBody(messages: ChatRequestBody['messages']): {
     switch (message.role) {
       case 'system': {
         // TOP-LEVEL, not a message. Several system turns concatenate.
-        const text = message.content ?? '';
+        const text = wireText(message.content);
         system = system === undefined ? text : \`\${system}\\n\\n\${text}\`;
         break;
       }
       case 'user': {
-        if (message.content) pushUser([{ type: 'text', text: message.content }]);
+        // Attachments ride HERE, as image and document blocks beside the text,
+        // in the order the thread authored them.
+        const blocks = wireParts(message.content).map((part): AnthropicBlock => {
+          if (part.kind === 'text') return { type: 'text', text: part.text };
+          const source: AnthropicSource =
+            part.source.type === 'data'
+              ? { type: 'base64', media_type: part.mediaType, data: part.source.data }
+              : { type: 'url', url: part.source.url };
+          // \`image/png\` and the bare top-level \`image\` both mean an image; a URL
+          // source reports only the segment because the wire carries no more.
+          return part.mediaType.startsWith('image') ? { type: 'image', source } : { type: 'document', source };
+        });
+        if (blocks.length > 0) pushUser(blocks);
         break;
       }
       case 'tool': {
@@ -1137,14 +1204,15 @@ function toAnthropicBody(messages: ChatRequestBody['messages']): {
           {
             type: 'tool_result',
             tool_use_id: message.tool_call_id ?? '',
-            content: message.content ?? '',
+            content: wireText(message.content),
           },
         ]);
         break;
       }
       case 'assistant': {
         const content: AnthropicBlock[] = [];
-        if (message.content) content.push({ type: 'text', text: message.content });
+        const text = wireText(message.content);
+        if (text) content.push({ type: 'text', text });
         for (const call of message.tool_calls ?? []) {
           content.push({
             type: 'tool_use',
@@ -1406,7 +1474,9 @@ async function chatHandler(request: Request): Promise<Response> {
   // The route reads ANTHROPIC_API_KEY into an `x-api-key` header. Note the
   // header is NOT `Authorization`, which is why the schema's detector matches
   // both spellings.
-  keyExposure: "needs-proxy"
+  keyExposure: "needs-proxy",
+  // A remote HTTPS endpoint and a key. Nothing to install, nothing to start.
+  outOfBand: "none"
 };
 const openrouter = {
   id: "openrouter",
@@ -1475,7 +1545,9 @@ const openrouter = {
   // Nothing to install. The route is global `fetch` and imports no module.
   deps: { npm: [], pip: [] },
   // The route reads OPENROUTER_API_KEY into an `Authorization: Bearer` header.
-  keyExposure: "needs-proxy"
+  keyExposure: "needs-proxy",
+  // A remote HTTPS endpoint and a key. Nothing to install, nothing to start.
+  outOfBand: "none"
 };
 const vercelAiSdk = {
   id: "vercel-ai-sdk",
@@ -1488,12 +1560,32 @@ const vercelAiSdk = {
   // scaffolder wraps it in the target framework's own route declaration.
   routeTemplates: {},
   webRoute: `import { streamText } from 'ai';
-import type { ModelMessage, AssistantContent, ToolResultPart } from 'ai';
+import type { ModelMessage, AssistantContent, UserContent, FilePart, ToolResultPart } from 'ai';
 
 // Next.js only: add \`export const maxDuration = 30\` to the route file to allow
 // long streaming responses. It is a Next route-segment config, not part of the
 // handler, so it lives in the file rather than in here.
 
+/**
+ * One attachment to an AI SDK FilePart.
+ *
+ * \`data\` takes the BARE shorthand — a base64 string, or a URL object for a
+ * remote file — rather than the newer tagged \`{ type: 'data' | 'url' }\` form.
+ * Both are accepted by the installed SDK; the shorthand is also what AI SDK v5
+ * and v6 accept, so this route keeps compiling if the app pins an older \`ai\`.
+ *
+ * Images arrive as \`image_url\` and become FileParts too. \`ImagePart\` still
+ * exists but is deprecated in favour of exactly this.
+ */
+function toFilePart(part: Extract<WirePart, { kind: 'file' }>): FilePart {
+  return {
+    type: 'file',
+    mediaType: part.mediaType,
+    ...(part.filename === undefined ? {} : { filename: part.filename }),
+    data: part.source.type === 'data' ? part.source.data : new URL(part.source.url),
+  };
+}
+
 // The kit's wire format is OpenAI-shaped (tool_calls on the assistant message,
 // a flat content string on the tool message). The AI SDK's ModelMessage is not:
 // a tool call is a CONTENT PART on the assistant message, and a tool result is a
@@ -1502,22 +1594,35 @@ import type { ModelMessage, AssistantContent, ToolResultPart } from 'ai';
 function toModelMessages(messages: ChatRequestBody['messages']): ModelMessage[] {
   return messages.map((message): ModelMessage => {
     switch (message.role) {
+      // A system prompt is text-only on every wire, so the array form collapses.
       case 'system':
-      case 'user':
-        return { role: message.role, content: message.content ?? '' };
+        return { role: 'system', content: wireText(message.content) };
+      case 'user': {
+        const parts = wireParts(message.content);
+        // Plain string for an ordinary turn: identical to what this route sent
+        // before attachments existed, and the shape the SDK docs lead with.
+        if (parts.every((p) => p.kind === 'text')) {
+          return { role: 'user', content: wireText(message.content) };
+        }
+        const content: UserContent = parts.map((p) =>
+          p.kind === 'text' ? { type: 'text' as const, text: p.text } : toFilePart(p),
+        );
+        return { role: 'user', content };
+      }
       case 'tool': {
         const result: ToolResultPart = {
           type: 'tool-result',
           toolCallId: message.tool_call_id ?? '',
           toolName: message.name ?? '',
-          output: { type: 'text', value: message.content ?? '' },
+          output: { type: 'text', value: wireText(message.content) },
         };
         return { role: 'tool', content: [result] };
       }
       case 'assistant': {
-        if (!message.tool_calls?.length) return { role: 'assistant', content: message.content ?? '' };
+        const text = wireText(message.content);
+        if (!message.tool_calls?.length) return { role: 'assistant', content: text };
         const content: AssistantContent = [];
-        if (message.content) content.push({ type: 'text', text: message.content });
+        if (text) content.push({ type: 'text', text });
         for (const call of message.tool_calls) {
           content.push({
             type: 'tool-call',
@@ -1586,7 +1691,10 @@ async function chatHandler(request: Request): Promise<Response> {
   // streamText(). This is the case that makes inference from route source
   // unsafe and the declaration necessary; `envVars` is what the schema's safety
   // net can still see.
-  keyExposure: "needs-proxy"
+  keyExposure: "needs-proxy",
+  // The AI Gateway is a remote HTTPS endpoint reached through the `ai` package,
+  // which is an ordinary npm dependency (see `deps`). Nothing to start.
+  outOfBand: "none"
 };
 const langgraph = {
   id: "langgraph",
@@ -1696,7 +1804,20 @@ async function chatHandler(request: Request): Promise<Response> {
   deps: { npm: ["@langchain/langgraph", "@langchain/openai", "@langchain/core", "zod"], pip: [] },
   // No key appears in the route: `new ChatOpenAI(...)` reads OPENAI_API_KEY from
   // the environment itself. Same invisible-key shape as vercel-ai-sdk.
-  keyExposure: "needs-proxy"
+  keyExposure: "needs-proxy",
+  // 'none', and this is the entry most likely to be "corrected" to something
+  // else, so the reason is here rather than assumed. The create-kai spec lists
+  // LangGraph under "Bring a server or runtime". That is WRONG for this route:
+  // the graph is built and compiled IN PROCESS above (`createReactAgent` over a
+  // `new ChatOpenAI(...)`), so there is no LangGraph server, no port and no
+  // second process — the four packages in `deps` are the whole install and
+  // `runNote` asks for a key and nothing else.
+  //
+  // LangGraph Platform / `langgraph dev` IS a server, and an integration that
+  // talked to one over HTTP would be 'local-server'. That is a different route
+  // than the one above, and if it is ever added it must be added as its own
+  // catalog entry rather than by changing this line.
+  outOfBand: "none"
 };
 const cloudflare = {
   id: "cloudflare",
@@ -1863,7 +1984,12 @@ export default {
   // The two routes differ and the stricter one governs: the worker template uses
   // the `env.AI` binding and holds no token in code at all, but a binding is a
   // Worker capability, not a browser one. Either way a server is required.
-  keyExposure: "needs-proxy"
+  keyExposure: "needs-proxy",
+  // Workers AI is a remote HTTPS endpoint (the REST route) or a platform binding
+  // (the worker route) — either way there is nothing on the developer's machine
+  // to install or run. `wrangler` is a devDependency of a Worker app, not an
+  // out-of-band prerequisite of this integration.
+  outOfBand: "none"
 };
 const ollama = {
   id: "ollama",
@@ -1942,7 +2068,14 @@ const ollama = {
   // empty, so there is no secret for a bundle to leak. runNote already documents
   // the browser-direct path (set OLLAMA_ORIGINS to allow the page origin), which
   // is the path this value unlocks.
-  keyExposure: "frontend-safe"
+  keyExposure: "frontend-safe",
+  // The route fetches http://localhost:11434, so Ollama must ALREADY be running:
+  // `ollama serve`, then `ollama pull <model>` for the model the route pins.
+  // Nothing in package.json installs or starts it — `deps.npm` is empty because
+  // the route is bare `fetch`, which is exactly why this cannot be inferred from
+  // the dependency list. The schema's LOOPBACK_FETCH net catches this one
+  // independently, so a later edit to 'none' fails at the catalog boundary.
+  outOfBand: "local-server"
 };
 const mastra = {
   id: "mastra",
@@ -1979,17 +2112,43 @@ async function chatHandler(request: Request): Promise<Response> {
   // is never null. A 'tool' wire message is OUR client-side tool bookkeeping;
   // this agent owns its tools server-side (forwardsFromClient is empty), so it
   // has no schema for that shape and the entry is dropped rather than guessed.
-  type MastraMessage = { role: 'system'; content: string } | { role: 'user'; content: string } | { role: 'assistant'; content: string };
+  //
+  // Only the USER role takes content parts: a system prompt is text by
+  // definition, and an assistant turn here is replayed history, not a new
+  // upload. \`data\` uses the bare base64-or-URL shorthand, which every AI SDK
+  // major Mastra accepts understands.
+  type MastraFilePart = { type: 'file'; data: string | URL; mediaType: string; filename?: string };
+  type MastraUserContent = string | Array<{ type: 'text'; text: string } | MastraFilePart>;
+  type MastraMessage = { role: 'system'; content: string } | { role: 'user'; content: MastraUserContent } | { role: 'assistant'; content: string };
   const mastraMessages: MastraMessage[] = [];
   for (const m of messages) {
-    const content = m.content ?? '';
     // Each branch constructs a literal with ONE fixed role, not m.role (which is
     // still typed as the 4-way union): a union-VALUED field on a single object
     // does not structurally match a union of role-discriminated objects, so
     // widening back to m.role here would reintroduce the original TS2345.
-    if (m.role === 'system') mastraMessages.push({ role: 'system', content });
-    else if (m.role === 'user') mastraMessages.push({ role: 'user', content });
-    else if (m.role === 'assistant') mastraMessages.push({ role: 'assistant', content });
+    if (m.role === 'system') mastraMessages.push({ role: 'system', content: wireText(m.content) });
+    else if (m.role === 'assistant') mastraMessages.push({ role: 'assistant', content: wireText(m.content) });
+    else if (m.role === 'user') {
+      const parts = wireParts(m.content);
+      // Plain string unless the turn actually carries an attachment.
+      if (parts.every((p) => p.kind === 'text')) {
+        mastraMessages.push({ role: 'user', content: wireText(m.content) });
+      } else {
+        mastraMessages.push({
+          role: 'user',
+          content: parts.map((p) =>
+            p.kind === 'text'
+              ? { type: 'text' as const, text: p.text }
+              : {
+                  type: 'file' as const,
+                  mediaType: p.mediaType,
+                  ...(p.filename === undefined ? {} : { filename: p.filename }),
+                  data: p.source.type === 'data' ? p.source.data : new URL(p.source.url),
+                },
+          ),
+        });
+      }
+    }
   }
 
   let agentStream: Awaited<ReturnType<ReturnType<typeof mastra.getAgent>['stream']>>;
@@ -2073,7 +2232,22 @@ async function chatHandler(request: Request): Promise<Response> {
   // agent endpoint — a decision a scaffolder must not make silently, even though
   // no key leaks. The conservative direction is the cheap one: a needless server
   // hop costs a process, the other error costs the endpoint.
-  keyExposure: "needs-proxy"
+  keyExposure: "needs-proxy",
+  // THE JUDGEMENT CALL FOR THIS FIELD, exactly as keyExposure above is, and for
+  // a related reason: no automatic check can decide it. MASTRA_URL is a base URL
+  // for a server this integration does not ship and cannot start; the route's
+  // only mention of loopback is inside a `throw new Error(...)` string, which
+  // LOOPBACK_FETCH deliberately does not match (a net that fired on prose would
+  // be right here by accident and wrong elsewhere). So 'none' would parse
+  // cleanly.
+  //
+  // It is 'local-server' on what the integration actually requires: a Mastra
+  // server has to be reachable at MASTRA_URL before the first message works,
+  // `mastra dev` is how a developer gets one (port 4111), and `@mastra/client-js`
+  // is a CLIENT for it, not the server itself. Printing "start your Mastra
+  // server" costs a line; omitting it produces a scaffold that fetches a URL
+  // nothing answers.
+  outOfBand: "local-server"
 };
 const pi = {
   id: "pi",
@@ -2098,7 +2272,25 @@ app.use(express.json());
 // 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[] };
-  const prompt = messages.at(-1)?.content ?? '';
+  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
+  // has no channel for a file, so an attachment is REFUSED here. Passing the
+  // array straight through would JSON.stringify an object graph into the prompt
+  // — no type error, no crash, just a model reading serialised noise.
+  if (Array.isArray(last) && last.some((part) => part.type !== 'text')) {
+    res.status(400).json({
+      error: {
+        message:
+          'This Pi bridge forwards a text prompt only and has no channel for an attachment. Extract the file content into the message text, or send it through a tool.',
+      },
+    });
+    return;
+  }
+  const prompt =
+    typeof last === 'string'
+      ? last
+      : (last ?? []).map((part) => (part.type === 'text' ? part.text : '')).join('');
 
   // Headers before the first frame: without text/event-stream the browser
   // buffers the body and readOpenAIStream never sees a frame.
@@ -2165,7 +2357,14 @@ app.listen(3001, () => console.log('chat api: http://localhost:3001/api/chat'));
   // warns that Pi runs with full user permissions and wants sandboxing before it
   // is exposed. "No key" is not the same fact as "safe in the browser", and
   // collapsing the two is exactly how this flag would be got wrong.
-  keyExposure: "needs-proxy"
+  keyExposure: "needs-proxy",
+  // Not 'local-server': nothing is listening in advance. The bridge spawns
+  // `pi --mode rpc` per request, so what the developer supplies is an EXECUTABLE
+  // on PATH ("Pi must be installed locally and available on PATH as 'pi'"), and
+  // "start the server first" would be the wrong instruction to print. Pi is not
+  // in `deps` for the same reason — the route reaches it with spawn(), not an
+  // import. The schema's SPAWNS_PROCESS net catches this one independently.
+  outOfBand: "local-binary"
 };
 const pydanticAi = {
   id: "pydantic-ai",
@@ -2177,7 +2376,7 @@ const pydanticAi = {
   routeTemplates: {
     fastapi: `# main.py
 import json
-from fastapi import FastAPI
+from fastapi import FastAPI, HTTPException
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import StreamingResponse
 from pydantic import BaseModel
@@ -2190,15 +2389,41 @@ app.add_middleware(
     CORSMiddleware, allow_origins=['*'], allow_methods=['*'], allow_headers=['*']
 )
 
+class ContentPart(BaseModel):
+    type: str
+    text: str | None = None
+
 class Message(BaseModel):
     role: str
-    content: str
+    # A plain string until the turn carries an attachment, at which point the
+    # wire sends an ARRAY of content parts. Declaring this \`str\` alone made a
+    # message with a file a 422 that named pydantic rather than the cause.
+    content: str | list[ContentPart] | None = None
 
 class ChatRequest(BaseModel):
     messages: list[Message]
 
+def prompt_text(message: Message) -> str:
+    """The text of a turn, refusing what this route cannot carry.
+
+    agent.run_stream() takes a TEXT prompt, so an image or a document has no
+    channel here. Dropping it would send the model a turn that silently lost the
+    user's file; a 400 that names the reason is the honest failure.
+    """
+    if message.content is None:
+        return ''
+    if isinstance(message.content, str):
+        return message.content
+    if any(part.type != 'text' for part in message.content):
+        raise HTTPException(
+            status_code=400,
+            detail='This route forwards a text prompt only and has no channel for an attachment. '
+            'Extract the file content into the message text, or send it through a tool.',
+        )
+    return ''.join(part.text or '' for part in message.content)
+
 async def openai_sse(messages: list[Message]):
-    prompt = messages[-1].content if messages else ''
+    prompt = prompt_text(messages[-1]) if messages else ''
     async with agent.run_stream(prompt) as result:
         async for delta in result.stream_text(delta=True):
             chunk = {'choices': [{'delta': {'content': delta}}]}
@@ -2233,7 +2458,15 @@ async def chat(req: ChatRequest):
   // DIRECTLY on :8000, with no JS proxy in front. That still is not
   // 'frontend-safe' — the flag asks where the SECRET lives, and it lives in the
   // python process. The FastAPI service IS the server hop.
-  keyExposure: "needs-proxy"
+  keyExposure: "needs-proxy",
+  // The emitted backend is a FastAPI service: a python interpreter, the four
+  // `deps.pip` packages, and `uvicorn main:app` on its own port — none of which a
+  // node toolchain provides or starts. It also needs OPENAI_API_KEY, so this is
+  // the entry that proves the groups are not mutually exclusive: a runtime
+  // prerequisite and a key at once. The prompt should lead with the runtime,
+  // because a key is useless until the service runs. The schema's `language ===
+  // 'python'` net catches this one independently.
+  outOfBand: "language-runtime"
 };
 const mock = {
   id: "mock",
@@ -2257,7 +2490,11 @@ const mock = {
   // 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.
-  keyExposure: "frontend-safe"
+  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.
+  outOfBand: "none"
 };
 const archetypes$1 = [
   {
@@ -2301,6 +2538,34 @@ const archetypes$1 = [
     components: ["kai-chat", "kai-voice-input"],
     defaultPlacement: "full-page",
     docsSlug: "examples/voice-assistant"
+  },
+  /**
+   * THE PRESET THAT EXISTS TO MAKE A CAPABILITY REACHABLE, not to name a product
+   * shape someone asked for.
+   *
+   * `kai-file-upload` and `kai-attachments` were registered elements that NO
+   * preset composed, and `listCapabilityGroups` derives its answer from this
+   * table — so the attachments capability reached neither `listSurfaceProbes`
+   * nor `verify:scaffold`, and `renderSurface` had no branch that emitted either
+   * tag. A caller could pass them in `components` (the axis takes any list) and
+   * get two bare `<kai-file-upload></kai-file-upload>` / `<kai-attachments>`
+   * siblings with nothing wired to them: on screen, inert, silent.
+   *
+   * The pair is ONE capability for the same reason `kai-artifact` +
+   * `kai-resizable` are: a dropzone with no list is a black hole, and a list
+   * with no dropzone can never fill. `hasAttachments` in scaffold.ts requires
+   * both for exactly that reason.
+   *
+   * The components match the create-kai spec's own feature table
+   * (`attachments` -> `kai-file-upload`, `kai-attachments`), so the CLI's
+   * multi-select and this preset name the same surface rather than two.
+   */
+  {
+    id: "attachments",
+    title: "File attachments",
+    components: ["kai-chat", "kai-file-upload", "kai-attachments"],
+    defaultPlacement: "full-page",
+    docsSlug: "examples/attachments"
   }
 ];
 const integrations = [
@@ -2329,6 +2594,83 @@ function listIntegrations() {
 function listArchetypes() {
   return archetypes;
 }
+const ENCODABLE = [
+  { pattern: "image/jpeg", kind: "image" },
+  { pattern: "image/png", kind: "image" },
+  { pattern: "image/gif", kind: "image" },
+  { pattern: "image/webp", kind: "image" },
+  { pattern: "application/pdf", kind: "document" },
+  { pattern: "text/*", kind: "text" },
+  { pattern: "application/json", kind: "text" },
+  { pattern: "application/xml", kind: "text" },
+  { pattern: "application/x-yaml", kind: "text" },
+  { pattern: "application/yaml", kind: "text" }
+];
+const UNNAMED_TEXT_MEDIA_TYPE = "text/plain";
+const NAMES_NOTHING = ["", "application/octet-stream"];
+const normalize = (value) => value.trim().toLowerCase();
+const namesNothing = (mediaType) => NAMES_NOTHING.includes(mediaType === void 0 ? "" : normalize(mediaType));
+const assertMediaType = (entry) => {
+  if (!entry.startsWith(".")) return entry;
+  throw new Error(
+    `\`accept\` entry "${entry}" is a file extension, and this kit takes media types only. HTML's own accept attribute does take extensions, which is exactly why this throws rather than quietly matching nothing. Use a media type instead -- "text/*" covers source files, "image/*" images, "application/pdf" PDFs, and \`encodableMediaTypes()\` is the full set. You lose nothing by dropping the extension: a file the browser cannot name is decided by decoding its bytes, which is stronger than matching its name.`
+  );
+};
+const splitFilter = (filter) => (typeof filter === "string" ? filter.split(",") : filter).map(normalize).filter((v2) => v2 !== "").map(assertMediaType);
+const parts = (pattern) => {
+  const slash = pattern.indexOf("/");
+  return slash === -1 ? [pattern, ""] : [pattern.slice(0, slash), pattern.slice(slash + 1)];
+};
+const matches = (pattern, mediaType) => {
+  const [pType, pSub] = parts(pattern);
+  const [mType, mSub] = parts(mediaType);
+  if (pType !== "*" && pType !== mType) return false;
+  return pSub === "*" || pSub === mSub;
+};
+const intersect = (capability, filter) => {
+  if (matches(capability, filter)) return filter;
+  if (matches(filter, capability)) return capability;
+  return void 0;
+};
+function encodableMediaTypes() {
+  return ENCODABLE.map((entry) => entry.pattern);
+}
+function resolveMediaPolicy(options = {}) {
+  const filter = options.accept === void 0 ? void 0 : splitFilter(options.accept);
+  const effective = [];
+  for (const capability of ENCODABLE) {
+    if (filter === void 0) {
+      effective.push({ ...capability });
+      continue;
+    }
+    for (const wanted of filter) {
+      const overlap = intersect(capability.pattern, wanted);
+      if (overlap !== void 0 && !effective.some((e) => e.pattern === overlap)) {
+        effective.push({ pattern: overlap, kind: capability.kind });
+      }
+    }
+  }
+  return {
+    types: effective.map((e) => e.pattern),
+    accept: effective.map((e) => e.pattern).join(","),
+    decide(mediaType) {
+      const type = mediaType === void 0 ? "" : normalize(mediaType);
+      if (namesNothing(type)) {
+        return effective.some((e) => matches(e.pattern, UNNAMED_TEXT_MEDIA_TYPE)) ? { status: "undetermined" } : (
+          // `unsupported` rather than `filtered`, deliberately: `filtered`
+          // claims the kit COULD have encoded this file, and nobody has
+          // established what it is. Unread and unnamed, it is not a text
+          // file the filter excluded -- it is a file with no known type.
+          { status: "unsupported" }
+        );
+      }
+      const hit = effective.find((e) => matches(e.pattern, type));
+      if (hit) return { status: "allowed", kind: hit.kind };
+      return ENCODABLE.some((e) => matches(e.pattern, type)) ? { status: "filtered" } : { status: "unsupported" };
+    }
+  };
+}
+resolveMediaPolicy();
 const text = (s) => ({
   content: [{ type: "text", text: s }]
 });
@@ -2433,11 +2775,13 @@ function realStreamBody(opts) {
     cards = false,
     valueSource = "e.detail.value",
     afterValue = [],
-    mock: mock2 = false
+    mock: mock2 = false,
+    filesExpr
   } = opts;
   const asConst = strictRoles ? " as const" : "";
   const historyType = strictRoles ? ": ChatMessage[]" : "";
-  const userMessage = `{ id: crypto.randomUUID(), role: 'user'${asConst}, parts: [{ type: 'text', text: value }] }`;
+  const fileParts = filesExpr ? `...${filesExpr}.map((attachment) => ({ type: 'file'${asConst}, attachment })), ` : "";
+  const userMessage = `{ id: crypto.randomUUID(), role: 'user'${asConst}, parts: [${fileParts}{ type: 'text', text: value }] }`;
   const open = toolLoop ? thread.open({ pad, userMessage, typed: strictRoles }) : [
     `${pad}const history${historyType} = [...${read}, ${userMessage}];`,
     `${pad}${commitSet("history")}`
@@ -2585,12 +2929,13 @@ function assertCardToolFormat(integration) {
   return provider;
 }
 function wireImportLines(opts) {
-  const { pad = "", typed, toolLoop = false, setMessagesType = false, cards = false, cardTools: emitsCardTools = false, mock: mock2 = false } = opts;
+  const { pad = "", typed, toolLoop = false, setMessagesType = false, cards = false, cardTools: emitsCardTools = false, mock: mock2 = false, attachments = false } = opts;
   const stateNames = [
     "createAssistantStream",
     // The mock's canned reply comes from the kit, not from a copy pasted into
     // this file. One implementation, shared with create-kai and the starters.
     ...mock2 ? ["createMockResponder"] : [],
+    ...attachments ? ["type AttachmentData"] : [],
     ...typed ? ["type ChatMessage"] : [],
     ...typed && setMessagesType ? ["type SetMessages"] : []
   ].join(", ");
@@ -2743,6 +3088,69 @@ const WORKSPACE_STRUCTURAL_TAGS = /* @__PURE__ */ new Set(["kai-resizable", "kai
 function isWorkspace(components) {
   return components.includes("kai-resizable") && components.includes("kai-artifact");
 }
+const ATTACHMENT_TAGS = /* @__PURE__ */ new Set(["kai-file-upload", "kai-attachments"]);
+function hasAttachments(components) {
+  return components.includes("kai-file-upload") && components.includes("kai-attachments");
+}
+const ATTACHMENT_ACCEPT = encodableMediaTypes().join(",");
+const ATTACHMENT_WIRE_NOTE = [
+  "// The staged files ride along on the message as `file` parts, so they RENDER",
+  "// in the thread AND reach the model: toOpenAIMessages / toAnthropicMessages",
+  "// encode each one into the content block its API takes.",
+  "// Which is why toAttachment below stages a `data:` URI rather than a",
+  "// URL.createObjectURL blob: an object URL previews fine and resolves ONLY",
+  "// inside this tab, so the encoder rejects it rather than send an address the",
+  "// provider cannot fetch.",
+  "// What can be sent is not a list worth copying into a comment -- it moves, and",
+  '// a copy cannot. `encodableMediaTypes()` from "@kitn.ai/ui/wire" IS the set,',
+  "// and `resolveMediaPolicy().decide(mediaType)` answers for one file. Anything",
+  "// outside it throws at encode time instead of going missing from the request.",
+  "// A file the browser could not name (a .rs, a .toml) is settled by decoding",
+  "// its bytes, never by its extension."
+];
+function fileToAttachmentLines(pad, typeName) {
+  return [
+    `${pad}/** <kai-file-upload> hands over File objects; <kai-attachments> renders these. */`,
+    `${pad}async function toAttachment(file: File): Promise<${typeName}> {`,
+    `${pad}  // A data: URI, NOT URL.createObjectURL. Both preview identically, but an`,
+    `${pad}  // object URL resolves only inside this tab, so it can never reach a model —`,
+    `${pad}  // the encoder rejects one rather than send an address the provider cannot`,
+    `${pad}  // fetch. Reading is async, which is why this function is.`,
+    `${pad}  const url = await new Promise<string>((resolve, reject) => {`,
+    `${pad}    const reader = new FileReader();`,
+    `${pad}    reader.onload = () => resolve(String(reader.result));`,
+    `${pad}    reader.onerror = () => reject(reader.error ?? new Error('Could not read ' + file.name));`,
+    `${pad}    reader.readAsDataURL(file);`,
+    `${pad}  });`,
+    `${pad}  return {`,
+    `${pad}    id: crypto.randomUUID(),`,
+    `${pad}    type: 'file',`,
+    `${pad}    filename: file.name,`,
+    `${pad}    // '' for an extensionless file, and an empty mediaType would render as a`,
+    `${pad}    // blank detail line rather than falling back to the generic icon.`,
+    `${pad}    mediaType: file.type || undefined,`,
+    `${pad}    url,`,
+    `${pad}  };`,
+    `${pad}}`
+  ];
+}
+const ATTACHMENT_MERGE_NOTE = [
+  "// <kai-chat> renders its OWN paperclip (there is no prop that hides it), and its",
+  "// staged files arrive on this event as detail.attachments. The dropzone above is",
+  "// the second source. Both are folded in — reading either one alone silently",
+  "// drops files the user really attached."
+];
+function attachmentTurnLines(opts) {
+  const { stagedExpr, clear, fromSubmitEvent } = opts;
+  return [
+    ...fromSubmitEvent ? ATTACHMENT_MERGE_NOTE : [
+      "// This target renders PromptInput directly rather than <kai-chat>, so the",
+      "// dropzone is the only source of staged files — there is no kai-submit detail."
+    ],
+    fromSubmitEvent ? `const files = [...${stagedExpr}, ...e.detail.attachments];` : `const files = [...${stagedExpr}];`,
+    ...clear
+  ];
+}
 const SAMPLE_AGENTIC_MESSAGE = {
   id: "sample-assistant",
   role: "assistant",
@@ -2779,11 +3187,22 @@ function sampleSeedComment(isMock, pad, decl) {
 }
 function componentTags(components, chatFill) {
   const companionTags = components.filter(
-    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !WORKSPACE_STRUCTURAL_TAGS.has(t)
+    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !WORKSPACE_STRUCTURAL_TAGS.has(t) && !(hasAttachments(components) && ATTACHMENT_TAGS.has(t))
   );
   const hasEmbedded = components.some((t) => MESSAGE_EMBEDDED_TAGS.has(t));
   const hasStandaloneCompanions = companionTags.length > 0;
   const lines = [];
+  if (hasAttachments(components)) {
+    lines.push(
+      `  <!-- Drop files here to stage them for the NEXT message. src/main.ts wires`,
+      `       kai-files-added -> the staged list -> kai-attachments' items property. -->`,
+      `  <div style="flex: 0 0 auto; display: flex; flex-direction: column; gap: 0.5rem; padding: 0.75rem;">`,
+      `    <kai-file-upload id="upload" accept="${ATTACHMENT_ACCEPT}"></kai-file-upload>`,
+      `    <!-- items is a JS PROPERTY (arrays can't be attributes); 'removable' fires kai-remove. -->`,
+      `    <kai-attachments id="attachments" variant="inline" removable></kai-attachments>`,
+      `  </div>`
+    );
+  }
   if (isWorkspace(components)) {
     lines.push(
       `  <!-- SCAF-14: workspace split — chat pane left, artifact preview right. -->`,
@@ -2826,6 +3245,40 @@ function componentTags(components, chatFill) {
 function htmlModule(ctx, components) {
   const hasEmbedded = components.some((t) => MESSAGE_EMBEDDED_TAGS.has(t));
   const hasSources = components.includes("kai-sources");
+  const attachments = hasAttachments(components);
+  const attachmentModuleLines = attachments ? [
+    ...ATTACHMENT_WIRE_NOTE,
+    `//`,
+    `// AttachmentData is the kit's own type for a staged file — the same one`,
+    `// <kai-attachments>.items holds and the same one a 'file' message part holds.`,
+    `let staged: AttachmentData[] = [];`,
+    ``,
+    ...fileToAttachmentLines("", "AttachmentData"),
+    ``
+  ] : [];
+  const attachmentSetupLines = attachments ? [
+    `  const uploadEl = document.getElementById('upload') as HTMLElement;`,
+    `  const attachmentsEl = document.getElementById('attachments') as KaiAttachmentsElement;`,
+    `  // Same upgrade rule as <kai-chat>: 'items' is an array, so it is a PROPERTY,`,
+    `  // and a property set before the element upgrades is dropped on upgrade.`,
+    `  await customElements.whenDefined('kai-attachments');`,
+    `  // A NEW array per write — same contract as chat.messages.`,
+    `  const showStaged = () => { attachmentsEl.items = [...staged]; };`,
+    ``,
+    `  uploadEl.addEventListener('kai-files-added', async (event: Event) => {`,
+    `    const { files } = (event as CustomEvent<{ files: File[] }>).detail;`,
+    `    // Read every file BEFORE appending: a per-file append would order the`,
+    `    // list by whichever finished reading first.`,
+    `    staged = [...staged, ...(await Promise.all(files.map(toAttachment)))];`,
+    `    showStaged();`,
+    `  });`,
+    `  attachmentsEl.addEventListener('kai-remove', (event: Event) => {`,
+    `    const { id } = (event as CustomEvent<{ id: string }>).detail;`,
+    `    staged = staged.filter((a) => a.id !== id);`,
+    `    showStaged();`,
+    `  });`,
+    ``
+  ] : [];
   const seedLines = hasEmbedded ? [...sampleSeedComment(ctx.isMock, `  `, (literal) => [`chat.messages = [${literal}];`]), ``] : [];
   const sourcesSetupLines = hasSources ? [
     `  const sourcesEl = document.getElementById('sources') as KaiSourcesElement;`,
@@ -2851,7 +3304,11 @@ function htmlModule(ctx, components) {
     `  chat.cardSchemas = cards.validationSchemas;`,
     ``
   ] : [];
-  const elementTypes = hasSources ? "KaiChatElement, KaiSourcesElement" : "KaiChatElement";
+  const elementTypes = [
+    "KaiChatElement",
+    ...hasSources ? ["KaiSourcesElement"] : [],
+    ...attachments ? ["KaiAttachmentsElement"] : []
+  ].join(", ");
   const annotatesChatMessage = !ctx.emitToolLoop;
   const head = [
     `// src/main.ts — the page's logic, in a module YOUR build type-checks.`,
@@ -2870,12 +3327,14 @@ function htmlModule(ctx, components) {
       toolLoop: ctx.emitToolLoop,
       cards: ctx.emitCards,
       cardTools: ctx.cardProvider !== null,
-      mock: ctx.isMock
+      mock: ctx.isMock,
+      attachments
     }),
     `import '@kitn.ai/ui/theme.tokens.css';  // compiled token defaults; use theme.css only for Tailwind-source apps`,
     ``,
     ...ctx.isMock ? [...mockResponderInit(), ``] : [],
     ...modelLines,
+    ...attachmentModuleLines,
     ...cardsLines,
     ...toolsLines,
     ...runnerLines,
@@ -2891,11 +3350,12 @@ function htmlModule(ctx, components) {
     ``,
     ...cardPropLines,
     ...seedLines,
-    ...sourcesSetupLines
+    ...sourcesSetupLines,
+    ...attachmentSetupLines
   ];
   const listenerOpen = [
     `  chat.addEventListener('kai-submit', async (event: Event) => {`,
-    `    const e = event as CustomEvent<{ value: string }>;`
+    attachments ? `    const e = event as CustomEvent<{ value: string; attachments: AttachmentData[] }>;` : `    const e = event as CustomEvent<{ value: string }>;`
   ];
   const footer = [
     `  });`,
@@ -2923,7 +3383,15 @@ function htmlModule(ctx, components) {
         "(fn) => { chat.messages = fn(chat.messages); }",
         "chat.messages ?? []"
       ),
-      mock: ctx.isMock
+      mock: ctx.isMock,
+      ...attachments ? {
+        filesExpr: "files",
+        afterValue: attachmentTurnLines({
+          stagedExpr: "staged",
+          clear: ["staged = [];", "showStaged();"],
+          fromSubmitEvent: true
+        })
+      } : {}
     }),
     ...footer
   ].join("\n");
@@ -2966,8 +3434,9 @@ function renderJsx(components, ctx, framework) {
   const importTags = workspace ? [.../* @__PURE__ */ new Set([...renderableTags.filter((t) => t !== "kai-resizable"), "kai-resizable", "kai-resizable-item"])] : renderableTags;
   const wrapperNames = importTags.map(toPascalCase);
   const importList = wrapperNames.join(", ");
+  const attachments = hasAttachments(components);
   const standaloneCompanionTags = components.filter(
-    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !WORKSPACE_STRUCTURAL_TAGS.has(t)
+    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !WORKSPACE_STRUCTURAL_TAGS.has(t) && !(attachments && ATTACHMENT_TAGS.has(t))
   );
   const companionJsxLines = [];
   if (hasEmbedded) {
@@ -2988,6 +3457,41 @@ function renderJsx(components, ctx, framework) {
     }
   }
   const companions = companionJsxLines.join("\n");
+  const attachmentJsx = attachments ? [
+    `      {/* Drop files here to stage them for the NEXT message. */}`,
+    `      <div style={{ flex: '0 0 auto', display: 'flex', flexDirection: 'column', gap: '0.5rem', padding: '0.75rem' }}>`,
+    `        <FileUpload accept="${ATTACHMENT_ACCEPT}" onFilesAdded={onFilesAdded} />`,
+    `        {/* items is an ARRAY, so the wrapper sets it as a DOM property, never an attribute. */}`,
+    `        <Attachments items={staged} variant="inline" removable onRemove={onRemoveAttachment} />`,
+    `      </div>`
+  ].join("\n") : "";
+  const attachmentModuleInit = attachments ? [
+    ...ATTACHMENT_WIRE_NOTE,
+    `//`,
+    `// AttachmentData is the kit's own type for a staged file — the same one`,
+    `// <Attachments>.items holds and the same one a 'file' message part holds.`,
+    ...fileToAttachmentLines("", "AttachmentData")
+  ] : [];
+  const attachmentStateInit = attachments ? [
+    `  const [staged, setStaged] = useState<AttachmentData[]>([]);`,
+    `  const onFilesAdded = async (e: CustomEvent<{ files: File[] }>) => {`,
+    `    // Read every file BEFORE appending: a per-file append would order the`,
+    `    // list by whichever finished reading first.`,
+    `    const added = await Promise.all(e.detail.files.map(toAttachment));`,
+    `    setStaged((prev) => [...prev, ...added]);`,
+    `  };`,
+    `  const onRemoveAttachment = (e: CustomEvent<{ id: string }>) =>`,
+    `    setStaged((prev) => prev.filter((a) => a.id !== e.detail.id));`
+  ].join("\n") : "";
+  const attachmentSubmitOpts = attachments ? {
+    filesExpr: "files",
+    afterValue: attachmentTurnLines({
+      stagedExpr: "staged",
+      clear: ["setStaged([]);"],
+      fromSubmitEvent: true
+    })
+  } : {};
+  const submitParamType = attachments ? "CustomEvent<{ value: string; attachments: AttachmentData[] }>" : "CustomEvent<{ value: string }>";
   const mockInit = isMock ? mockResponderInit() : [];
   const sampleMessagesInit = [
     ...hasEmbedded ? sampleSeedComment(isMock, "  ", (literal) => [
@@ -3022,7 +3526,8 @@ function renderJsx(components, ctx, framework) {
     toolLoop: emitToolLoop,
     cards: ctx.emitCards,
     thread: REACT_THREAD,
-    mock: isMock
+    mock: isMock,
+    ...attachmentSubmitOpts
   });
   const useClientDirective = framework === "next" ? [`'use client';`, ``] : [];
   if (framework === "next") {
@@ -3043,7 +3548,8 @@ function renderJsx(components, ctx, framework) {
         setMessagesType: emitToolLoop,
         cards: ctx.emitCards,
         cardTools: ctx.cardProvider !== null,
-        mock: isMock
+        mock: isMock,
+        attachments
       }),
       `import '@kitn.ai/ui/theme.tokens.css';  // compiled token defaults; use theme.css only for Tailwind-source apps`,
       `// <kai-*> are client-only custom elements (the server has no customElements`,
@@ -3056,22 +3562,25 @@ function renderJsx(components, ctx, framework) {
       ...(p.altNote ?? []).map((l) => `// ${l}`),
       ...mockInit,
       ``,
+      ...attachmentModuleInit,
       ...cardsInit,
       `export default function App() {`,
       sampleMessagesInit,
       `  const [loading, setLoading] = useState(false);`,
       `  const suggestions = ${jsArray(suggestions)};`,
+      ...attachmentStateInit ? [attachmentStateInit] : [],
       ...sampleSourcesInit ? [sampleSourcesInit] : [],
       ...modelInit ? [modelInit] : [],
       ...toolsInit ? [toolsInit] : [],
       ...toolRunner ? [toolRunner] : [],
       ``,
-      `  async function onSubmit(e: CustomEvent<{ value: string }>) {`,
+      `  async function onSubmit(e: ${submitParamType}) {`,
       onSubmitBody,
       `  }`,
       ``,
       `  return (`,
       `    <div style={{ ${jsxStyle(p.style)} }}>`,
+      ...attachmentJsx ? [attachmentJsx] : [],
       ...workspace ? [
         `      {/* SCAF-14: workspace split — chat pane left, artifact preview right. */}`,
         `      {/* Resizable needs ResizableItem children to render panels. */}`,
@@ -3131,7 +3640,8 @@ function renderJsx(components, ctx, framework) {
       setMessagesType: emitToolLoop,
       cards: ctx.emitCards,
       cardTools: ctx.cardProvider !== null,
-      mock: isMock
+      mock: isMock,
+      attachments
     }),
     `import '@kitn.ai/ui/theme.tokens.css';  // compiled token defaults; use theme.css only for Tailwind-source apps`,
     ``,
@@ -3140,22 +3650,25 @@ function renderJsx(components, ctx, framework) {
     ...(p.altNote ?? []).map((l) => `// ${l}`),
     ...mockInit,
     ``,
+    ...attachmentModuleInit,
     ...cardsInit,
     `export default function App() {`,
     sampleMessagesInit,
     `  const [loading, setLoading] = useState(false);`,
     `  const suggestions = ${jsArray(suggestions)};`,
+    ...attachmentStateInit ? [attachmentStateInit] : [],
     ...sampleSourcesInit ? [sampleSourcesInit] : [],
     ...modelInit ? [modelInit] : [],
     ...toolsInit ? [toolsInit] : [],
     ...toolRunner ? [toolRunner] : [],
     ``,
-    `  async function onSubmit(e: CustomEvent<{ value: string }>) {`,
+    `  async function onSubmit(e: ${submitParamType}) {`,
     onSubmitBody,
     `  }`,
     ``,
     `  return (`,
     `    <div style={{ ${jsxStyle(p.style)} }}>`,
+    ...attachmentJsx ? [attachmentJsx] : [],
     ...workspace ? [
       `      {/* SCAF-14: workspace split — chat pane left, artifact preview right. */}`,
       `      {/* Resizable needs ResizableItem children to render panels. */}`,
@@ -3200,8 +3713,9 @@ function renderJsx(components, ctx, framework) {
 function renderVue(components, ctx) {
   const { p, emptyHint, suggestions, isMock, defaultModel, emitTools, emitToolLoop } = ctx;
   const workspace = isWorkspace(components);
+  const attachments = hasAttachments(components);
   const standaloneCompanionTags = components.filter(
-    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !WORKSPACE_STRUCTURAL_TAGS.has(t)
+    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !WORKSPACE_STRUCTURAL_TAGS.has(t) && !(attachments && ATTACHMENT_TAGS.has(t))
   );
   const hasEmbedded = components.some((t) => MESSAGE_EMBEDDED_TAGS.has(t));
   const companionLines = [];
@@ -3220,6 +3734,42 @@ function renderVue(components, ctx) {
     }
   }
   const companions = companionLines.join("\n");
+  const attachmentTemplate = attachments ? [
+    `    <!-- Drop files here to stage them for the NEXT message. -->`,
+    `    <div style="flex: 0 0 auto; display: flex; flex-direction: column; gap: 0.5rem; padding: 0.75rem;">`,
+    `      <kai-file-upload accept="${ATTACHMENT_ACCEPT}" @kai-files-added="onFilesAdded" />`,
+    `      <kai-attachments :items.prop="staged" variant="inline" removable @kai-remove="onRemoveAttachment" />`,
+    `    </div>`
+  ].join("\n") : "";
+  const attachmentScript = attachments ? [
+    ...ATTACHMENT_WIRE_NOTE,
+    `//`,
+    `// AttachmentData is the kit's own type for a staged file, and it is what`,
+    `// <kai-attachments>.items and a 'file' MessagePart both hold.`,
+    `const staged = ref<AttachmentData[]>([]);`,
+    ``,
+    ...fileToAttachmentLines("", "AttachmentData"),
+    ``,
+    `async function onFilesAdded(event: Event) {`,
+    `  const { files } = (event as CustomEvent<{ files: File[] }>).detail;`,
+    `  // Read every file BEFORE appending: a per-file append would order the`,
+    `  // list by whichever finished reading first.`,
+    `  const added = await Promise.all(files.map(toAttachment));`,
+    `  staged.value = [...staged.value, ...added];`,
+    `}`,
+    `function onRemoveAttachment(event: Event) {`,
+    `  const { id } = (event as CustomEvent<{ id: string }>).detail;`,
+    `  staged.value = staged.value.filter((a) => a.id !== id);`,
+    `}`
+  ] : [];
+  const attachmentSubmitOpts = attachments ? {
+    filesExpr: "files",
+    afterValue: attachmentTurnLines({
+      stagedExpr: "staged.value",
+      clear: ["staged.value = [];"],
+      fromSubmitEvent: true
+    })
+  } : {};
   const onSubmitBody = realStreamBody({
     pad: "    ",
     read: "messages.value",
@@ -3231,7 +3781,8 @@ function renderVue(components, ctx) {
     toolLoop: emitToolLoop,
     cards: ctx.emitCards,
     thread: liveThreadBinding("messages.value", "(fn) => { messages.value = fn(messages.value); }"),
-    mock: isMock
+    mock: isMock,
+    ...attachmentSubmitOpts
   });
   const mockInit = isMock ? mockResponderInit() : [];
   const modelInit = defaultModel ? [
@@ -3306,7 +3857,8 @@ function renderVue(components, ctx) {
       toolLoop: emitToolLoop,
       cards: ctx.emitCards,
       cardTools: ctx.cardProvider !== null,
-      mock: isMock
+      mock: isMock,
+      attachments
     }),
     `import '@kitn.ai/ui/theme.tokens.css';  // compiled token defaults; use theme.css only for Tailwind-source apps`,
     vueImports,
@@ -3321,6 +3873,7 @@ function renderVue(components, ctx) {
     ...toolsLines,
     ...runnerLines,
     ...sourcesSeed,
+    ...attachmentScript,
     ``,
     `// SCAF-15: kai-* register via an async dynamic import (SSR-safety). The .prop`,
     `// bindings can apply before the element upgrades, which drops them — re-apply once`,
@@ -3332,13 +3885,14 @@ function renderVue(components, ctx) {
     `  if (el) Object.assign(el, { messages: messages.value, loading: loading.value, suggestions${cardPropAssign.length ? `, ${cardPropAssign.join(", ")}` : ""} });`,
     `});`,
     ``,
-    `async function onSubmit(e: CustomEvent<{ value: string }>) {`,
+    `async function onSubmit(e: ${attachments ? "CustomEvent<{ value: string; attachments: AttachmentData[] }>" : "CustomEvent<{ value: string }>"}) {`,
     onSubmitBody,
     `}`,
     `<\/script>`,
     ``,
     `<template>`,
     `  <div style="${p.style}">`,
+    ...attachmentTemplate ? [attachmentTemplate] : [],
     ...workspaceTemplate,
     `  </div>`,
     `</template>`
@@ -3347,8 +3901,9 @@ function renderVue(components, ctx) {
 function renderSvelte(components, ctx) {
   const { p, emptyHint, suggestions, isMock, defaultModel, emitTools, emitToolLoop } = ctx;
   const workspace = isWorkspace(components);
+  const attachments = hasAttachments(components);
   const standaloneCompanionTags = components.filter(
-    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !WORKSPACE_STRUCTURAL_TAGS.has(t)
+    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !WORKSPACE_STRUCTURAL_TAGS.has(t) && !(attachments && ATTACHMENT_TAGS.has(t))
   );
   const hasEmbedded = components.some((t) => MESSAGE_EMBEDDED_TAGS.has(t));
   const hasSourcesCompanion = standaloneCompanionTags.includes("kai-sources");
@@ -3368,6 +3923,14 @@ function renderSvelte(components, ctx) {
     }
   }
   const companionLines = companionLinesList.join("\n");
+  const attachmentSubmitOpts = attachments ? {
+    filesExpr: "files",
+    afterValue: attachmentTurnLines({
+      stagedExpr: "staged",
+      clear: ["staged = [];"],
+      fromSubmitEvent: true
+    })
+  } : {};
   const onSubmitBody = realStreamBody({
     pad: "    ",
     read: "messages",
@@ -3379,7 +3942,8 @@ function renderSvelte(components, ctx) {
     toolLoop: emitToolLoop,
     cards: ctx.emitCards,
     thread: liveThreadBinding("messages", "(fn) => { messages = fn(messages); }"),
-    mock: isMock
+    mock: isMock,
+    ...attachmentSubmitOpts
   });
   const mockInit = isMock ? mockResponderInit("  ") : [];
   const modelInit = defaultModel ? [
@@ -3405,6 +3969,33 @@ function renderSvelte(components, ctx) {
     `  ];`,
     `  $effect(() => { if (sourcesEl) { sourcesEl.sources = sampleSources; } });`
   ] : [];
+  const attachmentScript = attachments ? [
+    ...ATTACHMENT_WIRE_NOTE.map((l) => `  ${l}`),
+    `  //`,
+    `  // AttachmentData is the kit's own type for a staged file, and it is what`,
+    `  // <kai-attachments>.items and a 'file' MessagePart both hold.`,
+    `  let attachmentsEl = $state<KaiAttachmentsElement | undefined>(undefined);`,
+    `  let staged = $state.raw<AttachmentData[]>([]);`,
+    `  $effect(() => { if (attachmentsEl && defined) { attachmentsEl.items = staged; } });`,
+    ``,
+    ...fileToAttachmentLines("  ", "AttachmentData"),
+    `  async function onFilesAdded(e: CustomEvent<{ files: File[] }>) {`,
+    `    // Read every file BEFORE appending: a per-file append would order the`,
+    `    // list by whichever finished reading first.`,
+    `    const added = await Promise.all(e.detail.files.map(toAttachment));`,
+    `    staged = [...staged, ...added];`,
+    `  }`,
+    `  function onRemoveAttachment(e: CustomEvent<{ id: string }>) {`,
+    `    staged = staged.filter((a) => a.id !== e.detail.id);`,
+    `  }`
+  ] : [];
+  const attachmentMarkup = attachments ? [
+    `  <!-- Drop files here to stage them for the NEXT message. -->`,
+    `  <div style="flex: 0 0 auto; display: flex; flex-direction: column; gap: 0.5rem; padding: 0.75rem;">`,
+    `    <kai-file-upload accept="${ATTACHMENT_ACCEPT}" onkai-files-added={onFilesAdded}></kai-file-upload>`,
+    `    <kai-attachments bind:this={attachmentsEl} variant="inline" removable onkai-remove={onRemoveAttachment}></kai-attachments>`,
+    `  </div>`
+  ] : [];
   const workspaceMarkup = workspace ? [
     `  <!-- SCAF-14: workspace split — chat pane left, artifact preview right. -->`,
     `  <!-- kai-resizable needs kai-resizable-item children to render panels. -->`,
@@ -3435,14 +4026,19 @@ function renderSvelte(components, ctx) {
     // KaiSourcesElement is only imported when a kai-sources companion is actually
     // declared below: an always-on import would be unused (and fail noUnusedLocals)
     // on every archetype without kai-sources.
-    `  import type { ${hasSourcesCompanion ? "KaiChatElement, KaiSourcesElement" : "KaiChatElement"} } from '@kitn.ai/ui/elements';`,
+    `  import type { ${[
+      "KaiChatElement",
+      ...hasSourcesCompanion ? ["KaiSourcesElement"] : [],
+      ...attachments ? ["KaiAttachmentsElement"] : []
+    ].join(", ")} } from '@kitn.ai/ui/elements';`,
     ...wireImportLines({
       pad: "  ",
       typed: true,
       toolLoop: emitToolLoop,
       cards: ctx.emitCards,
       cardTools: ctx.cardProvider !== null,
-      mock: isMock
+      mock: isMock,
+      attachments
     }),
     `  import '@kitn.ai/ui/theme.tokens.css';  // compiled token defaults; use theme.css only for Tailwind-source apps`,
     `  import { onMount } from 'svelte';`,
@@ -3468,13 +4064,15 @@ function renderSvelte(components, ctx) {
     `    if (chatEl && defined) { chatEl.messages = messages; chatEl.loading = loading; chatEl.suggestions = suggestions;${cardPropEffect} }`,
     `  });`,
     ...sourcesReactive,
+    ...attachmentScript,
     ``,
-    `  async function onSubmit(e: CustomEvent<{ value: string }>) {`,
+    `  async function onSubmit(e: ${attachments ? "CustomEvent<{ value: string; attachments: AttachmentData[] }>" : "CustomEvent<{ value: string }>"}) {`,
     onSubmitBody,
     `  }`,
     `<\/script>`,
     ``,
     `<div style="${p.style}">`,
+    ...attachmentMarkup,
     ...workspaceMarkup,
     `</div>`
   ].filter((l, i, arr) => !(l === "" && arr[i - 1] === "" && i === arr.length - 1)).join("\n");
@@ -3487,8 +4085,9 @@ function renderTanstackStart(components, ctx) {
   const importTags = workspace ? [.../* @__PURE__ */ new Set([...renderableTags.filter((t) => t !== "kai-resizable"), "kai-resizable", "kai-resizable-item"])] : renderableTags;
   const wrapperNames = importTags.map(toPascalCase);
   const importList = wrapperNames.join(", ");
+  const attachments = hasAttachments(components);
   const standaloneCompanionTags = components.filter(
-    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !WORKSPACE_STRUCTURAL_TAGS.has(t)
+    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !WORKSPACE_STRUCTURAL_TAGS.has(t) && !(attachments && ATTACHMENT_TAGS.has(t))
   );
   const companionJsxLines = [];
   if (hasEmbedded) {
@@ -3509,6 +4108,41 @@ function renderTanstackStart(components, ctx) {
     }
   }
   const companions = companionJsxLines.join("\n");
+  const attachmentJsx = attachments ? [
+    `      {/* Drop files here to stage them for the NEXT message. */}`,
+    `      <div style={{ flex: '0 0 auto', display: 'flex', flexDirection: 'column', gap: '0.5rem', padding: '0.75rem' }}>`,
+    `        <FileUpload accept="${ATTACHMENT_ACCEPT}" onFilesAdded={onFilesAdded} />`,
+    `        {/* items is an ARRAY, so the wrapper sets it as a DOM property, never an attribute. */}`,
+    `        <Attachments items={staged} variant="inline" removable onRemove={onRemoveAttachment} />`,
+    `      </div>`
+  ].join("\n") : "";
+  const attachmentModuleInit = attachments ? [
+    ...ATTACHMENT_WIRE_NOTE,
+    `//`,
+    `// AttachmentData is the kit's own type for a staged file — the same one`,
+    `// <Attachments>.items holds and the same one a 'file' message part holds.`,
+    ...fileToAttachmentLines("", "AttachmentData")
+  ] : [];
+  const attachmentStateInit = attachments ? [
+    `  const [staged, setStaged] = useState<AttachmentData[]>([]);`,
+    `  const onFilesAdded = async (e: CustomEvent<{ files: File[] }>) => {`,
+    `    // Read every file BEFORE appending: a per-file append would order the`,
+    `    // list by whichever finished reading first.`,
+    `    const added = await Promise.all(e.detail.files.map(toAttachment));`,
+    `    setStaged((prev) => [...prev, ...added]);`,
+    `  };`,
+    `  const onRemoveAttachment = (e: CustomEvent<{ id: string }>) =>`,
+    `    setStaged((prev) => prev.filter((a) => a.id !== e.detail.id));`
+  ].join("\n") : "";
+  const attachmentSubmitOpts = attachments ? {
+    filesExpr: "files",
+    afterValue: attachmentTurnLines({
+      stagedExpr: "staged",
+      clear: ["setStaged([]);"],
+      fromSubmitEvent: true
+    })
+  } : {};
+  const submitParamType = attachments ? "CustomEvent<{ value: string; attachments: AttachmentData[] }>" : "CustomEvent<{ value: string }>";
   const mockInit = isMock ? mockResponderInit() : [];
   const sampleMessagesInit = [
     ...hasEmbedded ? sampleSeedComment(isMock, "  ", (literal) => [
@@ -3543,7 +4177,8 @@ function renderTanstackStart(components, ctx) {
     toolLoop: emitToolLoop,
     cards: ctx.emitCards,
     thread: REACT_THREAD,
-    mock: isMock
+    mock: isMock,
+    ...attachmentSubmitOpts
   });
   const filePathNote = [
     `// TanStack Start route file — save as: src/routes/chat.tsx`,
@@ -3573,7 +4208,8 @@ function renderTanstackStart(components, ctx) {
       setMessagesType: emitToolLoop,
       cards: ctx.emitCards,
       cardTools: ctx.cardProvider !== null,
-      mock: isMock
+      mock: isMock,
+      attachments
     }),
     `import '@kitn.ai/ui/theme.tokens.css'  // compiled token defaults`,
     ``,
@@ -3581,6 +4217,7 @@ function renderTanstackStart(components, ctx) {
     ...(p.altNote ?? []).map((l) => `// ${l}`),
     ...mockInit,
     ``,
+    ...attachmentModuleInit,
     ...cardsInit,
     `// ssr: false keeps the Solid-based web component client-only.`,
     `// Server HTML for /chat omits <kai-chat> → no hydration mismatch.`,
@@ -3593,17 +4230,19 @@ function renderTanstackStart(components, ctx) {
     sampleMessagesInit,
     `  const [loading, setLoading] = useState(false);`,
     `  const suggestions = ${jsArray(suggestions)};`,
+    ...attachmentStateInit ? [attachmentStateInit] : [],
     ...sampleSourcesInit ? [sampleSourcesInit] : [],
     ...modelInit ? [modelInit] : [],
     ...toolsInit ? [toolsInit] : [],
     ...toolRunner ? [toolRunner] : [],
     ``,
-    `  async function onSubmit(e: CustomEvent<{ value: string }>) {`,
+    `  async function onSubmit(e: ${submitParamType}) {`,
     onSubmitBody,
     `  }`,
     ``,
     `  return (`,
     `    <main style={{ ${jsxStyle(p.style)} }}>`,
+    ...attachmentJsx ? [attachmentJsx] : [],
     ...workspace ? [
       `      {/* SCAF-14: workspace split — chat pane left, artifact preview right. */}`,
       `      {/* Resizable needs ResizableItem children to render panels. */}`,
@@ -3648,8 +4287,9 @@ function renderTanstackStart(components, ctx) {
 function renderAngular(components, ctx) {
   const { p, emptyHint, suggestions, isMock, defaultModel, emitTools, emitToolLoop } = ctx;
   const workspace = isWorkspace(components);
+  const attachments = hasAttachments(components);
   const standaloneCompanionTags = components.filter(
-    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !WORKSPACE_STRUCTURAL_TAGS.has(t)
+    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !WORKSPACE_STRUCTURAL_TAGS.has(t) && !(attachments && ATTACHMENT_TAGS.has(t))
   );
   const hasEmbedded = components.some((t) => MESSAGE_EMBEDDED_TAGS.has(t));
   const hasSourcesCompanion = standaloneCompanionTags.includes("kai-sources");
@@ -3670,6 +4310,46 @@ function renderAngular(components, ctx) {
       companionLines.push(`      <${t}></${t}>`);
     }
   }
+  const attachmentTemplate = attachments ? [
+    `      <!-- Drop files here to stage them for the NEXT message. -->`,
+    `      <div style="flex: 0 0 auto; display: flex; flex-direction: column; gap: 0.5rem; padding: 0.75rem;">`,
+    `        <kai-file-upload accept="${ATTACHMENT_ACCEPT}" (kai-files-added)="onFilesAdded($event)"></kai-file-upload>`,
+    `        <kai-attachments [items]="staged()" variant="inline" removable (kai-remove)="onRemoveAttachment($event)"></kai-attachments>`,
+    `      </div>`
+  ] : [];
+  const attachmentModuleInit = attachments ? [
+    ...ATTACHMENT_WIRE_NOTE,
+    `//`,
+    `// AttachmentData is the kit's own type for a staged file, and it is what`,
+    `// <kai-attachments>.items and a 'file' MessagePart both hold.`,
+    ...fileToAttachmentLines("", "AttachmentData"),
+    ``
+  ] : [];
+  const attachmentFields = attachments ? [
+    `  readonly staged = signal<AttachmentData[]>([]);`,
+    ``,
+    `  // Same Event-not-CustomEvent rule as onSubmit below: strictTemplates types`,
+    `  // $event on an unknown custom-element event as a plain Event.`,
+    `  async onFilesAdded(event: Event) {`,
+    `    const { files } = (event as CustomEvent<{ files: File[] }>).detail;`,
+    `    // Read every file BEFORE appending: a per-file append would order the`,
+    `    // list by whichever finished reading first.`,
+    `    const added = await Promise.all(files.map(toAttachment));`,
+    `    this.staged.set([...this.staged(), ...added]);`,
+    `  }`,
+    `  onRemoveAttachment(event: Event) {`,
+    `    const { id } = (event as CustomEvent<{ id: string }>).detail;`,
+    `    this.staged.set(this.staged().filter((a) => a.id !== id));`,
+    `  }`
+  ] : [];
+  const attachmentSubmitOpts = attachments ? {
+    filesExpr: "files",
+    afterValue: attachmentTurnLines({
+      stagedExpr: "this.staged()",
+      clear: ["this.staged.set([]);"],
+      fromSubmitEvent: true
+    })
+  } : {};
   const read = "this.messages()";
   const commit = (value) => `this.messages.set(${value});`;
   const setter = "(fn) => this.messages.set(fn(this.messages()))";
@@ -3684,7 +4364,8 @@ function renderAngular(components, ctx) {
     toolLoop: emitToolLoop,
     cards: ctx.emitCards,
     thread: accessorThreadBinding(read, commit, setter),
-    mock: isMock
+    mock: isMock,
+    ...attachmentSubmitOpts
   });
   const modelInit = defaultModel ? [
     `// SCAF-8: change this model id to another id THIS PROVIDER accepts.`,
@@ -3760,7 +4441,8 @@ function renderAngular(components, ctx) {
       toolLoop: emitToolLoop,
       cards: ctx.emitCards,
       cardTools: ctx.cardProvider !== null,
-      mock: isMock
+      mock: isMock,
+      attachments
     }),
     ``,
     `// ${ctx.label} — ${p.note}. empty-state hint: ${emptyHint}`,
@@ -3768,6 +4450,7 @@ function renderAngular(components, ctx) {
     ...isMock ? mockResponderInit() : [],
     ``,
     ...modelInit,
+    ...attachmentModuleInit,
     ...cardsInit,
     ...toolsLines,
     ...runnerLines,
@@ -3779,6 +4462,7 @@ function renderAngular(components, ctx) {
     `  schemas: [CUSTOM_ELEMENTS_SCHEMA],`,
     `  template: \``,
     `    <div style="${p.style}">`,
+    ...attachmentTemplate,
     ...templateBody,
     `    </div>`,
     `  \`,`,
@@ -3811,11 +4495,13 @@ function renderAngular(components, ctx) {
     `    });`,
     `  }`,
     ``,
+    ...attachmentFields,
+    ``,
     `  // \`Event\`, not \`CustomEvent\`: under strictTemplates Angular types \`$event\` on`,
     `  // an unknown custom-element event as a plain Event, so the narrowing happens`,
     `  // here rather than in the signature.`,
     `  async onSubmit(event: Event) {`,
-    `    const e = event as CustomEvent<{ value: string }>;`,
+    `    const e = event as CustomEvent<{ value: string${attachments ? "; attachments: AttachmentData[]" : ""} }>;`,
     onSubmitBody,
     `  }`,
     `}`
@@ -3824,8 +4510,9 @@ function renderAngular(components, ctx) {
 function renderSolid(components, ctx) {
   const { p, emptyHint, suggestions, isMock, defaultModel, emitTools, emitToolLoop } = ctx;
   const workspace = isWorkspace(components);
+  const attachments = hasAttachments(components);
   const standaloneCompanionTags = components.filter(
-    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !WORKSPACE_STRUCTURAL_TAGS.has(t)
+    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !WORKSPACE_STRUCTURAL_TAGS.has(t) && !(attachments && ATTACHMENT_TAGS.has(t))
   );
   const hasSources = standaloneCompanionTags.includes("kai-sources");
   const hasVoice = standaloneCompanionTags.includes("kai-voice-input");
@@ -3856,7 +4543,13 @@ function renderSolid(components, ctx) {
     "SourceTrigger",
     "Tool",
     ...workspace ? ["Artifact", "ResizableHandle", "ResizablePanel", "ResizablePanelGroup"] : [],
-    ...hasVoice ? ["VoiceInput"] : []
+    ...hasVoice ? ["VoiceInput"] : [],
+    // `Attachments`/`Attachment`/`AttachmentPreview`/`AttachmentInfo` are already
+    // unconditional above — `renderPart` draws `file` PARTS with them whatever the
+    // surface asked for. These three are the STAGING half, which only this
+    // capability composes: the dropzone, its trigger, and the per-chip remove
+    // button `renderPart` has no use for (a sent file is not removable).
+    ...attachments ? ["AttachmentRemove", "FileUpload", "FileUploadTrigger"] : []
   ].sort();
   const read = "messages()";
   const commit = (value) => `setMessages(${value});`;
@@ -3873,7 +4566,17 @@ function renderSolid(components, ctx) {
     cards: ctx.emitCards,
     thread: accessorThreadBinding(read, commit, setter),
     valueSource: "input()",
-    afterValue: [`setInput('');`],
+    // The staged files are captured BEFORE either list is cleared. `setInput('')`
+    // stays last so the order reads the way it executes.
+    afterValue: [
+      ...attachments ? attachmentTurnLines({
+        stagedExpr: "staged()",
+        clear: ["setStaged([]);"],
+        fromSubmitEvent: false
+      }) : [],
+      `setInput('');`
+    ],
+    ...attachments ? { filesExpr: "files" } : {},
     mock: isMock
   });
   const modelInit = defaultModel ? [
@@ -3887,6 +4590,11 @@ function renderSolid(components, ctx) {
     `            types={cards.components}`,
     `            schemas={cards.validationSchemas}`
   ] : [];
+  const attachmentInit = attachments ? [
+    ...ATTACHMENT_WIRE_NOTE.map((l) => `  ${l}`),
+    `  const [staged, setStaged] = createSignal<AttachmentData[]>([]);`,
+    ...fileToAttachmentLines("  ", "AttachmentData")
+  ] : [];
   const sourcesInit = hasSources ? [
     `  // Replace sampleSources with your real source data.`,
     `  const sampleSources = [`,
@@ -3962,6 +4670,35 @@ function renderSolid(components, ctx) {
     `          </For>`,
     `        </div>`,
     `      </Show>`,
+    ...attachments ? [
+      `      {/* Drop files here to stage them for the NEXT message. */}`,
+      `      <div class="flex flex-col gap-2 pb-3">`,
+      `        {/* Read every file BEFORE appending: a per-file append would order`,
+      `            the list by whichever finished reading first. */}`,
+      `        <FileUpload`,
+      `          accept="${ATTACHMENT_ACCEPT}"`,
+      `          onFilesAdded={async (files) => setStaged([...staged(), ...(await Promise.all(files.map(toAttachment)))])}`,
+      `        >`,
+      `          <FileUploadTrigger class="border-border text-muted-foreground w-full rounded-xl border border-dashed px-4 py-3 text-center text-sm">`,
+      `            Click or drop files to attach`,
+      `          </FileUploadTrigger>`,
+      `        </FileUpload>`,
+      `        {/* The staged chips. onRemove is what makes <AttachmentRemove> draw its button. */}`,
+      `        <Show when={staged().length > 0}>`,
+      `          <Attachments variant="inline">`,
+      `            <For each={staged()}>`,
+      `              {(a) => (`,
+      `                <Attachment data={a} onRemove={() => setStaged(staged().filter((x) => x.id !== a.id))}>`,
+      `                  <AttachmentPreview />`,
+      `                  <AttachmentInfo />`,
+      `                  <AttachmentRemove />`,
+      `                </Attachment>`,
+      `              )}`,
+      `            </For>`,
+      `          </Attachments>`,
+      `        </Show>`,
+      `      </div>`
+    ] : [],
     `      <PromptInput value={input()} onValueChange={setInput} onSubmit={onSubmit} isLoading={loading()}>`,
     `        <div class="flex flex-col">`,
     `          <PromptInputTextarea placeholder="Send a message…" class="min-h-[44px] pt-3 pl-4" />`,
@@ -4026,11 +4763,25 @@ function renderSolid(components, ctx) {
     `// every kit utility class as unused, and the whole UI renders unstyled.`,
     `// (theme.css here, not theme.tokens.css: this app compiles Tailwind itself.)`,
     `import { For, Index, Match, Show, Switch, createMemo, createSignal } from 'solid-js';`,
+    // '@kitn.ai/ui/solid', NOT the root '@kitn.ai/ui', and the difference is
+    // invisible to every compiler on this repo's critical path: src/solid.ts is
+    // `export * from './index'`, so ./solid is a strict SUPERSET of the root and
+    // both specifiers typecheck identically. verify:scaffold's solid project
+    // compiled clean the whole time this was wrong.
+    //
+    // The root is the shared layer EVERY consumer resolves — React, Vue, Svelte
+    // and vanilla included — so it deliberately carries only the chat components,
+    // types and helpers those frameworks can use. The rest of the Solid catalog
+    // lives on ./solid, built as its own bundle so a React app never pays for it.
+    // A Solid app pointed at the root therefore gets the smaller surface and finds
+    // out the hard way, one missing export at a time. The published guide says so
+    // outright ("Import Solid components from @kitn.ai/ui/solid, not from the root
+    // @kitn.ai/ui"), and this generator contradicted it for every Solid scaffold.
     `import {`,
     ...componentImports.map((n) => `  ${n},`),
-    `} from '@kitn.ai/ui';`,
+    `} from '@kitn.ai/ui/solid';`,
     `// The kit's own types, from the same entry the components come from.`,
-    `import type { ChatMessage, MessagePart, MessageSource } from '@kitn.ai/ui';`,
+    `import type { ${attachments ? "AttachmentData, ChatMessage, MessagePart, MessageSource" : "ChatMessage, MessagePart, MessageSource"} } from '@kitn.ai/ui/solid';`,
     ...wireImportLines({
       typed: false,
       toolLoop: emitToolLoop,
@@ -4230,6 +4981,7 @@ function renderSolid(components, ctx) {
     `  // value, no row moves, and the content updates through accessors instead.`,
     `  const messageKeys = createMemo(() => messages().map((m) => m.id));`,
     `  const suggestions = ${jsArray(suggestions)};`,
+    ...attachmentInit,
     ...sourcesInit,
     ...modelInit,
     ...toolsLines,
@@ -4676,12 +5428,72 @@ const CHAT_REQUEST_BODY_DECL = [
   `  return (await request.json()) as ChatRequestBody;`,
   `}`
 ];
+const CONTENT_PARTS_DECL = [
+  `/** Where an attachment's bytes are: inline base64, or an address the PROVIDER`,
+  ` *  fetches. Never both. */`,
+  `type WireFileSource = { type: 'data'; data: string } | { type: 'url'; url: string };`,
+  ``,
+  `/** One piece of a turn, with the string and array content forms flattened into`,
+  ` *  a single shape. */`,
+  `type WirePart =`,
+  `  | { kind: 'text'; text: string }`,
+  `  | { kind: 'file'; mediaType: string; filename?: string; source: WireFileSource };`,
+  ``,
+  `const DATA_URI = /^data:([^;,]+);base64,([\\s\\S]*)$/;`,
+  ``,
+  `/**`,
+  ` * Flatten a wire message's content into parts.`,
+  ` *`,
+  ` * An image sent by URL has no media type here — \`image_url\` carries only the`,
+  ` * address — so it reports the top-level segment \`'image'\`, which is all a URL`,
+  ` * source needs. Only images can reach that branch: the kit refuses to encode a`,
+  ` * remote PDF rather than guess at one.`,
+  ` */`,
+  `function wireParts(content: OpenAIWireMessage['content']): WirePart[] {`,
+  `  if (content == null) return [];`,
+  `  if (typeof content === 'string') return content === '' ? [] : [{ kind: 'text', text: content }];`,
+  `  return content.map((part): WirePart => {`,
+  `    if (part.type === 'text') return { kind: 'text', text: part.text };`,
+  `    if (part.type === 'image_url') {`,
+  `      const asData = DATA_URI.exec(part.image_url.url);`,
+  `      return asData`,
+  `        ? { kind: 'file', mediaType: asData[1], source: { type: 'data', data: asData[2] } }`,
+  `        : { kind: 'file', mediaType: 'image', source: { type: 'url', url: part.image_url.url } };`,
+  `    }`,
+  `    const asData = DATA_URI.exec(part.file.file_data);`,
+  `    if (!asData) {`,
+  `      // LOUD on purpose. \`file_data\` is a data URI on this wire; anything else`,
+  `      // cannot be turned into bytes without fetching it, and forwarding a turn`,
+  `      // with the attachment quietly missing is the bug this whole path exists`,
+  `      // to prevent.`,
+  `      throw new Error(`,
+  `        'Unsupported file content part: file_data must be a data: URI of the form data:<media type>;base64,<data>.',`,
+  `      );`,
+  `    }`,
+  `    return {`,
+  `      kind: 'file',`,
+  `      mediaType: asData[1],`,
+  `      filename: part.file.filename,`,
+  `      source: { type: 'data', data: asData[2] },`,
+  `    };`,
+  `  });`,
+  `}`,
+  ``,
+  `/** Just the text of a turn. System, assistant and tool messages are text-only`,
+  ` *  on this wire, so this collapses the array form for them. */`,
+  `function wireText(content: OpenAIWireMessage['content']): string {`,
+  `  return wireParts(content)`,
+  `    .map((p) => (p.kind === 'text' ? p.text : ''))`,
+  `    .join('');`,
+  `}`
+];
 function withChatRequestBody(fragment) {
+  const decl = /\bwire(?:Parts|Text)\s*\(/.test(fragment) ? [...CHAT_REQUEST_BODY_DECL, ``, ...CONTENT_PARTS_DECL] : CHAT_REQUEST_BODY_DECL;
   const lines = fragment.split("\n");
   let at = lines.findIndex((l) => /^(?:export\s+)?async function chatHandler\b/.test(l));
-  if (at < 0) return [...CHAT_REQUEST_BODY_DECL, ``, ...lines].join("\n");
+  if (at < 0) return [...decl, ``, ...lines].join("\n");
   while (at > 0 && /^\s*(?:\/\/|\/\*|\*)/.test(lines[at - 1])) at -= 1;
-  return [...lines.slice(0, at), ...CHAT_REQUEST_BODY_DECL, ``, ...lines.slice(at)].join("\n");
+  return [...lines.slice(0, at), ...decl, ``, ...lines.slice(at)].join("\n");
 }
 function webRouteFor(integration, framework) {
   const fragment = integration.webRoute;
@@ -5067,7 +5879,7 @@ function rejectUseCase(id) {
     ``,
     `Valid useCases (presets): ${valid}.`,
     ``,
-    // The presets are six points, not the space. A harness that only ever learns
+    // The presets are seven points, not the space. A harness that only ever learns
     // the six ids will ask for the nearest one instead of the surface it wants,
     // so the rejection that teaches the id list is the right place to say so.
     `These are PRESETS over the real axis, which is \`components\`. To compose a surface no`,
@@ -5086,14 +5898,14 @@ const scaffold = {
     // catalogs to discover valid ids.
     //
     // `useCase` is OPTIONAL because `components` can carry the surface instead —
-    // the archetypes are six points in the components space, not the space. A
+    // the archetypes are seven points in the components space, not the space. A
     // request must still name one of the two, and the handler says so when it
     // names neither.
     useCase: z$1.string().optional().describe(
-      'Archetype PRESET id, e.g. "drop-in-chat", "support-widget", "knowledge-base", "agentic", "workspace", "voice". Shorthand for the preset\'s `components`. Omit it and pass `components` to compose a surface no preset names.'
+      'Archetype PRESET id, e.g. "drop-in-chat", "support-widget", "knowledge-base", "agentic", "workspace", "voice", "attachments". Shorthand for the preset\'s `components`. Omit it and pass `components` to compose a surface no preset names.'
     ),
     components: z$1.array(z$1.string()).optional().describe(
-      'The kai-* components this surface composes, e.g. ["kai-chat", "kai-tool", "kai-reasoning", "kai-artifact", "kai-resizable"]. The real axis: any combination is renderable, not just the six presets. Include "kai-chat". Wins over `useCase` when both are given.'
+      'The kai-* components this surface composes, e.g. ["kai-chat", "kai-tool", "kai-reasoning", "kai-artifact", "kai-resizable"]. The real axis: any combination is renderable, not just the seven presets. Include "kai-chat". Wins over `useCase` when both are given.'
     ),
     integration: z$1.string().describe(
       'Backend integration id, e.g. "openrouter", "vercel-ai-sdk", "langgraph", "cloudflare", "ollama", "mastra", "pi", "pydantic-ai".'