@andreprado/agentkit 0.1.1 → 0.2.0

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

@@ -1,127 +1,14 @@
 ---
 name: agentkit-channels
-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.
+description: Configure and debug local AgentKit website, messaging, and webhook channels.
 ---
 
-# AgentKit Channels
+# Local Channels
 
-Channels receive user messages. Tools let the agent call external systems. Keep them separate.
+Read `docs/guides/add-channel.md` using the root from `agentkit docs path`, then the provider guide. Keep `runtime: "local"`, register the channel helper in config, and put secret names in `.env.schema`. Set values through `agentkit env set <NAME> --stdin`.
 
-## Workflow
+Run `agentkit inspect`, `agentkit channels list`, and `agentkit dev`. POST authenticated fixtures to the local webhook route and inspect the response and conversation trace. For real provider traffic, configure its webhook manually against an HTTPS tunnel. The local process must remain running. Only authenticated webhook routes accept tunnel hosts.
 
-1. Add channel helpers in `agentkit.config.ts`.
-2. Keep `runtime: "edge"` and `storage.driver: "agentkit"`.
-3. Deploy before hosted channel creation.
-4. Configure provider secrets as managed secrets.
-5. Connect channel resources through the CLI.
-6. Test, doctor, and inspect delivery logs.
+Keep provider signature checks, query-token secrets, reply routing validation, and SSRF restrictions. Synthetic fixtures do not prove real provider delivery. Use `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` when a test must not contact real recipients. AgentKit does not run a Discord Gateway worker.
 
-## 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.
-
-```ts
-whatsappChannel({
-  name: "support-whatsapp",
-  provider: "zapster",
-  buffer: {
-    mode: "debounce",
-    quietWindowMs: 2500,
-    maxWaitMs: 12000,
-    maxMessages: 20,
-    maxChars: 8000,
-  },
-})
-```
-
-Buffered deliveries show `buffered` until AgentKit flushes the conversation buffer into one queued run.
-
-## Commands
-
-```sh
-npm run agentkit -- inspect
-npm run agentkit -- deploy
-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`
-
-## 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.
+Use `docs/guides/debug-channel.md` and `docs/guides/channel-security.md` for diagnosis and trust boundaries. Provider-specific notes live in `references/`.

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

@@ -42,15 +42,6 @@ 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>
-```
 
 Expected delivery states:
 

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

@@ -1,66 +1,3 @@
 # Channel Debugging
 
-Start with:
-
-```sh
-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:
-
-```txt
-webhook_received
-validated
-duplicate
-audio_received
-audio_downloaded
-transcribing
-transcribed
-buffered
-queued
-running
-agent_completed
-provider_request_built
-provider_sent
-adapter_stubbed
-delivered
-provider_failed
-synthetic_expected_failure
-dead_lettered
-skipped
-```
-
-Common errors:
-
-- `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, 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.
+Read `docs/guides/debug-channel.md` from the root printed by `agentkit docs path`. Configure local secrets and use `agentkit dev` for diagnostics. Provider webhook registration is manual; synthetic checks do not prove real delivery.

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

@@ -1,93 +1,3 @@
-# Discord Channel
+# Discord
 
-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`.
+Read `docs/guides/connect-discord.md` from the root printed by `agentkit docs path`. Configure local secrets and use `agentkit dev` for diagnostics. Provider webhook registration is manual; synthetic checks do not prove real delivery.

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

@@ -1,56 +1,3 @@
-# Slack Channel
+# Slack
 
-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`.
+Read `docs/guides/connect-slack.md` from the root printed by `agentkit docs path`. Configure local secrets and use `agentkit dev` for diagnostics. Provider webhook registration is manual; synthetic checks do not prove real delivery.

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

@@ -1,72 +1,3 @@
-# Telegram Channel
+# Telegram
 
-Required secrets:
-
-```txt
-TELEGRAM_BOT_TOKEN
-TELEGRAM_WEBHOOK_SECRET
-```
-
-Audio transcription also needs the configured transcription secret, usually:
-
-```txt
-GROQ_API_KEY
-```
-
-Commands:
-
-```sh
-agentkit deploy
-agentkit secret set TELEGRAM_BOT_TOKEN --stdin
-agentkit secret set TELEGRAM_WEBHOOK_SECRET --stdin
-agentkit channels connect telegram support-telegram
-agentkit channels doctor support-telegram
-agentkit channels status support-telegram
-agentkit channels test support-telegram --message "hello"
-agentkit channels test-audio support-telegram --fixture voice-note
-agentkit transcribe smoke --provider groq
-agentkit channels deliveries list support-telegram
-```
-
-`connect` creates or reuses the hosted channel, validates managed secrets, calls Telegram `setWebhook`, confirms `getWebhookInfo`, runs a synthetic smoke, and prints the human Telegram steps. Use `setup --apply` only when you need to repeat webhook registration without running smoke.
-
-Buffer rapid Telegram messages:
-
-```ts
-telegramChannel({
-  name: "support-telegram",
-  buffer: {
-    mode: "debounce",
-    quietWindowMs: 1500,
-    maxWaitMs: 8000,
-    maxMessages: 20,
-    maxChars: 8000,
-  },
-})
-```
-
-Transcribe Telegram voice notes:
-
-```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" },
-    }),
-  ],
-});
-```
-
-AgentKit validates the Telegram webhook, normalizes `voice` and `audio` payloads, enqueues an audio job, then the retryable channel worker calls Telegram `getFile`, downloads the media with `TELEGRAM_BOT_TOKEN`, sends the bytes to the configured transcription provider, and runs the agent with transcript text. Telegram voice notes are usually OGG/Opus; use Groq in V1 for that path. `test-audio` validates the audio channel ingress path; `transcribe smoke` validates the transcription provider separately.
+Read `docs/guides/connect-telegram.md` from the root printed by `agentkit docs path`. Configure local secrets and use `agentkit dev` for diagnostics. Provider webhook registration is manual; synthetic checks do not prove real delivery.

package/src/templates/skills/agentkit-channels/references/whatsapp-evolution.md

@@ -1,57 +1,3 @@
-# WhatsApp Through Evolution API
+# Whatsapp Evolution
 
-Required secrets:
-
-```txt
-EVOLUTION_API_BASE_URL
-EVOLUTION_API_KEY
-EVOLUTION_INSTANCE_NAME
-EVOLUTION_WEBHOOK_TOKEN
-```
-
-Audio transcription also needs the configured transcription secret, usually `OPENAI_API_KEY` or `GROQ_API_KEY`.
-
-Commands:
-
-```sh
-agentkit deploy
-agentkit channels add whatsapp main-whatsapp --provider evolution
-agentkit channels setup main-whatsapp --apply
-agentkit channels status main-whatsapp
-agentkit channels test main-whatsapp --message "hello"
-agentkit channels deliveries list main-whatsapp
-```
-
-AgentKit applies Evolution setup by calling `/webhook/set/{instance}` with the stable hosted URL and then confirming the configured webhook through `/webhook/find/{instance}`. AgentKit appends `?token=<EVOLUTION_WEBHOOK_TOKEN>` to the registered webhook URL.
-
-Inbound Evolution `MESSAGES_UPSERT` webhooks normalize text and audio messages. `fromMe` messages are skipped to avoid reply loops. Unsupported media should be logged as skipped/unsupported without creating an agent run.
-
-Outbound replies call Evolution API `POST /message/sendText/{instance}` with the `apikey` header and a JSON body containing `number` and `text`. Only set `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` in tests when Evolution should not receive a real message.
-
-Buffer rapid WhatsApp messages:
-
-```ts
-whatsappChannel({
-  name: "main-whatsapp",
-  provider: "evolution",
-  buffer: {
-    mode: "debounce",
-    quietWindowMs: 2500,
-    maxWaitMs: 12000,
-    maxMessages: 20,
-    maxChars: 8000,
-  },
-})
-```
-
-Transcribe WhatsApp audio:
-
-```ts
-whatsappChannel({
-  name: "main-whatsapp",
-  provider: "evolution",
-  audio: { mode: "transcribe" },
-})
-```
-
-Evolution audio downloads use `/chat/getBase64FromMediaMessage/{instance}` and AgentKit rejects unsafe Evolution base URLs before sending `EVOLUTION_API_KEY`; do not use localhost, private-network hosts, or HTTP base URLs.
+Read `docs/guides/connect-whatsapp-evolution.md` from the root printed by `agentkit docs path`. Configure local secrets and use `agentkit dev` for diagnostics. Provider webhook registration is manual; synthetic checks do not prove real delivery.

package/src/templates/skills/agentkit-channels/references/whatsapp-uazapi.md

@@ -1,54 +1,3 @@
-# WhatsApp Through UAZAPI
+# Whatsapp Uazapi
 
-Required secrets:
-
-```txt
-UAZAPI_BASE_URL
-UAZAPI_TOKEN
-UAZAPI_WEBHOOK_TOKEN
-```
-
-Audio transcription also needs the configured transcription secret, usually `OPENAI_API_KEY` or `GROQ_API_KEY`.
-
-Commands:
-
-```sh
-node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))" | npm run agentkit -- env set UAZAPI_WEBHOOK_TOKEN --stdin
-npm run agentkit -- env set UAZAPI_BASE_URL --stdin
-npm run agentkit -- env set UAZAPI_TOKEN --stdin
-npm run agentkit -- dev
-```
-
-`UAZAPI_WEBHOOK_TOKEN` is generated by the user for AgentKit; UAZAPI does not issue it. Expose the local port through an HTTPS tunnel and register the exact `/channels/support-whatsapp/whatsapp/uazapi/webhook?token=<UAZAPI_WEBHOOK_TOKEN>` URL with `addUrlEvents: false` and `addUrlTypesMessages: false`. Send a real message to confirm UAZAPI preserves the complete URL.
-
-Inbound UAZAPI `messages` webhooks normalize text and audio messages. `fromMe` and `wasSentByApi` messages are skipped to avoid reply loops. Unsupported media should be logged as skipped/unsupported without creating an agent run.
-
-Outbound replies call UAZAPI `POST /send/text` with the `token` header and a JSON body containing `number`, `text`, `readchat`, `async`, `track_source`, and `track_id`. Only set `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` in tests when UAZAPI should not receive a real message.
-
-Buffer rapid WhatsApp messages:
-
-```ts
-whatsappChannel({
-  name: "support-whatsapp",
-  provider: "uazapi",
-  buffer: {
-    mode: "debounce",
-    quietWindowMs: 2500,
-    maxWaitMs: 12000,
-    maxMessages: 20,
-    maxChars: 8000,
-  },
-})
-```
-
-Transcribe WhatsApp audio:
-
-```ts
-whatsappChannel({
-  name: "support-whatsapp",
-  provider: "uazapi",
-  audio: { mode: "transcribe" },
-})
-```
-
-UAZAPI audio downloads use `/message/download` with `return_base64: true`, `return_link: false`, `generate_mp3: false`, and `transcribe: false`. AgentKit rejects unsafe UAZAPI base URLs before sending `UAZAPI_TOKEN`; do not use localhost, private-network hosts, or HTTP base URLs.
+Read `docs/guides/connect-whatsapp-uazapi.md` from the root printed by `agentkit docs path`. Configure local secrets and use `agentkit dev` for diagnostics. Provider webhook registration is manual; synthetic checks do not prove real delivery.

package/src/templates/skills/agentkit-channels/references/whatsapp-zapster.md

@@ -1,71 +1,3 @@
-# WhatsApp Through Zapster
+# Whatsapp Zapster
 
-Required secrets:
-
-```txt
-ZAPSTER_API_KEY
-ZAPSTER_INSTANCE_ID
-ZAPSTER_WEBHOOK_ID
-ZAPSTER_WEBHOOK_TOKEN
-```
-
-Audio transcription also needs the configured transcription secret, usually `OPENAI_API_KEY` or `GROQ_API_KEY`.
-
-Commands:
-
-```sh
-node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))" | npm run agentkit -- env set ZAPSTER_WEBHOOK_TOKEN --stdin
-npm run agentkit -- env set ZAPSTER_API_KEY --stdin
-npm run agentkit -- env set ZAPSTER_INSTANCE_ID --stdin
-npm run agentkit -- env set ZAPSTER_WEBHOOK_ID --stdin
-npm run agentkit -- dev
-```
-
-`ZAPSTER_WEBHOOK_TOKEN` is generated by the user for AgentKit; Zapster does not issue it. Expose the local port through an HTTPS tunnel and register the exact `/channels/support-whatsapp/whatsapp/zapster/webhook?token=<ZAPSTER_WEBHOOK_TOKEN>` URL. Send a real message to confirm Zapster preserves the complete URL. Keep phone numbers redacted in logs by default.
-
-AgentKit handles Zapster `message.received` envelopes with event id at `id`, message text at `data.content.text`, and contact identity at `data.sender.id`. Unsupported media should be logged as skipped/unsupported without creating an agent run.
-
-Outbound replies call `POST https://api.zapsterapi.com/v1/wa/messages` with bearer auth and a JSON body containing `recipient`, `text`, and `instance_id`. Only set `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` in tests when Zapster should not receive a real message.
-
-Buffer rapid WhatsApp messages:
-
-```ts
-whatsappChannel({
-  name: "support-whatsapp",
-  provider: "zapster",
-  buffer: {
-    mode: "debounce",
-    quietWindowMs: 2500,
-    maxWaitMs: 12000,
-    maxMessages: 20,
-    maxChars: 8000,
-  },
-})
-```
-
-Transcribe WhatsApp audio:
-
-```ts
-export default defineAgent({
-  // ...
-  transcription: {
-    provider: "openai",
-    model: "gpt-4o-mini-transcribe",
-    secret: "OPENAI_API_KEY",
-    language: "pt",
-    limits: {
-      maxDurationSeconds: 180,
-      maxBytes: 20_000_000,
-    },
-  },
-  channels: [
-    whatsappChannel({
-      name: "support-whatsapp",
-      provider: "zapster",
-      audio: { mode: "transcribe" },
-    }),
-  ],
-});
-```
-
-Zapster audio payloads must include a usable HTTPS Zapster media download URL such as `audio.downloadUrl`, `audio.url`, `audio.mediaUrl`, or the snake_case equivalents. AgentKit rejects arbitrary hosts before sending `ZAPSTER_API_KEY`. The retryable channel worker downloads the media, transcribes it through the configured provider secret, and runs the agent with transcript text. If Zapster sends only a media ID in V1, AgentKit records `channel_audio_download_unavailable`.
+Read `docs/guides/connect-whatsapp-zapster.md` from the root printed by `agentkit docs path`. Configure local secrets and use `agentkit dev` for diagnostics. Provider webhook registration is manual; synthetic checks do not prove real delivery.

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

@@ -1,6 +1,6 @@
 ---
 name: agentkit-database
-description: Use when adding AgentKit-managed database tables, editing schema.sql, writing database-backed tools, seeding local data, or verifying local/hosted storage compatibility through ctx.db.
+description: Use when adding AgentKit-local database tables, editing schema.sql, writing database-backed tools, seeding local data, or verifying local storage compatibility through ctx.db.
 ---
 
 # AgentKit Database
@@ -23,7 +23,7 @@ When the owner asks the agent to save or update records, do not stop after addin
 - Put the first idempotent bootstrap schema in `schema.sql`.
 - For production-shaped changes, prefer ordered `migrations/*.sql` files such as `migrations/0001_initial.sql`.
 - Keep `schema.sql` idempotent with `CREATE TABLE IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`, and safe additive changes.
-- Keep deploy-ready capsules on `storage.driver: "agentkit"`.
+- Keep local capsules on `storage.driver: "agentkit"`.
 - Use `ctx.db` inside tools. `ctx.database` and `ctx.storage.sql` are aliases.
 - Do not import SQLite, Turso, or other database drivers from tools.
 - Do not edit `.agentkit/agentkit.db` by hand.
@@ -52,5 +52,3 @@ npm run typecheck
 npm run agentkit -- db migrate
 npm run agentkit -- tool <tool_name> --input '<json>'
 ```
-
-Hosted deploy applies AgentKit-managed storage internally. The user should not create hosted databases or buckets by hand.

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

@@ -19,7 +19,7 @@ Use evals after chat works and before claiming behavior is stable.
 6. For date-sensitive flows, set top-level `now` to an ISO timestamp with `Z` or a numeric offset so today, tomorrow, weekdays, and tool date validation stay deterministic.
 7. Use `turns` for full conversation flows, such as user asks, agent calls a tool, then the answer follows the required format.
 8. Convert local failures into regression tests with `npm run agentkit -- eval from-conversation <conversation-id>`.
-9. Convert hosted or local production evidence into regression tests with `npm run agentkit -- improve collect --deploy --since 24h`, then `npm run agentkit -- improve evals .agentkit/improve/<run>`.
+9. Convert local production evidence into regression tests with `npm run agentkit -- improve collect --since 24h`, then `npm run agentkit -- improve evals .agentkit/improve/<run>`.
 10. Do not put secrets or real client PII in evals.
 11. For tools that write externally, delete, charge money, send email, or call real customer systems, branch on `ctx.runtime.environment === "eval"` inside the registered tool.