@andreprado/agentkit 0.1.0-alpha.5 → 0.1.0-alpha.6

package/docs/guides/connect-whatsapp-zapster.md

@@ -50,6 +50,22 @@ export default defineAgent({
 });
 ```
 
+To handle clients who send several WhatsApp messages before waiting, enable channel buffering:
+
+```ts
+whatsappChannel({
+  name: "support-whatsapp",
+  provider: "zapster",
+  buffer: {
+    mode: "debounce",
+    quietWindowMs: 2500,
+    maxWaitMs: 12000,
+    maxMessages: 20,
+    maxChars: 8000,
+  },
+})
+```
+
 ## Setup Behavior
 
 `agentkit channels setup support-whatsapp` prints the stable AgentKit webhook URL. Paste it into Zapster webhook settings and configure Zapster to send the same shared secret as `ZAPSTER_WEBHOOK_SECRET`.

package/docs/guides/create-agent.md

@@ -84,7 +84,7 @@ Primary flow:
 Develop an appointment and intake agent for an ophthalmology office.
 ```
 
-The generated `AGENTS.md`, `AGENTKIT.md`, and `CLAUDE.md` tell the coding agent which files to edit and which verification commands to run. There is no wizard or recipe layer: the coding agent edits the capsule directly from the scaffold, contract, and owner request.
+The generated `AGENTS.md`, `AGENTKIT.md`, `CLAUDE.md`, and `skills/` pack tell the coding agent which files to edit, which task skill to load, and which verification commands to run. There is no wizard or recipe layer: the coding agent edits the capsule directly from the scaffold, contract, and owner request. The default router is `skills/agentkit-capsule/SKILL.md`; `llms-full.txt` is reserved for complete-contract checks.
 
 Optional shortcut when copying a prompt into another coding agent:
 

package/docs/llms-full.txt

@@ -40,6 +40,10 @@ agentkit chat-ui --deploy
 agentkit chat-ui --deploy [--port <number>] [--token-file <path>]
 agentkit chat --message <text> [--conversation-id <id>]
 agentkit tool <name> [--input <path-or-json>]
+agentkit knowledge add <path-or-url>
+agentkit knowledge sync
+agentkit knowledge inspect
+agentkit knowledge search <query> [--top-k <number>]
 agentkit db migrate
 agentkit db reset --yes
 agentkit db shell
@@ -144,7 +148,7 @@ npm run agentkit -- handoff codex "Develop an appointment and intake agent for a
 npm run agentkit -- handoff claude "Develop an appointment and intake agent for an ophthalmology office."
 ```
 
-The command prints a ready-to-paste prompt that points the coding agent at `AGENTKIT.md` and the packaged `llms-full.txt` contract.
+The command prints a ready-to-paste prompt that points the coding agent at `AGENTKIT.md`, the repo-local `skills/agentkit-capsule/SKILL.md` router when present, and the packaged `llms.txt` docs router. Load `llms-full.txt` only when a skill or ambiguous framework behavior requires the complete contract.
 
 The generated docs and handoff prompt must make UI testing explicit. For local UI testing, run `npm run dev`, open the printed `Chat:` URL, and tell the owner the exact URL. For hosted UI testing after deploy, run `npm run agentkit -- chat-ui --deploy`, open the printed `Chat:` URL, and tell the owner it is connected to the hosted deploy.
 
@@ -239,6 +243,73 @@ npm run chat -- --message "hello"
 
 If a provider key is missing, the runtime returns `secret_not_found`.
 
+## Knowledge Contract
+
+Knowledge is AgentKit's native retrieval layer for facts the agent should ground in source files. Use it for FAQs, prices, policies, service descriptions, procedures, CSV tables, and reference docs. Do not put secrets, credentials, `.env` contents, or live customer/payment records in Knowledge. Use tools for live or authorization-sensitive data.
+
+Configure Knowledge in `agentkit.config.ts`:
+
+```ts
+knowledge: {
+  sources: [
+    "knowledge/faq.md",
+    { path: "knowledge/prices.csv", title: "Prices" },
+  ],
+  retrieval: {
+    topK: 8,
+    hybrid: false,
+  },
+},
+```
+
+Local Knowledge supports `.md`, `.markdown`, `.txt`, and `.csv` sources inside the Agent Capsule. Markdown chunks follow headings, text chunks follow paragraphs, and CSV chunks preserve row data with headers.
+
+Embeddings are configured separately from the chat provider. The default provider is `none`, which gives local lexical search without an API key. For OpenAI embeddings:
+
+```ts
+knowledge: {
+  sources: ["knowledge/faq.md"],
+  embedding: {
+    provider: "openai",
+    model: "text-embedding-3-small",
+    secret: "KNOWLEDGE_OPENAI_API_KEY",
+  },
+  retrieval: {
+    topK: 8,
+    hybrid: true,
+  },
+},
+```
+
+Set the local embedding secret with `agentkit env set KNOWLEDGE_OPENAI_API_KEY --stdin`. Do not commit the value.
+
+Knowledge commands:
+
+```sh
+agentkit knowledge add knowledge/faq.md
+agentkit knowledge sync
+agentkit knowledge inspect
+agentkit knowledge search "refund policy" --top-k 3
+```
+
+`knowledge add` indexes one local path. `knowledge sync` indexes all configured `knowledge.sources` and skips unchanged files by content hash. `agentkit dev` and `agentkit chat` also sync configured Knowledge automatically before local runs. `knowledge inspect` lists indexed sources and chunk counts. `knowledge search` validates retrieval before relying on the agent. When embeddings are configured locally, AgentKit stores canonical chunks in `.agentkit/agentkit.db`, rebuilds a local libSQL vector sidecar at `.agentkit/agentkit.vectors.db`, uses native `libsql_vector_idx` semantic search, and falls back to stored JSON embeddings if the native vector path is unavailable.
+
+When `knowledge` is configured, AgentKit automatically registers the internal chat tool `agentkit_search_knowledge` and appends a prompt policy. The policy tells the agent to search before answering business-specific factual questions and not to expose raw retrieval JSON, scores, chunk IDs, or tool output objects. With `test/fake`, verify the internal tool directly:
+
+```sh
+agentkit chat --message '{"tool":"agentkit_search_knowledge","input":{"query":"refund policy","topK":1}}'
+```
+
+Expected output:
+
+```txt
+Tool agentkit_search_knowledge: completed
+```
+
+Cloudflare Knowledge deploys require `storage.driver: "agentkit"` and `storage.database.driver: "turso"`. `agentkit deploy doctor` and `agentkit build --target cloudflare` fail clearly when Knowledge is configured without Turso. Cloudflare artifacts include the Knowledge manifest, required embedding secret names, internal Knowledge schema, packaged local source contents, prompt policy, and hosted `agentkit_search_knowledge` runtime. During `agentkit deploy`, AgentKit Cloud applies the Knowledge schema, chunks packaged local sources, creates embeddings when configured, deletes stale hosted sources, and syncs sources, chunks, embedding metadata, FTS rows, and a native Turso `libsql_vector_idx` index into the project Turso database before publishing the Worker. Local `agentkit knowledge add/sync`, `agentkit dev`, and `agentkit chat` index configured Knowledge into local SQLite and the local libSQL vector sidecar; hosted deploy syncs configured local Knowledge sources automatically from the deploy artifact so private source material and embedding secrets do not move into client code. Hosted semantic search uses Turso native vector search when embeddings are configured and falls back to stored JSON embeddings if the native vector path is unavailable.
+
+Full guide: `docs/guides/add-knowledge.md`.
+
 ## Channel Contract
 
 Channels are hosted inbound/outbound conversation transports. They are separate from tools: channels receive user messages, while tools let the agent call external systems.
@@ -272,6 +343,24 @@ Rules:
 - Config stores secret names only, never secret values.
 - AgentKit owns channel webhook URLs, dedupe, identities, queue state, and delivery logs.
 - Do not store channel plumbing in the user's Turso database.
+- Use `buffer.mode: "debounce"` when a channel should coalesce rapid client messages into one agent run.
+- Buffered deliveries show `buffered`, then flush to one `queued` run after `quietWindowMs`, `maxWaitMs`, `maxMessages`, or `maxChars`.
+
+Channel buffer example:
+
+```ts
+whatsappChannel({
+  name: "support-whatsapp",
+  provider: "zapster",
+  buffer: {
+    mode: "debounce",
+    quietWindowMs: 2500,
+    maxWaitMs: 12000,
+    maxMessages: 20,
+    maxChars: 8000,
+  },
+})
+```
 
 Useful guides:
 

package/docs/llms.txt

@@ -2,12 +2,13 @@
 
 AgentKit creates and runs Agent Capsules: folders with `agentkit.config.ts`, prompts, tools, evals, local storage, and agent-facing docs.
 
-Read `docs/llms-full.txt` when you need the whole operating contract.
+Read `docs/llms-full.txt` only when you need the whole operating contract.
 
 Task guides:
 
 - Create a capsule: `docs/guides/create-agent.md`
 - Add a TypeScript tool: `docs/guides/add-tool.md`
+- Add Knowledge from local docs/CSVs: `docs/guides/add-knowledge.md`
 - Run or prepare evals: `docs/guides/run-evals.md`
 - Switch from `test/fake` to a real provider: `docs/guides/use-provider.md`
 - Prepare for hosted deploy: `docs/guides/prepare-deploy.md`
@@ -15,11 +16,13 @@ Task guides:
 - Build container artifact: `agentkit build --target container`
 - Generate VPS handoff: `agentkit deploy --target vps --host agent.example.com --dry-run`
 - Add hosted channels: `docs/guides/add-channel.md`
+- Buffer rapid channel messages: `docs/guides/add-channel.md#buffer-bursty-messages`
 - Connect Telegram: `docs/guides/connect-telegram.md`
 - Connect WhatsApp through Zapster: `docs/guides/connect-whatsapp-zapster.md`
 - Follow channel webhook and delivery-log safety rules: `docs/guides/channel-security.md`
 - Prepare Channels for production: `docs/guides/channels-production-handoff.md`
 - Follow secret, access, and tool safety rules: `docs/guides/security-rules.md`
+- Plan repo-local skills for coding agents: `docs/guides/agentkit-skills-architecture.md`
 
 Current local commands:
 
@@ -33,6 +36,10 @@ agentkit env unset <NAME>
 agentkit handoff codex|claude [goal]
 agentkit chat --message "hello"
 agentkit tool <name> --input <path-or-json>
+agentkit knowledge add <path-or-url>
+agentkit knowledge sync
+agentkit knowledge inspect
+agentkit knowledge search <query> [--top-k <number>]
 agentkit eval run
 agentkit conversations list
 agentkit conversations show <conversation-id>
@@ -58,7 +65,7 @@ agentkit dev
 agentkit open
 ```
 
-Generated capsules include `AGENTKIT.md` and `AGENTS.md` so Codex, Claude Code, or another coding agent can treat the owner's natural-language request as the brief and start building immediately. `agentkit handoff codex "Develop an ophthalmology office intake agent"` is an optional prompt-printing shortcut for users who are not already inside a coding-agent workspace. There is no wizard or recipe layer: the coding agent edits the capsule directly from the scaffold and contract.
+Generated capsules include `AGENTKIT.md`, `AGENTS.md`, and a repo-local `skills/` pack so Codex, Claude Code, or another coding agent can treat the owner's natural-language request as the brief and start building immediately without loading the full contract by default. Start with `skills/agentkit-capsule/SKILL.md`, then load the task skill for the current work. `agentkit handoff codex "Develop an ophthalmology office intake agent"` is an optional prompt-printing shortcut for users who are not already inside a coding-agent workspace. There is no wizard or recipe layer: the coding agent edits the capsule directly from the scaffold and contract.
 
 UI testing is part of the handoff. For local UI testing, run `agentkit dev`, open the printed `Chat:` URL, and tell the owner the exact URL. After hosted deploy, run `agentkit chat-ui --deploy`, open the printed `Chat:` URL, and tell the owner it is connected to the deploy.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andreprado/agentkit",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.6",
   "private": false,
   "type": "module",
   "repository": {
@@ -35,6 +35,7 @@
   "dependencies": {
     "@earendil-works/pi-ai": "^0.75.5",
     "@earendil-works/pi-coding-agent": "^0.75.5",
+    "@libsql/client": "^0.15.15",
     "esbuild": "^0.28.0",
     "tsx": "^4.22.3",
     "typebox": "^1.1.38"

package/src/cli/commands/channels.ts

@@ -6,6 +6,7 @@ import { cloudFetch, cloudGet, cloudPost } from "../cloud-client";
 import { parseCloudApiUrl } from "../flags";
 import { loadAgentCapsule } from "../../runtime/config";
 import { readLocalDeployStateIfExists, type LocalDeployState } from "../../runtime/core/deploy-state";
+import type { AgentChannel } from "../../index";
 
 type DeployState = LocalDeployState;
 
@@ -17,6 +18,7 @@ type CloudChannel = {
   status: string;
   webhook_url: string;
   required_secrets: Array<{ name: string; status: string }>;
+  buffer?: AgentChannel["buffer"];
 };
 
 type CloudDelivery = {
@@ -70,11 +72,14 @@ export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
 
     const deployState = await readDeployStateRequired(process.cwd());
     const provider = channelProviderForCli(type, args.flags.provider);
+    const localChannel = await readLocalChannelConfig(process.cwd(), type, provider, name);
     const payload = {
       name,
       type,
       provider,
-      secrets: defaultChannelSecretsForCli(type, provider),
+      secrets: localChannel?.secrets ?? defaultChannelSecretsForCli(type, provider),
+      ...(localChannel?.limits ? { limits: channelLimitsForApi(localChannel.limits) } : {}),
+      ...(localChannel?.buffer ? { buffer: localChannel.buffer } : {}),
     };
     const response = await cloudPost<{ channel: CloudChannel }>(
       parseCloudApiUrl(args.flags.api),
@@ -280,6 +285,15 @@ function printChannelStatus(channel: CloudChannel): void {
   for (const secret of channel.required_secrets) {
     console.log(`  ${secret.name}: ${secret.status}`);
   }
+  if (channel.buffer) {
+    if (channel.buffer.mode === "off") {
+      console.log("Buffer: off");
+    } else {
+      console.log(
+        `Buffer: debounce quiet=${channel.buffer.quietWindowMs}ms max_wait=${channel.buffer.maxWaitMs}ms max_messages=${channel.buffer.maxMessages} max_chars=${channel.buffer.maxChars}`,
+      );
+    }
+  }
 }
 
 async function printChannelDeliverySummary(
@@ -352,6 +366,30 @@ function defaultChannelSecretsForCli(type: string, provider: string): string[] {
   return [];
 }
 
+async function readLocalChannelConfig(
+  cwd: string,
+  type: string,
+  provider: string,
+  name: string,
+): Promise<AgentChannel | null> {
+  const capsule = await loadAgentCapsule(cwd);
+  return (
+    (capsule.config.channels ?? []).find(
+      (channel) => channel.name === name && channel.type === type && channel.provider === provider,
+    ) ?? null
+  );
+}
+
+function channelLimitsForApi(limits: NonNullable<AgentChannel["limits"]>): {
+  messages_per_day?: number;
+  usd_per_day?: number;
+} {
+  return {
+    ...(limits.messagesPerDay ? { messages_per_day: limits.messagesPerDay } : {}),
+    ...(limits.usdPerDay ? { usd_per_day: limits.usdPerDay } : {}),
+  };
+}
+
 async function channelTestBody(
   channel: CloudChannel,
   messageFlag: string | boolean | undefined,

package/src/cli/commands/knowledge.ts

@@ -0,0 +1,136 @@
+import {
+  addKnowledgeSourceFromCwd,
+  listKnowledgeSourcesFromCwd,
+  syncKnowledgeSourcesFromCwd,
+} from "../../runtime/knowledge/ingest";
+import { searchKnowledgeFromCwd } from "../../runtime/knowledge/retrieve";
+import type { ParsedArgs } from "../args";
+
+export async function handleKnowledgeCommand(args: ParsedArgs): Promise<void> {
+  const [subcommand, ...rest] = args.positional;
+
+  if (subcommand === "add") {
+    const [source] = rest;
+
+    if (!source) {
+      throw new Error("Usage: agentkit knowledge add <path-or-url>");
+    }
+
+    const summary = await addKnowledgeSourceFromCwd(process.cwd(), source);
+    printIngestSummary("Knowledge add", summary);
+    return;
+  }
+
+  if (subcommand === "sync") {
+    const summary = await syncKnowledgeSourcesFromCwd(process.cwd());
+    printIngestSummary("Knowledge sync", summary);
+    return;
+  }
+
+  if (subcommand === "inspect") {
+    const result = await listKnowledgeSourcesFromCwd(process.cwd());
+
+    console.log("Knowledge sources");
+    console.log(`Database: ${result.databasePath}`);
+
+    if (result.sources.length === 0) {
+      console.log("No knowledge sources indexed.");
+      return;
+    }
+
+    console.log("");
+    console.log("source\tstatus\tchunks\tupdated_at\ttitle");
+
+    for (const source of result.sources) {
+      console.log(
+        [
+          source.source,
+          source.status,
+          String(source.chunkCount),
+          source.updatedAt,
+          source.title ?? "",
+        ].join("\t"),
+      );
+    }
+
+    return;
+  }
+
+  if (subcommand === "search") {
+    const query = rest.join(" ").trim();
+
+    if (!query) {
+      throw new Error("Usage: agentkit knowledge search <query> [--top-k <number>]");
+    }
+
+    const topK = parseTopK(args.flags["top-k"] ?? args.flags.topK);
+    const result = await searchKnowledgeFromCwd(process.cwd(), query, { topK });
+
+    console.log("Knowledge search");
+    console.log(`Database: ${result.databasePath}`);
+    console.log(`Query:    ${query}`);
+
+    if (result.results.length === 0) {
+      console.log("No matching knowledge chunks found.");
+      return;
+    }
+
+    console.log("");
+
+    for (const [index, item] of result.results.entries()) {
+      const source = [
+        item.source.path,
+        item.source.section ? `section: ${item.source.section}` : null,
+        item.source.locator,
+      ].filter(Boolean).join(" | ");
+
+      console.log(`${index + 1}. ${source}`);
+      console.log(`   score: ${item.score}`);
+      console.log(`   ${oneLine(item.content)}`);
+    }
+
+    return;
+  }
+
+  throw new Error(
+    "Usage: agentkit knowledge add <path-or-url> | sync | inspect | search <query> [--top-k <number>]",
+  );
+}
+
+function printIngestSummary(label: string, summary: Awaited<ReturnType<typeof addKnowledgeSourceFromCwd>>): void {
+  console.log(label);
+  console.log(`Database: ${summary.databasePath}`);
+  console.log(`${summary.indexed} indexed, ${summary.skipped} skipped, ${summary.failed} failed, ${summary.chunksCreated} chunks`);
+
+  if (summary.results.length > 0) {
+    console.log("");
+    console.log("source\tstatus\tchunks\tmessage");
+
+    for (const result of summary.results) {
+      console.log([result.source, result.status, String(result.chunksCreated), result.message].join("\t"));
+    }
+  }
+
+  if (summary.failed > 0) {
+    process.exitCode = 1;
+  }
+}
+
+function parseTopK(value: unknown): number | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  const topK = Number(value);
+
+  if (!Number.isInteger(topK) || topK <= 0 || topK > 50) {
+    throw new Error("knowledge search --top-k must be a positive integer no larger than 50.");
+  }
+
+  return topK;
+}
+
+function oneLine(value: string): string {
+  const compact = value.replace(/\s+/g, " ").trim();
+  return compact.length <= 220 ? compact : `${compact.slice(0, 217)}...`;
+}

package/src/cli/deploy-readiness.ts

@@ -179,6 +179,25 @@ export async function checkDeployReadiness(options: {
     });
   }
 
+  if (context.knowledge.enabled) {
+    if (context.knowledge.databaseDriver !== "turso") {
+      checks.push({
+        status: "fail",
+        title: "Knowledge storage",
+        message: "Hosted Knowledge requires a Turso database so indexed chunks are available to the Cloudflare runtime.",
+        action: 'set storage.database.driver: "turso" in agentkit.config.ts before deploying Knowledge',
+      });
+    } else {
+      checks.push({
+        status: "pass",
+        title: "Knowledge storage",
+        message: `Knowledge is configured with ${context.knowledge.sourceCount} source${
+          context.knowledge.sourceCount === 1 ? "" : "s"
+        } and Turso storage.`,
+      });
+    }
+  }
+
   if (context.userManagedSecrets.length === 0) {
     checks.push({
       status: "pass",

package/src/cli/help.ts

@@ -21,6 +21,8 @@ Start:
   agentkit inspect
 
 Build:
+  agentkit knowledge add <path>
+  agentkit knowledge search <query>
   agentkit tool <name> [--input <path-or-json>]
   agentkit db migrate
   agentkit eval run
@@ -53,6 +55,10 @@ Usage:
   agentkit chat-ui --deploy [--port <number>] [--token-file <path>]
   agentkit chat --message <text> [--conversation-id <id>]
   agentkit tool <name> [--input <path-or-json>]
+  agentkit knowledge add <path-or-url>
+  agentkit knowledge sync
+  agentkit knowledge inspect
+  agentkit knowledge search <query> [--top-k <number>]
   agentkit db migrate
   agentkit db reset --yes
   agentkit db shell
@@ -106,6 +112,7 @@ Commands:
   chat-ui         Run a local chat UI, optionally pointed at a hosted deploy
   chat            Send one message to the local Agent Capsule
   tool            Run one registered tool directly
+  knowledge       Add, sync, inspect, and search local Knowledge sources
   db              Manage the local SQLite database
   eval            Run local eval files
   conversations   List and inspect stored local conversations
@@ -142,6 +149,7 @@ export function renderCommandHelp(command: string): string {
     "chat-ui": "agentkit chat-ui --deploy [--port <number>] [--token-file <path>]",
     chat: 'agentkit chat --message "hello" [--conversation-id <id>]',
     tool: "agentkit tool <name> [--input <path-or-json>]",
+    knowledge: "agentkit knowledge add <path-or-url> | sync | inspect | search <query> [--top-k <number>]",
     deploy:
       'agentkit deploy [--smoke "hello"] | agentkit deploy smoke [--message "hello"] | agentkit deploy doctor | status | pause | resume',
     secret:

package/src/cli/index.ts

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve } from "node:path";
 
@@ -61,6 +62,7 @@ import {
 import { renderCommandHelp, renderCommandReference, renderHelp } from "./help";
 import { runInheritedCommand, waitForShutdown } from "./process";
 import { handleChannelsCommand } from "./commands/channels";
+import { handleKnowledgeCommand } from "./commands/knowledge";
 
 async function main() {
   const args = parseArgs(process.argv.slice(2));
@@ -118,6 +120,7 @@ async function main() {
       console.log("  npm install");
     }
     console.log("  open this folder in Codex or Claude Code");
+    console.log("  coding agents start at skills/agentkit-capsule/SKILL.md");
     console.log('  ask: "Develop an appointment and intake agent for an ophthalmology office"');
     console.log('  npm run chat -- --message "hello"');
     console.log("  npm run dev");
@@ -340,6 +343,11 @@ async function main() {
     throw new Error("Usage: agentkit conversations list | agentkit conversations show <conversation-id>");
   }
 
+  if (args.command === "knowledge") {
+    await handleKnowledgeCommand(args);
+    return;
+  }
+
   if (args.command === "inspect") {
     const state = await inspectAgentCapsule(process.cwd());
     console.log(JSON.stringify(state, null, 2));
@@ -718,15 +726,17 @@ async function main() {
 
     const root = await findAgentCapsuleRoot(process.cwd());
     const docs = findAgentKitDocs();
-    console.log(renderHandoffPrompt({ target, root, docsFull: docs.llmsFull, goal: goalParts.join(" ").trim() }));
+    console.log(renderHandoffPrompt({ target, root, docsLlms: docs.llms, goal: goalParts.join(" ").trim() }));
     return;
   }
 
   throw new Error(`Unknown command: ${args.command}`);
 }
 
-function renderHandoffPrompt(input: { target: string; root: string; docsFull: string; goal: string }): string {
+function renderHandoffPrompt(input: { target: string; root: string; docsLlms: string; goal: string }): string {
   const agentName = input.target === "claude" ? "Claude Code" : "Codex";
+  const skillRouter = join(input.root, "skills/agentkit-capsule/SKILL.md");
+  const skillLine = existsSync(skillRouter) ? `- ${skillRouter}\n` : "";
   const goal = input.goal
     ? `Owner request:
 ${input.goal}`
@@ -740,12 +750,14 @@ ${input.root}
 Read these files first:
 
 - ${join(input.root, "AGENTKIT.md")}
-- ${input.docsFull}
+${skillLine}- ${input.docsLlms}
 
 ${goal}
 
 Rules:
-- Follow the AgentKit contract in llms-full.txt.
+- Start with the AgentKit capsule skill when it exists.
+- Use llms.txt as the docs router.
+- Read llms-full.txt only when a skill or ambiguous framework behavior requires the complete contract.
 - Treat the owner's request as the brief.
 - Build or update the agent inside this capsule as far as you can without asking for obvious restatements.
 - Do not wait for a wizard or recipe; implement directly in the capsule files.

package/src/cloud/artifact.ts

@@ -1,10 +1,15 @@
 import { createHash } from "node:crypto";
-import { readFile } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
+import { extname, isAbsolute, relative, resolve } from "node:path";
 
 import type { AgentBuildResult, AgentManifestWithBundle } from "../runtime/targets/cloudflare/build";
 import { AgentKitError } from "../runtime/errors";
 import type { HostedDeployArtifact } from "./contracts";
 
+const HOSTED_KNOWLEDGE_MAX_SOURCE_BYTES = 5 * 1024 * 1024;
+const HOSTED_KNOWLEDGE_MAX_TOTAL_BYTES = 9 * 1024 * 1024;
+const HOSTED_KNOWLEDGE_SUPPORTED_EXTENSIONS = new Set([".md", ".markdown", ".txt", ".csv"]);
+
 export async function createHostedDeployArtifact(build: AgentBuildResult): Promise<HostedDeployArtifact> {
   const [manifestSource, workerSource, wranglerSource] = await Promise.all([
     readFile(build.manifestPath, "utf8"),
@@ -40,9 +45,95 @@ export async function createHostedDeployArtifact(build: AgentBuildResult): Promi
     };
   }
 
+  if (manifest.knowledge.enabled) {
+    artifact.knowledge_sources = await createHostedKnowledgeSources(build.root, manifest);
+  }
+
   return artifact;
 }
 
+async function createHostedKnowledgeSources(
+  root: string,
+  manifest: AgentManifestWithBundle,
+): Promise<NonNullable<HostedDeployArtifact["knowledge_sources"]>> {
+  const sources: NonNullable<HostedDeployArtifact["knowledge_sources"]>["sources"] = [];
+  let totalBytes = 0;
+
+  for (const source of manifest.knowledge.sources) {
+    if (source.kind === "url") {
+      throw new AgentKitError(
+        "artifact_knowledge_source_unsupported",
+        "Hosted deploy can automatically sync local Knowledge files only. URL Knowledge sources require a hosted ingestion connector.",
+      );
+    }
+
+    const absolutePath = resolve(root, source.value);
+    const sourceKey = capsuleRelativePath(root, absolutePath);
+    const extension = extname(sourceKey).toLowerCase();
+
+    if (!HOSTED_KNOWLEDGE_SUPPORTED_EXTENSIONS.has(extension)) {
+      throw new AgentKitError(
+        "artifact_knowledge_source_unsupported",
+        `Knowledge source "${sourceKey}" is not supported for hosted deploy. Use .md, .txt, or .csv.`,
+      );
+    }
+
+    const stats = await stat(absolutePath).catch((error) => {
+      throw new AgentKitError("artifact_knowledge_source_missing", `Knowledge source "${sourceKey}" was not found.`, {
+        cause: error,
+      });
+    });
+
+    if (!stats.isFile()) {
+      throw new AgentKitError("artifact_knowledge_source_invalid", `Knowledge source "${sourceKey}" must be a file.`);
+    }
+
+    if (stats.size > HOSTED_KNOWLEDGE_MAX_SOURCE_BYTES) {
+      throw new AgentKitError(
+        "artifact_knowledge_source_too_large",
+        `Knowledge source "${sourceKey}" is too large for automatic deploy sync. Keep each source under 5MB.`,
+      );
+    }
+
+    totalBytes += stats.size;
+
+    if (totalBytes > HOSTED_KNOWLEDGE_MAX_TOTAL_BYTES) {
+      throw new AgentKitError(
+        "artifact_knowledge_sources_too_large",
+        "Knowledge sources are too large for automatic deploy sync. Keep total packaged Knowledge under 9MB.",
+      );
+    }
+
+    const content = await readFile(absolutePath, "utf8");
+    sources.push({
+      kind: "file",
+      source_key: sourceKey,
+      title: source.title,
+      content,
+      sha256: sha256(content),
+    });
+  }
+
+  return {
+    content_type: "application/json",
+    sources,
+    sha256: sha256(JSON.stringify(sources)),
+  };
+}
+
+function capsuleRelativePath(root: string, absolutePath: string): string {
+  const relativePath = relative(root, absolutePath);
+
+  if (!relativePath || relativePath.startsWith("..") || isAbsolute(relativePath)) {
+    throw new AgentKitError(
+      "artifact_knowledge_source_outside_capsule",
+      "Knowledge source paths must stay inside the Agent Capsule.",
+    );
+  }
+
+  return relativePath.split("\\").join("/");
+}
+
 function sha256(source: string): string {
   return createHash("sha256").update(source).digest("hex");
 }