@andreprado/agentkit 0.1.0-alpha.17 → 0.1.0-alpha.19

package/README.md

@@ -44,6 +44,9 @@ agentkit db migrate
 agentkit sync run
 agentkit eval run
 agentkit eval from-conversation <conversation-id>
+agentkit improve collect --deploy --since 24h
+agentkit improve evals .agentkit/improve/<run>
+agentkit replay .agentkit/improve/<run> --against local
 agentkit conversations list
 agentkit conversations trace <conversation-id>
 ```

package/docs/guides/add-channel.md

@@ -6,7 +6,7 @@ Add a hosted messaging channel to an Agent Capsule, create the hosted channel re
 
 ## When To Use It
 
-Use this when the agent should receive messages from website chat, Telegram, or WhatsApp through AgentKit-owned webhook infrastructure.
+Use this when the agent should receive messages from website chat, Telegram, WhatsApp, or Discord through AgentKit-owned channel infrastructure.
 
 ## Commands
 
@@ -17,6 +17,8 @@ agentkit channels list
 agentkit channels add website website-chat
 agentkit channels add telegram support-telegram
 agentkit channels add whatsapp support-whatsapp --provider zapster
+agentkit channels connect discord support-discord
+agentkit channels connect discord server-discord --mode bot
 agentkit channels setup support-telegram
 agentkit channels status support-telegram
 agentkit channels test support-telegram --message "hello"
@@ -24,19 +26,19 @@ agentkit channels deliveries list support-telegram
 agentkit channels buffers list support-telegram
 ```
 
-Use `--api <url>` with hosted commands when testing against a non-default AgentKit Cloud API.
+Use `--api <url>` only when the owner gives you a non-default AgentKit Cloud API URL.
 
 ## Files Created Or Edited
 
-- `agentkit.config.ts`: declare channel config with `websiteChannel`, `telegramChannel`, or `whatsappChannel`.
+- `agentkit.config.ts`: declare channel config with `websiteChannel`, `telegramChannel`, `whatsappChannel`, or `discordChannel`.
 - `.agentkit/deploy.json`: written by `agentkit deploy`; used by `agentkit channels ...`.
-- No user Turso tables: AgentKit channel resources, dedupe, identities, queue state, and delivery logs are control-plane owned.
+- No user Turso tables: AgentKit owns channel resources, dedupe, identities, queue state, and delivery logs.
 - Website channel clients must send `AGENTKIT_WEBSITE_CHANNEL_TOKEN` as `Authorization: Bearer <token>` or `X-AgentKit-Channel-Token`.
 
 ## Minimal Working Example
 
 ```ts
-import { defineAgent, telegramChannel, whatsappChannel, websiteChannel } from "@andreprado/agentkit";
+import { defineAgent, discordChannel, telegramChannel, whatsappChannel, websiteChannel } from "@andreprado/agentkit";
 
 export default defineAgent({
   name: "support-agent",
@@ -49,6 +51,8 @@ export default defineAgent({
     websiteChannel({ name: "website-chat" }),
     telegramChannel({ name: "support-telegram" }),
     whatsappChannel({ name: "support-whatsapp", provider: "zapster" }),
+    discordChannel({ name: "support-discord" }),
+    discordChannel({ name: "server-discord", mode: "bot" }),
   ],
   access: { mode: "public" },
   storage: { driver: "agentkit" },
@@ -87,9 +91,11 @@ agentkit channels buffers clear support-whatsapp <conversation-id>
 agentkit channels buffers retry support-whatsapp <conversation-id>
 ```
 
+Discord supports buffering for slash-command interactions and bot-mode server messages, but it does not support `audio` in V1.
+
 ## Auto Transcribe Audio
 
-Use `transcription` at the agent level and `audio.mode: "transcribe"` on each channel that should accept voice notes or audio files.
+Use `transcription` at the agent level and `audio.mode: "transcribe"` on each Telegram or WhatsApp channel that should accept voice notes or audio files.
 
 ```ts
 export default defineAgent({
@@ -178,10 +184,10 @@ Run `agentkit deploy` before creating hosted channel resources.
 Set the named hosted secret. Do not add production values to `.env`.
 
 `channel_signature_invalid`:
-The provider webhook secret, token, or origin header does not match the managed secret.
+The provider webhook secret, token, origin header, or Discord Ed25519 signature does not match the managed secret.
 
 `channel_limit_exceeded`:
-The channel daily message limit was reached. Website requests return `429`; Telegram and WhatsApp are acknowledged and skipped to avoid provider retry storms.
+The channel daily message limit was reached. Website requests return `429`; Telegram, WhatsApp, and Discord are acknowledged and skipped to avoid provider retry storms.
 
 `transcription_secret_missing`:
 Set the managed transcription secret declared by `agentkit inspect`, for example `OPENAI_API_KEY` or `GROQ_API_KEY`.

package/docs/guides/add-knowledge.md

@@ -77,8 +77,17 @@ agentkit knowledge search "refund policy" --top-k 3
 
 `knowledge add` is useful for one-off local indexing. `knowledge sync` validates and indexes all configured `knowledge.sources` on demand. `agentkit dev` and `agentkit chat` also sync configured Knowledge automatically before local runs, and unchanged files are skipped by content hash.
 
+On Windows PowerShell, if `npm.ps1` is blocked by `PSSecurityException`, run capsule scripts through the `.cmd` shim:
+
+```sh
+npm.cmd run agentkit -- knowledge sync
+npm.cmd run agentkit -- knowledge search "refund policy" --top-k 3
+```
+
 When embeddings are configured locally, AgentKit stores canonical Knowledge chunks in `.agentkit/agentkit.db` and rebuilds a local libSQL vector sidecar at `.agentkit/agentkit.vectors.db`. Local semantic search uses the sidecar's native `libsql_vector_idx` path and falls back to stored JSON embeddings if the native vector path is unavailable.
 
+Local lexical search uses SQLite FTS5 when the local SQLite build provides it. If SQLite does not provide FTS5, AgentKit automatically keeps indexing and searching with a normal SQLite table and a simpler text-match fallback.
+
 ## Agent Behavior
 
 When `knowledge` is configured, AgentKit automatically registers the internal tool `agentkit_search_knowledge` during chat runs 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, or chunk IDs.
@@ -131,4 +140,5 @@ Local `agentkit knowledge add`, `agentkit knowledge sync`, `agentkit dev`, and `
 - `Knowledge source paths must stay inside the Agent Capsule`: move the source under the capsule root, usually `knowledge/`.
 - `Local Knowledge currently supports .md, .txt, and .csv files`: convert the source or add a tool for unsupported formats.
 - `Knowledge embeddings require missing secret`: set the env var named by `knowledge.embedding.secret`.
+- `PSSecurityException` on Windows PowerShell: use `npm.cmd run agentkit -- knowledge sync` or `npm.cmd run agentkit -- knowledge search "refund policy" --top-k 3`.
 - Hosted build says Turso is required: add `storage.database.driver: "turso"` before deploying Knowledge.

package/docs/guides/add-managed-composio.md

@@ -13,6 +13,7 @@ Managed Composio is paid hosted AgentKit infrastructure:
 - It works per agent/project, not per client.
 - It requires an AgentKit Cloud account with `managed_composio`.
 - AgentKit Cloud injects `COMPOSIO_API_KEY`; do not put it in `.env`, `.env.schema`, or `agentkit.config.ts`.
+- AgentKit Cloud resolves toolkit auth configs from its managed registry. The capsule owner only declares allowed toolkits/actions.
 - AgentKit Cloud assigns the deployed Composio `user_id` from the account, project, agent, and integration name. The local inspect/build id is only a preview.
 - The agent gets one generated tool, `agentkit_composio_execute`, only when explicit Composio action slugs are configured.
 - Anonymous deploys cannot use managed Composio.
@@ -39,8 +40,13 @@ export default defineAgent({
       toolkits: ["gmail", "googlecalendar"],
       tools: {
         gmail: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"],
-        googlecalendar: ["GOOGLECALENDAR_CREATE_EVENT"],
+        googlecalendar: [
+          "GOOGLECALENDAR_EVENTS_LIST",
+          "GOOGLECALENDAR_CREATE_EVENT",
+          "GOOGLECALENDAR_UPDATE_EVENT",
+        ],
       },
+      confirmExternalWrites: true,
     }),
   ],
   access: {
@@ -61,14 +67,15 @@ export default defineAgent({
 agentkit login --token agk_user_...
 agentkit deploy doctor
 agentkit deploy
-agentkit integrations status
+agentkit integrations status --toolkit googlecalendar
 ```
 
 Expected readiness:
 
-- `cloudflare_deploy_alpha` is active.
+- Hosted deploy access is active through `cloudflare_deploy_alpha` or purchased/manual deploy slots.
 - `managed_composio` is active.
 - `COMPOSIO_API_KEY` appears as an AgentKit-managed secret, not a user-managed hosted secret.
+- Each configured toolkit auth config is available in AgentKit Cloud.
 
 ## Connect Apps
 
@@ -83,23 +90,41 @@ AgentKit prints a URL. Send that URL to the person who owns the app account.
 
 If the deploy has only one toolkit, `--toolkit` can be omitted.
 
-## Operator Setup
+## Calendar Defaults
 
-Trusted AgentKit Cloud operators grant access and configure Composio auth configs:
+For Google Calendar agents, include read and write actions together. Do not expose only `GOOGLECALENDAR_CREATE_EVENT`; users naturally ask to see availability before booking.
 
-```sh
-npm run agentkit:operator -- accounts grant user@example.com --managed-composio
+Use these starter actions:
+
+```ts
+googlecalendar: [
+  "GOOGLECALENDAR_EVENTS_LIST",
+  "GOOGLECALENDAR_CREATE_EVENT",
+  "GOOGLECALENDAR_UPDATE_EVENT",
+]
 ```
 
-Required control-plane environment:
+`GOOGLECALENDAR_CREATE_EVENT` requires extra care:
 
-```txt
-AGENTKIT_SECRET_COMPOSIO_API_KEY=<project API key>
-AGENTKIT_COMPOSIO_AUTH_CONFIG_GMAIL=<auth config id>
-AGENTKIT_COMPOSIO_AUTH_CONFIG_GOOGLECALENDAR=<auth config id>
-```
+- `start_datetime` must be explicit UTC RFC3339, such as `2026-06-03T15:00:00Z` for 12:00 in `America/Sao_Paulo`.
+- `event_duration_minutes` or `event_duration_hour` must be explicit. AgentKit blocks the implicit Composio default because `event_duration_minutes` defaults to 30.
+- Confirm the final title, date, local time, duration, timezone, and attendees/location when relevant before creating or updating an event.
+
+## Write Confirmation
 
-Use one `AGENTKIT_COMPOSIO_AUTH_CONFIG_<TOOLKIT>` value per toolkit slug, uppercased with non-alphanumeric characters converted to `_`.
+Managed Composio requires confirmation for external write actions by default. For actions such as create, update, delete, send, patch, move, insert, clear, remove, import, or quick add, the generated `agentkit_composio_execute` tool requires `confirmed: true`.
+
+Set `confirmed: true` only after the user confirms the exact external change. If a capsule intentionally handles confirmation elsewhere, disable this guard explicitly:
+
+```ts
+composioManaged({
+  toolkits: ["googlecalendar"],
+  tools: {
+    googlecalendar: ["GOOGLECALENDAR_EVENTS_LIST", "GOOGLECALENDAR_CREATE_EVENT"],
+  },
+  confirmExternalWrites: false,
+})
+```
 
 ## Verification
 
@@ -107,7 +132,7 @@ Use one `AGENTKIT_COMPOSIO_AUTH_CONFIG_<TOOLKIT>` value per toolkit slug, upperc
 agentkit inspect
 agentkit build --target cloudflare
 agentkit deploy doctor
-agentkit integrations status
+agentkit integrations status --toolkit googlecalendar
 ```
 
 Expected:
@@ -117,6 +142,7 @@ Expected:
 - Build manifest includes `integrations`.
 - Build manifest includes `COMPOSIO_API_KEY`.
 - `deploy doctor` does not ask the user to set `COMPOSIO_API_KEY`.
+- `deploy doctor` reports each configured toolkit auth config as present before the connect link flow.
 
 ## Troubleshooting
 
@@ -126,11 +152,11 @@ Log in with a paid AgentKit Cloud account that has `managed_composio`.
 
 `managed_composio_auth_config_missing`:
 
-An operator must set `AGENTKIT_COMPOSIO_AUTH_CONFIG_<TOOLKIT>` on the control plane.
+The AgentKit Cloud account is entitled, but the requested toolkit is not configured in AgentKit Cloud yet. Report the exact error code and toolkit slug to the AgentKit owner.
 
 `managed_composio_not_configured`:
 
-An operator must set `AGENTKIT_SECRET_COMPOSIO_API_KEY` on the control plane.
+Managed Composio is not available for this AgentKit Cloud environment. Use BYO `defineTool` wrappers for now or ask the owner to enable managed Composio for the account.
 
 `integration_toolkit_required`:
 

package/docs/guides/channel-security.md

@@ -2,52 +2,40 @@
 
 ## Goal
 
-Keep channel webhooks, delivery logs, provider sends, and managed secrets safe by default.
+Configure website, Telegram, WhatsApp, and Discord channels without leaking secrets, storing raw provider payloads, or treating public webhook URLs as authorization.
 
 ## When To Use It
 
-Use this before adding a channel provider, changing webhook validation, adding delivery logging, or enabling real-provider smoke tests.
+Use this when a coding agent adds or changes channels in an Agent Capsule, enables audio transcription, inspects deliveries, or prepares a hosted deploy that receives provider webhooks.
 
 ## Commands
 
 ```sh
 agentkit inspect
 agentkit channels status <name>
+agentkit channels doctor <name>
+agentkit channels deliveries list <name> --since 24h
 agentkit channels deliveries show <delivery-id>
-bun test packages/agentkit/src/runtime/channels/adapters.test.ts
-bun test packages/agentkit/src/runtime/transcription.test.ts
-bun test packages/agentkit/src/runtime/deploy.test.ts
 ```
 
-Real-provider gates are opt-in:
-
-```sh
-AGENTKIT_RUN_TELEGRAM_CHANNEL_TESTS=1 bun test
-AGENTKIT_RUN_ZAPSTER_CHANNEL_TESTS=1 bun test
-```
-
-Telegram smoke also requires `TELEGRAM_BOT_TOKEN`, `TELEGRAM_WEBHOOK_SECRET`, and `AGENTKIT_TELEGRAM_WEBHOOK_URL`.
-
-Zapster smoke also requires `ZAPSTER_API_KEY`, `ZAPSTER_INSTANCE_ID`, and `AGENTKIT_ZAPSTER_TO`. `AGENTKIT_ZAPSTER_SEND_URL` is optional and defaults to `https://api.zapsterapi.com/v1/wa/messages`.
-
 ## Files Created Or Edited
 
-- `agentkit.config.ts`: secret names only.
-- Managed hosted secrets: production secret values, no readback.
-- Delivery records: hashes, statuses, provider event IDs, redacted metadata.
+- `agentkit.config.ts`: channel names, provider choices, audio/buffer config, and secret names only.
+- `.env.schema`: local secret names only when the capsule needs a local provider or local smoke.
+- `.env`: local-only secret values; do not commit it.
+- Hosted managed secrets: production secret values with no readback.
 
 ## Safety Rules
 
 - Public webhook URLs are not permission grants.
-- Validate provider authenticity when the provider supports it.
-- Do not store channel plumbing in the user's Turso database.
-- Do not store raw webhook bodies in delivery records; store a SHA-256 hash.
-- Do not store raw audio in delivery records. V1 audio transcription downloads provider media into memory and stores only redacted metadata and state transitions.
-- Redact bearer tokens, bot tokens, signing secrets, provider API tokens, and phone numbers.
-- Inject only channel-declared secrets into adapter code.
-- Inject transcription secrets only when the deploy manifest declares transcription and the channel uses `audio.mode: "transcribe"`.
-- Prefer acknowledging Telegram/WhatsApp over retry storms when a channel-level limit is exceeded.
-- Keep audio duration and byte limits bounded before provider calls to avoid uncontrolled transcription spend.
+- Keep provider tokens, webhook secrets, bot tokens, transcription keys, and bearer tokens out of source files.
+- Put secret names in `agentkit.config.ts`; put local values in ignored `.env`; upload production values with `agentkit secret set` or `agentkit secret sync`.
+- Do not store raw webhook bodies, raw audio, or provider secret values in tools, prompts, evals, fixtures, or delivery notes.
+- Do not expose Discord interaction tokens or bot tokens. Interaction tokens are reply tokens, not public identifiers.
+- Inspect delivery IDs, hashes, redacted metadata, and statuses instead of raw provider payloads.
+- Keep channel plumbing out of the agent's application database. The user's Turso tables are for the agent's business data.
+- Enable audio transcription only when the capsule declares a transcription provider and bounded `limits`.
+- Keep channel buffer limits bounded so bursty client messages cannot create unbounded runs or provider spend.
 
 ## Minimal Working Example
 
@@ -81,7 +69,7 @@ export default defineAgent({
 });
 ```
 
-The config contains secret names only. Hosted responses report:
+The config contains secret names only. Hosted responses report status, not values:
 
 ```txt
 TELEGRAM_BOT_TOKEN: set
@@ -89,25 +77,58 @@ TELEGRAM_WEBHOOK_SECRET: missing
 GROQ_API_KEY: set
 ```
 
+Discord slash-command mode uses a public key rather than a shared webhook secret:
+
+```ts
+discordChannel({
+  name: "support-discord",
+  secrets: ["DISCORD_PUBLIC_KEY"],
+});
+```
+
+AgentKit validates `X-Signature-Ed25519` and `X-Signature-Timestamp` against the raw body, returns `type: 1` for Discord `PING`, and sends follow-up replies with `allowed_mentions: { parse: [] }`.
+
+Discord bot mode uses a bot token and Gateway connection:
+
+```ts
+discordChannel({
+  name: "server-discord",
+  mode: "bot",
+  secrets: ["DISCORD_BOT_TOKEN"],
+});
+```
+
+Bot mode requires Message Content Intent in the Discord Developer Portal and channel permissions for `View Channel`, `Read Message History`, and `Send Messages`. AgentKit must redact `DISCORD_BOT_TOKEN` anywhere delivery, queue, buffer, or doctor output is returned.
+
 ## Verification
 
 ```sh
-bun test packages/agentkit/src/runtime/channels/adapters.test.ts
-bun test packages/agentkit/src/runtime/transcription.test.ts
-bun test packages/agentkit/src/runtime/deploy.test.ts
-npm run typecheck
+npm run agentkit -- inspect
+npm run agentkit -- deploy doctor
+npm run agentkit -- channels status <name>
+npm run agentkit -- channels doctor <name>
+```
+
+For a synthetic channel smoke after deploy:
+
+```sh
+npm run agentkit -- channels test <name> --message "hello"
+npm run agentkit -- channels deliveries list <name> --since 1h
 ```
 
 ## Troubleshooting
 
 Secret value appears in output:
-Stop and add a regression test before changing behavior. Delivery APIs must never return secret values.
+Stop and remove the value from source, fixtures, prompts, evals, and delivery notes. Hosted delivery APIs must not return secret values.
 
 Phone number appears in delivery logs:
-Redact it to a stable partial form such as `5511******9999`.
+Use the redacted delivery metadata and avoid pasting full phone numbers into committed fixtures.
+
+`channel_secret_missing`:
+Set the named hosted secret with `agentkit secret set <NAME> --from-local-env` or `agentkit secret sync --from-local`.
 
-Webhook accepts invalid signatures or origin headers:
-Fix `verifyWebhook` for the adapter before enabling provider setup docs.
+`channel_signature_invalid`:
+Check that the provider webhook secret/token configured in the provider dashboard matches the hosted secret name declared by the channel. For Discord slash-command mode, check that `DISCORD_PUBLIC_KEY` matches the application's public key. For Discord bot mode, check that `DISCORD_BOT_TOKEN` is set and Message Content Intent is enabled.
 
-Raw audio or transcript provider secret appears in output:
-Stop and add a regression test before changing behavior. Delivery APIs may include transcript text in normalized agent messages after successful transcription, but must never include raw bytes or provider secret values.
+Raw audio appears in files or logs:
+Remove it. AgentKit may pass transcript text into the normalized agent message after successful transcription, but raw audio belongs outside committed capsule files.

package/docs/guides/connect-discord.md

@@ -0,0 +1,178 @@
+# Connect Discord
+
+## Goal
+
+Connect Discord to a hosted AgentKit channel. Discord has two supported modes:
+
+- `interactions`: slash commands through Discord's Interactions Endpoint URL.
+- `bot`: normal server messages through a Discord Bot user connected to the Gateway.
+
+Use `bot` mode when the agent should answer messages without a slash command.
+
+## Commands
+
+Slash-command mode:
+
+```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
+```
+
+Bot/server-message mode:
+
+```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
+```
+
+## Minimal Config
+
+Slash commands:
+
+```ts
+discordChannel({ name: "support-discord" })
+```
+
+Normal server messages:
+
+```ts
+discordChannel({
+  name: "server-discord",
+  mode: "bot",
+})
+```
+
+Full example:
+
+```ts
+import { defineAgent, discordChannel } from "@andreprado/agentkit";
+
+export default defineAgent({
+  name: "support-agent",
+  runtime: "edge",
+  provider: { name: "test", model: "fake" },
+  instructions: "./prompts/instructions.md",
+  secrets: [],
+  tools: [],
+  channels: [
+    discordChannel({
+      name: "server-discord",
+      mode: "bot",
+      buffer: {
+        mode: "debounce",
+        quietWindowMs: 1500,
+        maxWaitMs: 8000,
+        maxMessages: 20,
+        maxChars: 8000,
+      },
+    }),
+  ],
+  access: { mode: "public" },
+  storage: { driver: "agentkit" },
+});
+```
+
+Discord audio transcription is not supported in V1. Do not add `audio` to a Discord channel.
+
+## Slash Command Setup
+
+Use this when users should run `/ask message:<text>`.
+
+Required secret:
+
+```txt
+DISCORD_PUBLIC_KEY
+```
+
+`agentkit channels connect discord support-discord` creates or refreshes the hosted channel, validates the public key, runs an AgentKit synthetic smoke, and prints the human setup step.
+
+Expected webhook URL:
+
+```txt
+https://<deploy-host>/channels/support-discord/discord/discord/webhook
+```
+
+In the Discord Developer Portal:
+
+1. Open the application.
+2. Copy the application's public key into the hosted secret named `DISCORD_PUBLIC_KEY`.
+3. Paste the AgentKit webhook URL into `Interactions Endpoint URL`.
+4. Register a slash command with a string option named `message`, `text`, `prompt`, `question`, `query`, or `input`.
+
+AgentKit answers Discord's `PING` handshake with `{ "type": 1 }`. Normal command webhooks are acknowledged with a deferred response and the retryable channel worker sends the final answer as an interaction follow-up.
+
+## Bot Setup
+
+Use this when the agent should behave like a server member and answer normal messages.
+
+Required secret:
+
+```txt
+DISCORD_BOT_TOKEN
+```
+
+`agentkit channels connect discord server-discord --mode bot` creates or refreshes the hosted channel, validates the bot token secret is present, runs an AgentKit synthetic Gateway smoke, and prints the human setup step.
+
+In the Discord Developer Portal:
+
+1. Create or open the Discord application.
+2. Open the Bot page.
+3. Reset/copy the bot token and save it as hosted secret `DISCORD_BOT_TOKEN`.
+4. Enable Message Content Intent on the Bot page.
+5. Install the app into the server with bot permissions.
+6. Grant the bot `View Channel`, `Read Message History`, and `Send Messages` in the channels it should answer.
+
+Hosted AgentKit runs a Discord Gateway worker for bot-mode channels. Discord sends `MESSAGE_CREATE` events, AgentKit ignores messages authored by bots, maps each human message to a channel conversation, runs the agent, and replies in the same Discord channel with `allowed_mentions: { parse: [] }`.
+
+For server hygiene, install or grant the bot only in channels where it should answer. Bot mode processes every readable non-bot text message the Gateway sends for that bot.
+
+## Safety Rules
+
+- Keep `DISCORD_PUBLIC_KEY` and `DISCORD_BOT_TOKEN` as managed hosted secrets; do not put values in prompts, fixtures, or source files.
+- Discord interaction tokens and bot tokens must never appear in delivery, queue, buffer, or doctor API responses.
+- Slash-command validation uses `X-Signature-Ed25519` and `X-Signature-Timestamp` against the exact raw request body.
+- Bot mode requires Discord Message Content Intent; without it, Discord sends empty message content and AgentKit skips the event.
+- Outbound Discord sends use `allowed_mentions: { parse: [] }` so agent text cannot accidentally ping users or roles.
+- Only set `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` in tests when Discord should not receive a real reply. Dry-run deliveries are recorded as `adapter_stubbed`.
+
+## Verification
+
+```sh
+agentkit channels status server-discord
+agentkit channels test server-discord --message "hello"
+agentkit channels deliveries list server-discord
+agentkit channels deliveries show <delivery-id>
+agentkit channels buffers list server-discord
+```
+
+Expected bot-mode flow:
+
+1. A user sends a normal message in a Discord server channel where the bot has access.
+2. Discord sends `MESSAGE_CREATE` over the Gateway.
+3. AgentKit records an inbound delivery and enqueues the channel job.
+4. The channel queue runs the agent.
+5. AgentKit sends a bot message through `/channels/<channel_id>/messages`.
+6. Delivery status becomes `provider_sent` for a real provider send or `adapter_stubbed` in dry-run mode.
+
+## Troubleshooting
+
+`channel_secret_missing`:
+Set `DISCORD_PUBLIC_KEY` for slash-command mode or `DISCORD_BOT_TOKEN` for bot mode as a hosted managed secret.
+
+Bot does not answer normal messages:
+Confirm the channel was created with `--mode bot`, `DISCORD_BOT_TOKEN` is set, Message Content Intent is enabled in the Discord Developer Portal, and the bot has channel permissions to view, read history, and send messages.
+
+Bot answers nothing and delivery events show empty content:
+Discord Message Content Intent is missing, disabled, or not approved for the application.
+
+Discord Developer Portal rejects the slash-command endpoint:
+Confirm the deployed interaction channel is online, `DISCORD_PUBLIC_KEY` matches the application's public key, and the endpoint returns `{ "type": 1 }` for Discord's signed `PING` request.
+
+No answer appears after a queued delivery:
+Run `agentkit channels deliveries list <name>`, inspect the inbound delivery, and drain/check the channel queue.

package/docs/guides/create-agent.md

@@ -39,6 +39,19 @@ cd support-demo
 npm run agentkit -- tool lookup_order --input '{"orderId":"A100"}'
 ```
 
+## Windows PowerShell
+
+If PowerShell blocks `npm.ps1` or `npx.ps1` with `PSSecurityException`, run the same commands through the Windows command shims:
+
+```sh
+npx.cmd @andreprado/agentkit@alpha new demo --template blank
+npm.cmd run typecheck
+npm.cmd run chat -- --message "hello"
+npm.cmd run agentkit -- inspect
+```
+
+This keeps the capsule workflow the same without changing the machine-wide PowerShell execution policy.
+
 ## Files Created Or Edited
 
 Generated files: