@andreprado/agentkit 0.1.0-alpha.9 → 0.1.1

package/src/templates/dentista.ts

@@ -64,6 +64,7 @@ node_modules/
 OPENAI_API_KEY=
 ANTHROPIC_API_KEY=
 OPENROUTER_API_KEY=
+OPENCODE_API_KEY=
 `,
       },
       {
@@ -83,6 +84,7 @@ export default defineAgent({
     name: "test",
     model: "fake",
   },
+  timeZone: "America/Sao_Paulo",
   instructions: "./prompts/instructions.md",
   secrets: [],
   tools: [listarHorariosDisponiveis, consultarConsulta, agendarConsulta, alterarConsulta],
@@ -282,7 +284,7 @@ export const listarHorariosDisponiveis = defineTool<ListarHorariosInput, { data:
   },
   async execute(input, ctx) {
     const date = normalizeDate(input.data);
-    const dateError = validateAppointmentDate(date);
+    const dateError = validateAppointmentDate(date, ctx.clock.now);
 
     if (dateError) {
       return {
@@ -409,6 +411,7 @@ export const agendarConsulta = defineTool<AgendarConsultaInput, AgendaOutput>({
       data,
       horario,
       confirmadoPeloCliente: input.confirmadoPeloCliente,
+      now: ctx.clock.now,
     });
 
     if (!validation.ok) {
@@ -482,6 +485,7 @@ export const alterarConsulta = defineTool<AlterarConsultaInput, AgendaOutput>({
       data,
       horario,
       confirmadoPeloCliente: input.confirmadoPeloCliente,
+      now: ctx.clock.now,
     });
 
     if (!contact.ok) {
@@ -575,9 +579,9 @@ export const alterarConsulta = defineTool<AlterarConsultaInput, AgendaOutput>({
 
 async function validateScheduleRequest(
   db: DatabaseRunner,
-  input: { data: string; horario: string; confirmadoPeloCliente: boolean },
+  input: { data: string; horario: string; confirmadoPeloCliente: boolean; now: Date },
 ): Promise<{ ok: boolean; mensagem: string; disponiveis: string[] }> {
-  const dateError = validateAppointmentDate(input.data);
+  const dateError = validateAppointmentDate(input.data, input.now);
 
   if (dateError) {
     return {
@@ -698,7 +702,7 @@ function normalizeTime(input: string): string {
   return \`\${match[1].padStart(2, "0")}:\${match[2]}\`;
 }
 
-function validateAppointmentDate(data: string): string | null {
+function validateAppointmentDate(data: string, now: Date): string | null {
   if (!/^\\d{4}-\\d{2}-\\d{2}$/.test(data)) {
     return "Use a data no formato YYYY-MM-DD.";
   }
@@ -710,20 +714,20 @@ function validateAppointmentDate(data: string): string | null {
     return "Esta data nao existe. Confirme a data com o cliente.";
   }
 
-  if (data < todayInClinicTimezone()) {
+  if (data < todayInClinicTimezone(now)) {
     return "Nao agende consultas em datas passadas.";
   }
 
   return null;
 }
 
-function todayInClinicTimezone(): string {
+function todayInClinicTimezone(now: Date): string {
   const parts = new Intl.DateTimeFormat("en-US", {
     timeZone: CLINIC_TIME_ZONE,
     year: "numeric",
     month: "2-digit",
     day: "2-digit",
-  }).formatToParts(new Date());
+  }).formatToParts(now);
   const byType = Object.fromEntries(parts.map((part) => [part.type, part.value]));
   return \`\${byType.year}-\${byType.month}-\${byType.day}\`;
 }
@@ -838,13 +842,18 @@ Quando o cliente quiser alterar a própria consulta:
       },
       {
         path: "evals/smoke.eval.ts",
-        contents: `export default {
+        contents: `import { defineEval } from "@andreprado/agentkit";
+
+export default defineEval({
   name: "smoke",
   input: "Oi, quero marcar uma consulta.",
   expect: {
-    contains: "nome",
+    response: {
+      containsAny: ["nome", "Nome"],
+      notRegex: ["API_KEY|secret|token"],
+    },
   },
-};
+});
 `,
       },
       {
@@ -857,7 +866,21 @@ Esta é uma AgentKit Agent Capsule para a Clara, atendente em português de um c
 
 A Clara conversa com clientes, coleta nome, email e telefone, consulta disponibilidade e agenda consultas em slots de 30 minutos. Ela também consulta e altera o próprio horário do cliente usando email e telefone como verificação mínima.
 
-Quando o dono pedir mudanças em linguagem natural, crie ou atualize \`AGENT_SPEC.md\` com \`npm run agentkit -- spec init --brief "<pedido do dono>"\`. O dono dá a ideia geral; o agente de código transforma isso no contrato estruturado.
+Quando o dono pedir mudanças em linguagem natural, trate a mensagem como o brief. O dono não deve precisar rodar wizard ou preparar arquivo de brief. Crie ou atualize \`AGENT_SPEC.md\` com \`npm run agentkit -- spec init --brief "<pedido do dono>"\`; o agente de código transforma a ideia geral no contrato estruturado.
+
+## Contrato Proativo De Produto Testável
+
+Não edite apenas o prompt. Para cada requisito relevante do pedido ou do \`AGENT_SPEC.md\`, decida qual artefato deve garantir o comportamento:
+
+- entrada no spec para o contrato de produto;
+- instrução no prompt para comportamento, tom, limites, coleta de dados e escalonamento;
+- ferramenta mais registro no config para ações, dados vivos, escritas externas ou dados sensíveis;
+- schema/migration mais ferramenta para dados duráveis;
+- eval para privacidade, confirmação, campos obrigatórios, horário comercial, datas, duração e regressões;
+- fixture, seed, branch fake ou teste direto de ferramenta para integrações e caminhos de erro;
+- checagem de deploy/readiness para secrets hosted, canais, integrações ou acesso de produção.
+
+Regras que protegem privacidade, agendamento, confirmação, dados de cliente, horário comercial ou segurança precisam de eval ou checagem determinística antes de dizer que a cápsula está pronta. Se uma conversa real revelar bug, transforme em uma eval de regressão pequena antes ou junto da correção.
 
 ## Regras de Produto
 
@@ -900,16 +923,19 @@ Quando o dono pedir mudanças em linguagem natural, crie ou atualize \`AGENT_SPE
 - UI local: rode \`npm run dev\`, abra a URL impressa em \`Chat:\` e informe essa URL exata ao dono.
 - UI pós-deploy: depois de \`npm run agentkit -- deploy\`, rode \`npm run agentkit -- chat-ui --deploy\`, abra a URL impressa em \`Chat:\` e informe que ela está conectada ao deploy hospedado.
 - \`test/fake\` é determinístico. Ele valida scaffold, ferramentas e evals previsíveis, mas não valida qualidade de conversa natural.
-- Antes de dizer que a conversa real foi testada, pergunte ao dono qual provider usar: OpenRouter, OpenAI, Anthropic ou outro provider suportado. Não escolha pelo dono.
+- Antes de dizer que a conversa real foi testada, pergunte ao dono qual provider usar: OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go ou outro provider suportado. Não escolha pelo dono.
 
 ## Regras de Implementação
 
 - Use \`ctx.db\` nas ferramentas. Não importe drivers SQLite, Turso ou Node-only APIs.
 - Mantenha \`schema.sql\` idempotente com \`CREATE TABLE IF NOT EXISTS\` e \`CREATE INDEX IF NOT EXISTS\`. Use \`migrations/*.sql\` ordenadas para evolução de schema com cara de produção.
+- Quando a mudança exigir persistência nova, implemente a fatia completa: schema/migration, ferramenta, registro no config, instruções no prompt, teste direto da ferramenta e eval.
 - Use \`npm run agentkit -- sync init\` quando a agente depender de catálogo externo, fixture local ou seed padronizado.
+- Para regras de privacidade, confirmação, campos obrigatórios, timezone, horário comercial, duração, erro de integração ou no-leak, adicione uma eval, fixture, branch fake ou teste direto de ferramenta.
+- Transforme conversas reais com falhas em regressão com \`npm run agentkit -- eval from-conversation <conversation-id>\`.
 - 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.
+- Para trocar para um provider real, o dono deve escolher OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go 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\`.
 `,
       },
@@ -987,7 +1013,7 @@ npm run agentkit -- chat-ui --deploy
 
 Abra a URL impressa em \`Chat:\` e informe que essa UI local está conectada ao deploy hospedado.
 
-Antes de dizer que a conversa real foi testada, pergunte ao dono qual provider usar: OpenRouter, OpenAI, Anthropic ou outro provider suportado. Não escolha pelo dono. Depois configure \`agentkit.config.ts\`, \`.env.schema\`, secrets locais e secrets hosted se for deployar.
+Antes de dizer que a conversa real foi testada, pergunte ao dono qual provider usar: OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go ou outro provider suportado. Não escolha pelo dono. Depois configure \`agentkit.config.ts\`, \`.env.schema\`, secrets locais e secrets hosted se for deployar.
 
 ## Deploy
 

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

@@ -7,17 +7,46 @@ description: Use when the owner gives a natural-language brief for a new or chan
 
 Use this when the owner asks for an agent in plain language.
 
+The owner should only need to run `agentkit new [name]` or `agentkit new .`, open the capsule in Codex or another coding agent, and say what agent they want. Do not send them back to the CLI for a brief wizard. Treat their chat message as the brief and build the first useful local capsule.
+
 ## Workflow
 
 1. Read `agentkit.config.ts`, `prompts/instructions.md`, `schema.sql`, `evals/`, and existing `tools/`.
 2. If `AGENT_SPEC.md` does not exist, create it from the owner's plain-language request with `npm run agentkit -- spec init --brief "<owner request>"`. If it exists, update it directly before changing behavior.
 3. Infer the first useful local version from the owner's brief and the spec. Do not ask the owner to fill a form.
 4. Edit `prompts/instructions.md` for behavior, boundaries, intake questions, escalation rules, and tool-use policy.
-5. Add tools only when the agent needs action, live data, authorization-sensitive data, or durable writes.
-6. Add database tables to `schema.sql` or ordered `migrations/*.sql` when the agent owns records.
-7. Add `sync.ts` and `seed.sql` with `npm run agentkit -- sync init` when the agent depends on external catalogs or recurring imports.
-8. Add or update evals for the main flow. Prefer multi-turn `turns` evals for real conversations.
-9. Keep the capsule runnable on `test/fake` unless the owner has chosen a real provider.
+5. For scheduling, deadlines, reminders, or any relative-date behavior, set `timeZone` in `agentkit.config.ts` to the business/user timezone. AgentKit injects the current date, weekday, timestamp, and timezone dynamically at runtime; do not hardcode today's date in prompts.
+6. Add tools when the agent needs action, live data, authorization-sensitive data, durable writes, or a requested external judgment such as TypeSafe/Jev. Use `skills/agentkit-tools/SKILL.md` for the tool workflow and Jev guidance.
+7. Add database tables to `schema.sql` or ordered `migrations/*.sql` when the agent owns records.
+8. Add `sync.ts` and `seed.sql` with `npm run agentkit -- sync init` when the agent depends on external catalogs or recurring imports.
+9. Turn requirements into checks as you build. Every privacy rule, external write, confirmation step, business-hour rule, timezone rule, required intake field, and customer-data boundary needs an eval, direct tool check, fixture, or deterministic fake path.
+10. Add or update evals for the main flow. Prefer multi-turn `turns` evals for real conversations.
+11. Keep the capsule runnable on `test/fake` unless the owner has chosen a real provider.
+
+## Requirement-To-Verification Loop
+
+For each item in the brief or `AGENT_SPEC.md`, classify it before finishing:
+
+- prompt-only behavior: add a prompt instruction and a response eval when the wording or boundary matters;
+- required intake such as name, phone, email, budget, or account id: add a multi-turn eval that proves the agent asks before acting;
+- tool call or external write: add a persisted tool-call eval and a direct `agentkit tool` check;
+- database record: implement the complete slice in the next section;
+- scheduling, deadlines, or timezone: set `timeZone`, freeze eval `now`, and assert the date/time sent to tools;
+- privacy/no-leak rule: add a no-leak eval with `notContains` or `notRegex`;
+- integration failure such as rate limit, timeout, unavailable slot, or missing auth: add a fixture, fake branch, or eval-safe tool behavior.
+
+If a requirement is important enough to mention in the spec, it is usually important enough to test. State any untested requirement in the final response.
+
+## Complete Slice
+
+When the brief implies durable records such as leads, clients, bookings, tickets, or notes, do the whole local slice:
+
+- add or update `schema.sql` and ordered `migrations/*.sql` when appropriate;
+- add the `defineTool` implementation under `tools/`;
+- register the tool in `agentkit.config.ts`;
+- teach `prompts/instructions.md` when and how to use the tool;
+- add a direct tool check fixture or command;
+- add an eval that proves the agent calls the tool in the expected flow.
 
 ## Templates
 

package/src/templates/skills/agentkit-build-agent/templates/appointment-intake.instructions.md

@@ -13,8 +13,9 @@ Required intake:
 - Any urgency or special constraints
 
 Rules:
+- Interpret today, tomorrow, weekdays, and vague time windows using the AgentKit runtime date context.
+- If the user's scheduling timezone may differ from the business timezone, confirm the timezone before booking.
 - Do not diagnose, promise outcomes, or provide emergency guidance beyond directing urgent cases to appropriate human or emergency support.
 - Do not create, change, or cancel an appointment without explicit user confirmation.
 - Do not invent availability.
 - Use the scheduling tools for availability and writes.
-

package/src/templates/skills/agentkit-capsule/SKILL.md

@@ -7,6 +7,27 @@ description: Use when working inside an AgentKit Agent Capsule, especially after
 
 Use this first inside an AgentKit Agent Capsule.
 
+## Owner-To-Codex Contract
+
+The owner has already done the setup work by running `agentkit new [name]` or `agentkit new .` and opening this folder in a coding agent. When they ask for an agent in natural language, that message is the brief.
+
+- Do not ask the owner to run a wizard, fill a form, or prepare `AGENT_SPEC.md`.
+- Route immediately to `skills/agentkit-build-agent/SKILL.md`.
+- You create or update `AGENT_SPEC.md`, prompts, tools, schema, evals, and docs as needed.
+- Use the CLI for validation and deployment, not for business inference.
+
+## Proactive Builder Contract
+
+Do not stop at "the prompt was edited." For every meaningful requirement in the owner's brief or `AGENT_SPEC.md`, decide which artifact must enforce it:
+
+- behavior or tone: `prompts/instructions.md`;
+- action, live data, or external write: `tools/` plus `agentkit.config.ts`;
+- durable records: schema/migration, tool, config registration, prompt guidance, direct tool check, and eval;
+- privacy, confirmation, business hours, dates, money, safety, or client data: at least one eval or deterministic check;
+- production or integration dependency: deploy/readiness check and safe fixture or fake path.
+
+If a real conversation reveals a bug or risky behavior, convert it into a regression eval before or alongside the fix.
+
 ## Start
 
 1. Treat the directory containing `agentkit.config.ts` as the capsule root.
@@ -18,14 +39,16 @@ Use this first inside an AgentKit Agent Capsule.
 
 - Build or reshape the agent from the owner's brief: `skills/agentkit-build-agent/SKILL.md`
 - Edit prompts: `skills/agentkit-prompts/SKILL.md`
-- Add actions or external data: `skills/agentkit-tools/SKILL.md`
+- Add actions, external data, or TypeSafe/Jev judgments: `skills/agentkit-tools/SKILL.md`
+- Add AgentKit-managed integrations such as managed Composio: `skills/agentkit-integrations/SKILL.md`
 - Add database tables or database-backed tools: `skills/agentkit-database/SKILL.md`
 - Add docs, FAQs, prices, policies, or CSV facts: `skills/agentkit-knowledge/SKILL.md`
 - Switch from `test/fake` to a real model provider: `skills/agentkit-provider/SKILL.md`
 - Add or run evals: `skills/agentkit-evals/SKILL.md`
+- Improve from hosted or local production evidence: `skills/agentkit-improve/SKILL.md`
 - Prepare hosted deploy: `skills/agentkit-deploy/SKILL.md`
 - Work with secrets, external APIs, public access, channels, or real data: `skills/agentkit-security/SKILL.md`
-- Add or debug website, Telegram, or WhatsApp channels: `skills/agentkit-channels/SKILL.md`
+- Add or debug website, Telegram, WhatsApp, Discord, Slack, or generic webhook channels: `skills/agentkit-channels/SKILL.md`
 - Investigate command failures: `skills/agentkit-troubleshooting/SKILL.md`
 
 For a compact docs map, read `references/docs-router.md`.
@@ -52,11 +75,17 @@ If you change behavior, add or update an eval and run:
 npm run eval
 ```
 
+If the change fixes production behavior, also collect or use an improve bundle and run:
+
+```sh
+npm run agentkit -- replay .agentkit/improve/<run> --against local
+```
+
 ## Rules
 
 - Keep `.env`, `.agentkit/`, and `node_modules/` out of commits.
 - Keep secret names in `.env.schema`; keep secret values in ignored `.env` or hosted managed secrets.
 - Keep the first useful version runnable with `test/fake` unless the owner explicitly chooses a real provider.
+- For scheduling or relative-date agents, set `timeZone` in `agentkit.config.ts`; AgentKit injects the current date, weekday, timestamp, and timezone dynamically at runtime.
 - Ask follow-up questions only when missing information blocks a safe local implementation.
 - Tell the owner when testing used `test/fake` instead of a real provider.
-

package/src/templates/skills/agentkit-capsule/references/docs-router.md

@@ -6,10 +6,10 @@ Prefer the narrowest source that covers the task.
 - Tools, schemas, secrets, and direct tool tests: `docs/guides/add-tool.md`
 - Knowledge sources, indexing, search, and hosted sync: `docs/guides/add-knowledge.md`
 - Evals and deterministic side-effect guards: `docs/guides/run-evals.md`
+- Safe AgentKit product feedback drafts/submission: `docs/guides/send-feedback.md`
 - Real provider setup: `docs/guides/use-provider.md`
 - Deploy readiness, managed secrets, smoke checks, hosted UI: `docs/guides/prepare-deploy.md`
-- Channels: `docs/guides/add-channel.md`, `connect-telegram.md`, `connect-whatsapp-zapster.md`, `debug-channel.md`
+- Channels: `docs/guides/add-channel.md`, `connect-discord.md`, `connect-slack.md`, `connect-telegram.md`, `connect-whatsapp-evolution.md`, `connect-whatsapp-uazapi.md`, `connect-whatsapp-zapster.md`, `debug-channel.md`
 - Security: `docs/guides/security-rules.md`
 
 Use `npm run agentkit -- docs full` only for a complete-contract audit, framework internals, or a behavior not covered by the task guide.
-

package/src/templates/skills/agentkit-channels/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agentkit-channels
-description: Use when adding, connecting, testing, buffering, or debugging AgentKit website, Telegram, or WhatsApp channels, including channel config helpers, provider secrets, webhook setup, channel tests, delivery logs, and burst-message buffers.
+description: Use when adding, connecting, testing, buffering, transcribing audio, or debugging AgentKit website, Telegram, WhatsApp, Discord, Slack, or generic webhook channels, including channel config helpers, provider secrets, webhook setup, channel tests, delivery logs, burst-message buffers, and transcription provider secrets.
 ---
 
 # AgentKit Channels
@@ -16,6 +16,41 @@ Channels receive user messages. Tools let the agent call external systems. Keep
 5. Connect channel resources through the CLI.
 6. Test, doctor, and inspect delivery logs.
 
+## Audio Transcription
+
+Enable transcription at the agent level and opt in per channel with `audio.mode: "transcribe"`.
+
+```ts
+export default defineAgent({
+  // ...
+  transcription: {
+    provider: "groq",
+    model: "whisper-large-v3-turbo",
+    secret: "GROQ_API_KEY",
+    language: "pt",
+    limits: {
+      maxDurationSeconds: 180,
+      maxBytes: 20_000_000,
+    },
+  },
+  channels: [
+    telegramChannel({
+      name: "support-telegram",
+      audio: { mode: "transcribe" },
+    }),
+  ],
+});
+```
+
+V1 providers:
+
+- `openai`: `gpt-4o-mini-transcribe`, `gpt-4o-transcribe`, `whisper-1`; default secret `OPENAI_API_KEY`.
+- `groq`: `whisper-large-v3-turbo`, `whisper-large-v3`, `distil-whisper-large-v3-en`; default secret `GROQ_API_KEY`.
+
+Telegram voice notes are usually OGG/Opus, so use Groq for the default Telegram voice-note path in V1. Zapster audio needs a usable HTTPS Zapster media download URL in the webhook payload; arbitrary hosts are rejected before bearer auth is sent. UAZAPI audio downloads go through UAZAPI `/message/download` with base64 return enabled. Evolution audio downloads go through Evolution API `/chat/getBase64FromMediaMessage/{instance}` with base64 return enabled. Arbitrary UAZAPI and Evolution webhook media hosts are not fetched. Hosted channel creation requires the transcription secret automatically when the channel enables transcription. Webhooks only enqueue audio jobs; download and transcription run in the retryable channel worker before the agent run.
+
+Discord channels do not support audio in V1.
+
 ## Buffering
 
 Enable `buffer.mode: "debounce"` when clients send several short messages in a row and the agent should answer once.
@@ -45,14 +80,26 @@ npm run agentkit -- channels list
 npm run agentkit -- channels add website website-chat
 npm run agentkit -- channels connect telegram support-telegram
 npm run agentkit -- channels add whatsapp support-whatsapp --provider zapster
+npm run agentkit -- channels connect whatsapp support-whatsapp --provider uazapi
+npm run agentkit -- channels connect whatsapp main-whatsapp --provider evolution
+npm run agentkit -- channels connect discord support-discord
+npm run agentkit -- channels connect discord server-discord --mode bot
+npm run agentkit -- channels connect slack support-slack
+npm run agentkit -- channels connect webhook n8n-webhook
 npm run agentkit -- channels doctor support-telegram
 npm run agentkit -- channels test support-telegram --message "hello"
+npm run agentkit -- channels test-audio support-telegram --fixture voice-note
+npm run agentkit -- transcribe smoke --provider groq
 npm run agentkit -- channels deliveries list support-telegram
 ```
 
 ## References
 
+- `references/discord.md`
+- `references/slack.md`
 - `references/telegram.md`
+- `references/whatsapp-evolution.md`
+- `references/whatsapp-uazapi.md`
 - `references/whatsapp-zapster.md`
 - `references/channel-buffering.md`
 - `references/channel-debugging.md`
@@ -60,3 +107,21 @@ npm run agentkit -- channels deliveries list support-telegram
 ## Safety
 
 Do not paste provider tokens into code, docs, fixtures, prompts, evals, or delivery logs. Webhook URLs are public transport endpoints; authenticity comes from provider validation or channel tokens.
+
+## Generic Webhooks
+
+Use `webhookChannel({ name: "n8n-webhook" })` for n8n, Make, Zapier, Pipedream, or custom server events.
+
+Canonical JSON:
+
+```json
+{
+  "event_id": "evt_123",
+  "external_id": "customer_123",
+  "message": "hello from n8n"
+}
+```
+
+`event_id` is required for dedupe. `external_id` is recommended for conversation continuity and is hashed before storage. Authenticate with `Authorization: Bearer <AGENTKIT_WEBHOOK_SECRET>`, `X-AgentKit-Webhook-Secret`, or `X-AgentKit-Webhook-Signature: sha256=<hmac of raw JSON body>`.
+
+Generic webhooks are inbound-only in V1. Add a separate tool if the agent must call back into n8n after it runs.

package/src/templates/skills/agentkit-channels/references/channel-buffering.md

@@ -43,6 +43,11 @@ Behavior:
 Debug:
 
 ```sh
+agentkit channels buffers list <name>
+agentkit channels buffers show <conversation-id>
+agentkit channels buffers flush <conversation-id>
+agentkit channels buffers clear <conversation-id>
+agentkit channels buffers retry <conversation-id>
 agentkit channels deliveries list <name>
 agentkit channels deliveries show <delivery-id>
 ```
@@ -54,5 +59,7 @@ buffered
 queued
 running
 agent_completed
-outbound_sent
+provider_request_built
+provider_sent
+adapter_stubbed
 ```

package/src/templates/skills/agentkit-channels/references/channel-debugging.md

@@ -7,8 +7,15 @@ agentkit channels list
 agentkit channels status <name>
 agentkit channels doctor <name>
 agentkit channels test <name> --message "hello"
+agentkit channels test-audio <name> --fixture voice-note
+agentkit transcribe smoke --provider groq
 agentkit channels deliveries list <name> --since 24h
 agentkit channels deliveries show <delivery-id>
+agentkit channels buffers list <name>
+agentkit channels buffers show <conversation-id>
+agentkit channels buffers flush <conversation-id>
+agentkit channels buffers clear <conversation-id>
+agentkit channels buffers retry <conversation-id>
 ```
 
 Common states:
@@ -17,11 +24,17 @@ Common states:
 webhook_received
 validated
 duplicate
+audio_received
+audio_downloaded
+transcribing
+transcribed
 buffered
 queued
 running
 agent_completed
-outbound_sent
+provider_request_built
+provider_sent
+adapter_stubbed
 delivered
 provider_failed
 synthetic_expected_failure
@@ -31,11 +44,23 @@ skipped
 
 Common errors:
 
-- `channel_not_found`: webhook URL points to an unknown channel.
+- `channel_not_found`: webhook URL points to an unknown channel. `channels test` is the official synthetic smoke and should resolve the current `.agentkit/deploy.json` channel.
 - `channel_secret_missing`: required hosted secret is not set.
-- `channel_signature_invalid`: webhook secret/token mismatch.
+- `channel_signature_invalid`: webhook secret, token, origin header, or Discord public key mismatch.
+- Discord bot mode with no deliveries: confirm `--mode bot`, `DISCORD_BOT_TOKEN`, Message Content Intent, server install, and channel permissions for View Channel, Read Message History, and Send Messages.
 - `channel_payload_invalid`: malformed or unsupported provider payload.
 - `channel_event_duplicate`: provider retry; do not create a second run.
+- `audio_received`: audio message was accepted and normalized.
+- `audio_downloaded`: retryable channel worker downloaded provider media into memory.
+- `transcribing`: AgentKit is calling the configured transcription provider.
+- `transcribed`: transcript text was queued for the agent.
+- `channel_audio_download_unavailable`: provider audio payload did not include a usable download URL, or Zapster sent a non-HTTPS/non-Zapster media host.
+- `transcription_secret_missing`: managed transcription secret is missing.
+- `transcription_audio_too_large` or `transcription_audio_too_long`: audio exceeded configured limits.
+- `transcription_audio_format_unsupported`: provider does not accept this audio MIME type or extension.
+- `transcription_provider_unavailable`: retryable transcription provider failure.
 - `channel_limit_exceeded`: backpressure skipped the message.
 - `synthetic_expected_failure`: a synthetic test reached AgentKit, but the provider correctly rejected a fake test recipient.
 - `buffered` delivery state: message is waiting for the channel quiet window or max wait before one coalesced agent run is queued.
+- `adapter_stubbed`: adapter completed without calling an outbound provider, either because explicit dry-run mode is enabled or the channel is inbound-only.
+- `provider_sent`: the provider accepted the outbound send and returned a provider message ID.

package/src/templates/skills/agentkit-channels/references/discord.md

@@ -0,0 +1,93 @@
+# Discord Channel
+
+Discord supports two modes:
+
+- `interactions`: slash commands through the Discord Interactions Endpoint URL.
+- `bot`: normal server messages through a Discord Bot user and Gateway connection.
+
+Use bot mode when the owner asks for the agent to answer without slash commands.
+
+## Slash Commands
+
+Required secret:
+
+```txt
+DISCORD_PUBLIC_KEY
+```
+
+Config:
+
+```ts
+discordChannel({ name: "support-discord" })
+```
+
+Commands:
+
+```sh
+agentkit deploy
+agentkit secret set DISCORD_PUBLIC_KEY --stdin
+agentkit channels connect discord support-discord
+agentkit channels test support-discord --message "hello"
+agentkit channels deliveries list support-discord
+```
+
+Paste the printed webhook URL into the application's Interactions Endpoint URL. Register a slash command with a string option named `message`, `text`, `prompt`, `question`, `query`, or `input`.
+
+## Bot Server Messages
+
+Required secret:
+
+```txt
+DISCORD_BOT_TOKEN
+```
+
+Config:
+
+```ts
+discordChannel({
+  name: "server-discord",
+  mode: "bot",
+})
+```
+
+Commands:
+
+```sh
+agentkit deploy
+agentkit secret set DISCORD_BOT_TOKEN --stdin
+agentkit channels connect discord server-discord --mode bot
+agentkit channels test server-discord --message "hello"
+agentkit channels deliveries list server-discord
+```
+
+In the Discord Developer Portal, open the Bot page, enable Message Content Intent, install the app into the server, and grant the bot `View Channel`, `Read Message History`, and `Send Messages` in the channels it should answer.
+
+Bot mode processes every readable non-bot text message Discord sends over the Gateway. Keep server permissions narrow if the agent should answer only in specific channels.
+
+## Buffering
+
+Buffer rapid Discord messages:
+
+```ts
+discordChannel({
+  name: "server-discord",
+  mode: "bot",
+  buffer: {
+    mode: "debounce",
+    quietWindowMs: 1500,
+    maxWaitMs: 8000,
+    maxMessages: 20,
+    maxChars: 8000,
+  },
+})
+```
+
+## Runtime Behavior
+
+Slash-command mode validates `X-Signature-Ed25519` and `X-Signature-Timestamp` against the raw body and `DISCORD_PUBLIC_KEY`, returns `type: 1` for Discord `PING`, acknowledges slash commands with a deferred response, then sends the final answer as an interaction follow-up.
+
+Bot mode connects to Discord Gateway with `DISCORD_BOT_TOKEN`, requests guild message and message-content intents, ignores bot-authored messages, normalizes `MESSAGE_CREATE`, and sends the final answer through `/channels/<channel_id>/messages`.
+
+All outbound Discord sends use `allowed_mentions: { parse: [] }`. Discord interaction tokens and bot tokens must not appear in delivery, queue, buffer, or doctor API responses.
+
+Discord audio is not supported in V1; do not configure `audio` on `discordChannel`.

package/src/templates/skills/agentkit-channels/references/slack.md

@@ -0,0 +1,56 @@
+# Slack Channel
+
+Slack uses Events API webhooks.
+
+V1 supports:
+
+- `app_mention` in channels.
+- `message.im` direct messages.
+- Outbound replies through `chat.postMessage`.
+
+V1 does not support Socket Mode, files, audio transcription, app-management automation, or all-channel message listening.
+
+## Required Secrets
+
+```txt
+SLACK_BOT_TOKEN
+SLACK_SIGNING_SECRET
+```
+
+## Config
+
+```ts
+slackChannel({
+  name: "support-slack",
+})
+```
+
+## Commands
+
+```sh
+agentkit deploy
+agentkit secret set SLACK_BOT_TOKEN --stdin
+agentkit secret set SLACK_SIGNING_SECRET --stdin
+agentkit channels connect slack support-slack
+agentkit channels test support-slack --message "hello"
+agentkit channels deliveries list support-slack
+```
+
+## Slack Setup
+
+In Slack app configuration:
+
+1. Basic Information: copy Signing Secret into `SLACK_SIGNING_SECRET`.
+2. OAuth & Permissions: add bot scopes `app_mentions:read`, `im:history`, and `chat:write`.
+3. Install or reinstall the app to the workspace.
+4. Copy the Bot User OAuth Token into `SLACK_BOT_TOKEN`.
+5. Event Subscriptions: enable events and paste the AgentKit webhook URL.
+6. Subscribe to bot events `app_mention` and `message.im`.
+
+## Runtime Behavior
+
+AgentKit verifies `X-Slack-Signature` and `X-Slack-Request-Timestamp` against the raw body before processing events. It rejects stale timestamps, answers `url_verification` with the literal challenge, skips bot/subtype messages, maps channel mentions to Slack threads, maps DMs to the Slack DM channel and user, and replies with `chat.postMessage`.
+
+Outbound Slack text escapes Slack control mentions and disables link-name expansion and unfurls.
+
+Slack audio is not supported in V1; do not configure `audio` on `slackChannel`.