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

package/src/runtime/targets/cloudflare/build.ts

@@ -8,6 +8,8 @@ import { build as esbuild, type Plugin } from "esbuild";
 import { loadAgentCapsule, type LoadedAgentCapsule } from "../../config";
 import { buildSharedAgentManifest, type ManifestSchema, type SharedAgentManifest } from "../../core/manifest";
 import { AgentKitError } from "../../errors";
+import { resolveKnowledgeConfig } from "../../knowledge/config";
+import { KNOWLEDGE_SCHEMA_SQL } from "../../knowledge/schema";
 
 export type BuildTarget = "cloudflare";
 
@@ -34,6 +36,7 @@ export type AgentManifest = {
   secrets: SharedAgentManifest["secrets"];
   tools: SharedAgentManifest["tools"];
   channels: SharedAgentManifest["channels"];
+  knowledge: SharedAgentManifest["knowledge"];
   access: SharedAgentManifest["access"];
   storage: {
     driver: "agentkit";
@@ -145,6 +148,14 @@ function validateCloudflareBuild(capsule: LoadedAgentCapsule): void {
     );
   }
 
+  const knowledge = resolveKnowledgeConfig(capsule.config);
+
+  if (knowledge.enabled && capsule.config.storage.database?.driver !== "turso") {
+    throw new AgentKitError(
+      "build_knowledge_database",
+      'Cloudflare Knowledge deploy requires storage.database.driver: "turso" so chunks and retrieval state are available to the hosted runtime.',
+    );
+  }
 }
 
 function buildWarnings(capsule: LoadedAgentCapsule): string[] {
@@ -185,6 +196,7 @@ function buildManifest(
     secrets: shared.secrets,
     tools: shared.tools,
     channels: shared.channels,
+    knowledge: shared.knowledge,
     access: shared.access,
     storage: {
       driver: "agentkit",
@@ -210,12 +222,26 @@ function buildCloudflareFilesManifest(files: SharedAgentManifest["storage"]["fil
 
 async function loadTursoSchema(capsule: LoadedAgentCapsule): Promise<ManifestSchema | null> {
   const database = capsule.config.storage.database;
+  const knowledge = resolveKnowledgeConfig(capsule.config);
+  const sources: string[] = [];
+
+  if (!database || database.driver !== "turso") {
+    return null;
+  }
+
+  if (database.schema) {
+    sources.push(await readFile(resolve(capsule.root, database.schema), "utf8"));
+  }
+
+  if (knowledge.enabled) {
+    sources.push(KNOWLEDGE_SCHEMA_SQL);
+  }
 
-  if (!database || database.driver !== "turso" || !database.schema) {
+  if (sources.length === 0) {
     return null;
   }
 
-  const source = await readFile(resolve(capsule.root, database.schema), "utf8");
+  const source = sources.map((part) => part.trim()).filter(Boolean).join("\n\n") + "\n";
   const digest = sha256(source);
   return { source, sha256: digest };
 }
@@ -361,6 +387,7 @@ export function websiteChannel(input) {
     access: input.access ?? { mode: "token" },
     secrets: normalizeChannelSecrets(input.secrets ?? ["AGENTKIT_WEBSITE_CHANNEL_TOKEN"], "website channel"),
     ...(input.limits ? { limits: input.limits } : {}),
+    ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, "website channel") } : {}),
   };
 }
 
@@ -372,6 +399,7 @@ export function telegramChannel(input) {
     secrets: normalizeChannelSecrets(input.secrets ?? ["TELEGRAM_BOT_TOKEN", "TELEGRAM_WEBHOOK_SECRET"], "telegram channel"),
     allowedUpdates: input.allowedUpdates ?? ["message"],
     ...(input.limits ? { limits: input.limits } : {}),
+    ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, "telegram channel") } : {}),
   };
 }
 
@@ -382,6 +410,7 @@ export function whatsappChannel(input) {
     name: input.name,
     secrets: normalizeChannelSecrets(input.secrets ?? defaultWhatsappChannelSecrets(input.provider), \`\${input.provider} whatsapp channel\`),
     ...(input.limits ? { limits: input.limits } : {}),
+    ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, \`\${input.provider} whatsapp channel\`) } : {}),
   };
 }
 
@@ -406,6 +435,36 @@ function normalizeChannelSecrets(secrets, context) {
 
   return Array.from(uniqueSecrets).sort();
 }
+
+function normalizeChannelBuffer(input, context) {
+  if (input.mode === "off") {
+    return { mode: "off" };
+  }
+
+  if (input.mode !== undefined && input.mode !== "debounce") {
+    throw new Error(\`\${context} buffer.mode must be "off" or "debounce".\`);
+  }
+
+  const buffer = {
+    mode: "debounce",
+    quietWindowMs: input.quietWindowMs ?? 2500,
+    maxWaitMs: input.maxWaitMs ?? 12000,
+    maxMessages: input.maxMessages ?? 20,
+    maxChars: input.maxChars ?? 8000,
+  };
+
+  for (const field of ["quietWindowMs", "maxWaitMs", "maxMessages", "maxChars"]) {
+    if (!Number.isInteger(buffer[field]) || buffer[field] <= 0) {
+      throw new Error(\`\${context} buffer.\${field} must be a positive integer.\`);
+    }
+  }
+
+  if (buffer.maxWaitMs < buffer.quietWindowMs) {
+    throw new Error(\`\${context} buffer.maxWaitMs must be greater than or equal to buffer.quietWindowMs.\`);
+  }
+
+  return buffer;
+}
 `;
 }
 
@@ -486,7 +545,8 @@ import { getProviderAdapter } from ${providerImportPath};
 
 const manifest = ${manifestJson};
 const instructions = ${instructionsJson};
-const hostedTools = agentConfig.tools ?? [];
+const hostedKnowledgeTool = manifest.knowledge.enabled ? createHostedKnowledgeSearchTool() : null;
+const hostedTools = hostedKnowledgeTool ? [hostedKnowledgeTool, ...(agentConfig.tools ?? [])] : (agentConfig.tools ?? []);
 const DEFAULT_TOOL_TIMEOUT_MS = 30000;
 
 export class AgentKitConversationStore extends DurableObject {
@@ -668,6 +728,7 @@ export default {
           provider: channel.provider,
           secrets: channel.secrets,
         })),
+        knowledge: manifest.knowledge,
         access: manifest.access,
         storage: manifest.storage,
         database: inspectHostedDatabase(),
@@ -1022,7 +1083,7 @@ async function callHostedProvider(env, messages, signal) {
       runtime: manifest.runtime,
       provider: manifest.provider,
     },
-    instructions: withToolVisibilityInstructions(instructions, hostedTools),
+    instructions: withToolVisibilityInstructions(appendHostedKnowledgePromptPolicy(instructions), hostedTools),
     messages,
     tools: hostedTools,
     toolRuntime: createHostedProviderToolRuntime(env, signal),
@@ -1033,6 +1094,20 @@ async function callHostedProvider(env, messages, signal) {
   return result.message.content;
 }
 
+function appendHostedKnowledgePromptPolicy(baseInstructions) {
+  if (!manifest.knowledge.enabled) {
+    return baseInstructions;
+  }
+
+  return \`\${baseInstructions.trimEnd()}
+
+Knowledge rules:
+- Use agentkit_search_knowledge before answering business-specific factual questions about the user's documents, policies, prices, availability, services, procedures, or source-specific claims.
+- Do not invent prices, policies, legal/clinical claims, availability, or source-specific facts when Knowledge has not returned support for the answer.
+- Use retrieved Knowledge as context for the final answer, but do not expose raw retrieval JSON, scores, chunk IDs, or internal tool output objects to the user.
+\`;
+}
+
 function withToolVisibilityInstructions(baseInstructions, tools) {
   const internalTools = tools
     .filter((tool) => tool.visibility === "internal")
@@ -1052,6 +1127,396 @@ Tool visibility rules:
 \`;
 }
 
+function createHostedKnowledgeSearchTool() {
+  return {
+    name: manifest.knowledge.internalTool || "agentkit_search_knowledge",
+    description: "Search the Agent Capsule's configured Knowledge sources for business-specific facts.",
+    visibility: "internal",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string" },
+        topK: { type: "integer" },
+      },
+      required: ["query"],
+      additionalProperties: false,
+    },
+    outputSchema: {
+      type: "object",
+      properties: {
+        results: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              content: { type: "string" },
+              score: { type: "number" },
+              source: { type: "object" },
+            },
+            required: ["content", "score", "source"],
+          },
+        },
+      },
+      required: ["results"],
+      additionalProperties: false,
+    },
+    secrets: manifest.knowledge.embedding.secret ? [manifest.knowledge.embedding.secret] : [],
+    async execute(input, ctx) {
+      const query = typeof input?.query === "string" ? input.query : "";
+      const topK = normalizeKnowledgeTopK(input?.topK ?? manifest.knowledge.retrieval.topK);
+      const results = await searchHostedKnowledge(ctx.database, query, topK, ctx.secrets ?? {});
+
+      return {
+        results: results.map((result) => ({
+          content: result.content,
+          score: result.score,
+          source: result.source,
+        })),
+      };
+    },
+  };
+}
+
+async function searchHostedKnowledge(database, query, topK, secrets) {
+  const normalizedQuery = String(query || "").trim();
+
+  if (!normalizedQuery) {
+    throw agentKitError("knowledge_query_invalid", "Knowledge search query must be a non-empty string.");
+  }
+
+  const hasEmbeddingProvider = manifest.knowledge.embedding.provider !== "none";
+  const lexical =
+    manifest.knowledge.retrieval.hybrid || !hasEmbeddingProvider
+      ? await searchHostedKnowledgeLexical(database, normalizedQuery, Math.max(topK * 4, topK))
+      : [];
+  const semantic = hasEmbeddingProvider
+    ? await searchHostedKnowledgeSemantic(database, normalizedQuery, topK * 4, secrets)
+    : [];
+
+  return combineHostedKnowledgeResults(lexical, semantic, topK);
+}
+
+async function searchHostedKnowledgeLexical(database, query, limit) {
+  const tokens = hostedKnowledgeQueryTokens(query);
+
+  if (tokens.length === 0) {
+    return [];
+  }
+
+  try {
+    const result = await database.query(
+      \`
+      SELECT
+        c.id AS chunk_id,
+        c.source_id AS source_id,
+        c.content AS content,
+        c.title AS title,
+        c.section AS section,
+        c.locator AS locator,
+        s.source_key AS source_key,
+        rank
+      FROM agentkit_knowledge_fts
+      JOIN agentkit_knowledge_chunks c ON c.id = agentkit_knowledge_fts.chunk_id
+      JOIN agentkit_knowledge_sources s ON s.id = c.source_id
+      WHERE agentkit_knowledge_fts MATCH ?
+      ORDER BY rank ASC
+      LIMIT ?
+    \`,
+      [tokens.map((token) => \`"\${token.replace(/"/g, '""')}"\`).join(" OR "), limit],
+    );
+
+    return result.rows.map((row, index) => hostedKnowledgeResultFromRow(row, hostedLexicalScore(index), null));
+  } catch {
+    return searchHostedKnowledgeLexicalFallback(database, query, limit);
+  }
+}
+
+async function searchHostedKnowledgeLexicalFallback(database, query, limit) {
+  const like = \`%\${query.toLowerCase()}%\`;
+  const result = await database.query(
+    \`
+    SELECT
+      c.id AS chunk_id,
+      c.source_id AS source_id,
+      c.content AS content,
+      c.title AS title,
+      c.section AS section,
+      c.locator AS locator,
+      s.source_key AS source_key
+    FROM agentkit_knowledge_chunks c
+    JOIN agentkit_knowledge_sources s ON s.id = c.source_id
+    WHERE lower(c.content) LIKE ?
+      OR lower(COALESCE(c.title, '')) LIKE ?
+      OR lower(COALESCE(c.section, '')) LIKE ?
+    ORDER BY c.created_at DESC, c.ordinal ASC
+    LIMIT ?
+  \`,
+    [like, like, like, limit],
+  );
+
+  return result.rows.map((row, index) => hostedKnowledgeResultFromRow(row, hostedLexicalScore(index), null));
+}
+
+async function searchHostedKnowledgeSemantic(database, query, limit, secrets) {
+  const queryEmbedding = await createHostedKnowledgeEmbedding(query, secrets);
+
+  if (!queryEmbedding) {
+    return [];
+  }
+
+  try {
+    return await searchHostedKnowledgeNativeVector(database, queryEmbedding, limit);
+  } catch {
+    return searchHostedKnowledgeSemanticFallback(database, queryEmbedding, limit);
+  }
+}
+
+async function searchHostedKnowledgeNativeVector(database, queryEmbedding, limit) {
+  const vector = JSON.stringify(queryEmbedding);
+  const result = await database.query(
+    \`
+    SELECT
+      c.id AS chunk_id,
+      c.source_id AS source_id,
+      c.content AS content,
+      c.title AS title,
+      c.section AS section,
+      c.locator AS locator,
+      s.source_key AS source_key,
+      vector_distance_cos(v.embedding, vector32(?)) AS vector_distance
+    FROM vector_top_k('agentkit_knowledge_vectors_embedding_idx', vector32(?), ?) nearest
+    JOIN agentkit_knowledge_vectors v ON v.id = nearest.id
+    JOIN agentkit_knowledge_chunks c ON c.id = v.chunk_id
+    JOIN agentkit_knowledge_sources s ON s.id = c.source_id
+    ORDER BY vector_distance ASC
+  \`,
+    [vector, vector, limit],
+  );
+
+  return result.rows
+    .map((row) => {
+      const distance = Number(row.vector_distance);
+      const semantic = Number.isFinite(distance) ? 1 - distance : 0;
+      return hostedKnowledgeResultFromRow(row, 0, semantic);
+    })
+    .filter((result) => result.match.semantic !== null && result.match.semantic > 0)
+    .slice(0, limit);
+}
+
+async function searchHostedKnowledgeSemanticFallback(database, queryEmbedding, limit) {
+  const result = await database.query(
+    \`
+    SELECT
+      c.id AS chunk_id,
+      c.source_id AS source_id,
+      c.content AS content,
+      c.title AS title,
+      c.section AS section,
+      c.locator AS locator,
+      c.embedding_json AS embedding_json,
+      s.source_key AS source_key
+    FROM agentkit_knowledge_chunks c
+    JOIN agentkit_knowledge_sources s ON s.id = c.source_id
+    WHERE c.embedding_json IS NOT NULL
+    ORDER BY c.created_at DESC, c.ordinal ASC
+  \`,
+  );
+
+  return result.rows
+    .map((row) => {
+      const embedding = parseHostedKnowledgeEmbedding(row.embedding_json);
+      const semantic = embedding ? hostedCosineSimilarity(queryEmbedding, embedding) : 0;
+      return hostedKnowledgeResultFromRow(row, 0, semantic);
+    })
+    .filter((result) => result.match.semantic !== null && result.match.semantic > 0)
+    .sort((left, right) => (right.match.semantic ?? 0) - (left.match.semantic ?? 0))
+    .slice(0, limit);
+}
+
+async function createHostedKnowledgeEmbedding(input, secrets) {
+  const provider = manifest.knowledge.embedding.provider;
+
+  if (provider === "none") {
+    return null;
+  }
+
+  if (provider === "test") {
+    return hostedFakeEmbedding(input, manifest.knowledge.embedding.dimensions || 32);
+  }
+
+  if (provider !== "openai") {
+    throw agentKitError("knowledge_embedding_provider_unsupported", "Unsupported knowledge embedding provider.");
+  }
+
+  const secretName = manifest.knowledge.embedding.secret || "OPENAI_API_KEY";
+  const apiKey = secrets[secretName];
+
+  if (!apiKey) {
+    throw agentKitError("knowledge_embedding_secret_missing", \`Knowledge embeddings require missing secret "\${secretName}".\`);
+  }
+
+  const response = await fetch("https://api.openai.com/v1/embeddings", {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: \`Bearer \${apiKey}\`,
+    },
+    body: JSON.stringify({
+      model: manifest.knowledge.embedding.model || "text-embedding-3-small",
+      input,
+      encoding_format: "float",
+      ...(manifest.knowledge.embedding.dimensions ? { dimensions: manifest.knowledge.embedding.dimensions } : {}),
+    }),
+  });
+
+  if (!response.ok) {
+    const text = await response.text().catch(() => "");
+    throw agentKitError(
+      "knowledge_embedding_failed",
+      \`OpenAI embedding request failed with HTTP \${response.status}.\${text ? " " + text.slice(0, 240) : ""}\`,
+    );
+  }
+
+  const payload = await response.json();
+  const embedding = payload?.data?.[0]?.embedding;
+
+  if (!Array.isArray(embedding) || embedding.some((value) => typeof value !== "number")) {
+    throw agentKitError("knowledge_embedding_failed", "OpenAI embedding response did not contain a numeric vector.");
+  }
+
+  return embedding;
+}
+
+function combineHostedKnowledgeResults(lexical, semantic, topK) {
+  const byChunk = new Map();
+
+  for (const result of lexical) {
+    byChunk.set(result.chunkId, result);
+  }
+
+  for (const result of semantic) {
+    const existing = byChunk.get(result.chunkId);
+
+    if (!existing) {
+      byChunk.set(result.chunkId, {
+        ...result,
+        score: hostedCombinedScore(0, result.match.semantic),
+      });
+      continue;
+    }
+
+    byChunk.set(result.chunkId, {
+      ...existing,
+      score: hostedCombinedScore(existing.match.lexical, result.match.semantic),
+      match: {
+        lexical: existing.match.lexical,
+        semantic: result.match.semantic,
+      },
+    });
+  }
+
+  return Array.from(byChunk.values())
+    .map((result) => ({
+      ...result,
+      score: result.score || hostedCombinedScore(result.match.lexical, result.match.semantic),
+    }))
+    .sort((left, right) => right.score - left.score || left.source.path.localeCompare(right.source.path))
+    .slice(0, topK);
+}
+
+function hostedKnowledgeResultFromRow(row, lexical, semantic) {
+  return {
+    chunkId: String(row.chunk_id),
+    content: String(row.content),
+    score: hostedCombinedScore(lexical, semantic),
+    source: {
+      id: String(row.source_id),
+      path: String(row.source_key),
+      title: typeof row.title === "string" ? row.title : null,
+      section: typeof row.section === "string" ? row.section : null,
+      locator: typeof row.locator === "string" ? row.locator : null,
+    },
+    match: {
+      lexical,
+      semantic,
+    },
+  };
+}
+
+function normalizeKnowledgeTopK(value) {
+  const topK = Number(value);
+
+  if (!Number.isInteger(topK) || topK <= 0 || topK > 50) {
+    throw agentKitError("knowledge_query_invalid", "Knowledge search topK must be a positive integer no larger than 50.");
+  }
+
+  return topK;
+}
+
+function hostedKnowledgeQueryTokens(query) {
+  return Array.from(new Set(String(query).toLowerCase().match(/[\\p{L}\\p{N}_-]+/gu) ?? [])).slice(0, 12);
+}
+
+function parseHostedKnowledgeEmbedding(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed) && parsed.every((item) => typeof item === "number") ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function hostedCombinedScore(lexical, semantic) {
+  const semanticScore = semantic === null ? 0 : Math.max(0, (semantic + 1) / 2);
+  return Number((lexical * 0.6 + semanticScore * 0.4).toFixed(6));
+}
+
+function hostedLexicalScore(index) {
+  return Number((1 / (index + 1)).toFixed(6));
+}
+
+function hostedCosineSimilarity(left, right) {
+  if (left.length !== right.length || left.length === 0) {
+    return 0;
+  }
+
+  let dot = 0;
+  let leftNorm = 0;
+  let rightNorm = 0;
+
+  for (let index = 0; index < left.length; index += 1) {
+    dot += left[index] * right[index];
+    leftNorm += left[index] * left[index];
+    rightNorm += right[index] * right[index];
+  }
+
+  if (leftNorm === 0 || rightNorm === 0) {
+    return 0;
+  }
+
+  return dot / (Math.sqrt(leftNorm) * Math.sqrt(rightNorm));
+}
+
+async function hostedFakeEmbedding(input, dimensions) {
+  const values = Array.from({ length: dimensions }, () => 0);
+  const tokens = String(input).toLowerCase().match(/[\\p{L}\\p{N}_-]+/gu) ?? [];
+  const encoder = new TextEncoder();
+
+  for (const token of tokens) {
+    const hash = new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(token)));
+    const slot = hash[0] % dimensions;
+    const sign = hash[1] % 2 === 0 ? 1 : -1;
+    values[slot] += sign * (1 + (hash[2] % 7) / 10);
+  }
+
+  const norm = Math.sqrt(values.reduce((sum, value) => sum + value * value, 0));
+  return norm === 0 ? values : values.map((value) => Number((value / norm).toFixed(8)));
+}
+
 async function persistFailure(env, conversationId, userMessage, error) {
   await persist(env, {
     conversationId,

package/src/storage/sqlite.ts

@@ -6,6 +6,7 @@ import type { DatabaseArgs, DatabaseResult, DatabaseRow, DatabaseStatement } fro
 import type { AgentMessageRole, ProviderRunResult } from "../providers";
 import type { LoadedAgentCapsule } from "../runtime/config";
 import { AgentKitError } from "../runtime/errors";
+import { KNOWLEDGE_MIGRATION_ID, KNOWLEDGE_SCHEMA_SQL } from "../runtime/knowledge/schema";
 
 export type ConversationSummary = {
   id: string;
@@ -153,6 +154,10 @@ const MIGRATIONS = [
         ADD COLUMN visibility TEXT NOT NULL DEFAULT 'user';
     `,
   },
+  {
+    id: KNOWLEDGE_MIGRATION_ID,
+    sql: KNOWLEDGE_SCHEMA_SQL,
+  },
 ] as const;
 
 export async function openCapsuleStore(capsule: LoadedAgentCapsule): Promise<SqliteAgentKitStore> {

package/src/templates/blank.ts

@@ -147,7 +147,7 @@ When the owner opens this folder in Codex, Claude Code, or another coding agent
 
 Start building immediately:
 
-- Read \`AGENTKIT.md\` and the full docs path from \`npm run agentkit -- docs full\`.
+- Start with \`skills/agentkit-capsule/SKILL.md\`, then use \`npm run agentkit -- docs llms\` as the docs router.
 - Infer the first useful version from the owner's request.
 - Edit \`prompts/instructions.md\` for the agent behavior.
 - Edit \`agentkit.config.ts\` for provider, tools, secrets, access, and storage.
@@ -170,7 +170,8 @@ Start building immediately:
 - \`npm run agentkit -- inspect\`: print machine-readable capsule state.
 - \`printf %s "$VALUE" | npm run agentkit -- env set <NAME> --stdin\`: write a local secret value to ignored \`.env\` without putting it in shell history.
 - \`npm run agentkit -- env list\`: list local secret names without printing values.
-- \`npm run agentkit -- docs full\`: print the full AgentKit contract path.
+- \`npm run agentkit -- docs llms\`: print the lightweight AgentKit docs router.
+- \`npm run agentkit -- docs full\`: print the full AgentKit contract path only when a skill asks for it.
 
 ## Testing With A UI
 
@@ -305,12 +306,14 @@ If you add a tool, also run a fake-provider tool smoke test:
 npm run agentkit -- tool tool_name --input '{}'
 \`\`\`
 
-For the full framework contract, read the path printed by:
+For the lightweight docs router, read the path printed by:
 
 \`\`\`sh
-npm run agentkit -- docs full
+npm run agentkit -- docs llms
 \`\`\`
 
+Read the full framework contract with \`npm run agentkit -- docs full\` only when a skill asks for it.
+
 ## Hosted Deploy
 
 This capsule is hosted-deploy ready by default.
@@ -343,6 +346,7 @@ Use AgentKit conventions when editing this project.
 - Production secrets must be managed secrets, not committed files.
 - Keep required local secret names in \`.env.schema\` and values in ignored \`.env\`. AgentKit local commands load \`.env\` directly.
 - Treat the owner's natural-language request as the brief and start implementing inside this capsule.
+- Start with \`skills/agentkit-capsule/SKILL.md\` when the task is not obvious.
 `,
       },
       {

package/src/templates/dentista.ts

@@ -887,7 +887,8 @@ A Clara conversa com clientes, coleta nome, email e telefone, consulta disponibi
 - \`npm run eval\`: rodar evals.
 - \`npm run dev\`: rodar a runtime local.
 - \`npm run agentkit -- inspect\`: imprimir o estado da cápsula.
-- \`npm run agentkit -- docs full\`: imprimir o contrato completo do AgentKit.
+- \`npm run agentkit -- docs llms\`: imprimir o roteador leve da documentação AgentKit.
+- \`npm run agentkit -- docs full\`: imprimir o contrato completo do AgentKit somente quando uma skill pedir.
 
 ## Teste Com UI
 
@@ -903,6 +904,7 @@ A Clara conversa com clientes, coleta nome, email e telefone, consulta disponibi
 - Mantenha segredos em \`.env\`, nunca em arquivos versionados.
 - Não espere wizard ou recipe. AgentKit fornece o scaffold e o contrato; implemente diretamente conforme o brief do dono.
 - Para trocar para um provider real, o dono deve escolher OpenRouter, OpenAI, Anthropic ou outro provider suportado. Depois edite \`agentkit.config.ts\`, atualize \`.env.schema\` e configure secrets locais/hosted.
+- Quando a próxima ação não for óbvia, comece por \`skills/agentkit-capsule/SKILL.md\`.
 `,
       },
       {

package/src/templates/skills/agentkit-build-agent/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: agentkit-build-agent
+description: Use when the owner gives a natural-language brief for a new or changed AgentKit agent and expects the coding agent to turn it into a working local capsule with prompts, tools, schema, evals, and verification.
+---
+
+# Build An AgentKit Agent
+
+Use this when the owner asks for an agent in plain language.
+
+## Workflow
+
+1. Read `agentkit.config.ts`, `prompts/instructions.md`, `schema.sql`, `evals/`, and existing `tools/`.
+2. Infer the first useful local version from the owner's brief.
+3. Edit `prompts/instructions.md` for behavior, boundaries, intake questions, escalation rules, and tool-use policy.
+4. Add tools only when the agent needs action, live data, authorization-sensitive data, or durable writes.
+5. Add database tables to `schema.sql` when the agent owns records.
+6. Add or update evals for the main flow.
+7. Keep the capsule runnable on `test/fake` unless the owner has chosen a real provider.
+
+## Templates
+
+Use these only when they match the brief:
+
+- `templates/support-agent.instructions.md`
+- `templates/appointment-intake.instructions.md`
+- `templates/sales-qualifier.instructions.md`
+
+For prompt-only work, use `skills/agentkit-prompts/SKILL.md`.
+For database-backed tools, use `skills/agentkit-database/SKILL.md`.
+
+## Verification
+
+```sh
+npm run typecheck
+npm run agentkit -- inspect
+npm run chat -- --message "hello"
+npm run eval
+```
+
+If a tool was added:
+
+```sh
+npm run agentkit -- tool <tool_name> --input '<json>'
+```
+
+## Final Response
+
+Summarize the files changed, assumptions made, verification results, and whether the behavior was tested with `test/fake` or a real provider selected by the owner.
+