@andreprado/agentkit 0.1.0-alpha.18 → 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"
@@ -28,7 +30,7 @@ Use `--api <url>` only when the owner gives you a non-default AgentKit Cloud API
 
 ## 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 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`.
@@ -36,7 +38,7 @@ Use `--api <url>` only when the owner gives you a non-default AgentKit Cloud API
 ## 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.
@@ -71,9 +72,10 @@ 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
 
@@ -150,7 +152,7 @@ Log in with a paid AgentKit Cloud account that has `managed_composio`.
 
 `managed_composio_auth_config_missing`:
 
-The AgentKit Cloud account is entitled, but the requested toolkit is not available for managed Composio yet. Report the exact error code and toolkit slug to the AgentKit owner.
+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`:
 

package/docs/guides/channel-security.md

@@ -2,7 +2,7 @@
 
 ## Goal
 
-Configure website, Telegram, and WhatsApp channels without leaking secrets, storing raw provider payloads, or treating public webhook URLs as authorization.
+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
 
@@ -31,6 +31,7 @@ agentkit channels deliveries show <delivery-id>
 - 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`.
@@ -76,6 +77,29 @@ 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
@@ -104,7 +128,7 @@ Use the redacted delivery metadata and avoid pasting full phone numbers into com
 Set the named hosted secret with `agentkit secret set <NAME> --from-local-env` or `agentkit secret sync --from-local`.
 
 `channel_signature_invalid`:
-Check that the provider webhook secret/token configured in the provider dashboard matches the hosted secret name declared by the channel.
+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 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:

package/docs/guides/debug-channel.md

@@ -2,7 +2,7 @@
 
 ## Goal
 
-Diagnose website, Telegram, or WhatsApp channel setup, webhook validation, dedupe, buffering, outbound sends, and delivery failures from the Agent Capsule CLI.
+Diagnose website, Telegram, WhatsApp, or Discord channel setup, webhook validation, dedupe, buffering, outbound sends, and delivery failures from the Agent Capsule CLI.
 
 ## When To Use It
 
@@ -87,11 +87,17 @@ The channel was disabled. Re-add or recreate it.
 The hosted secret metadata says a required channel secret is missing. Set it with `agentkit secret set <NAME> --from-local-env` or `agentkit secret sync --from-local`.
 
 `channel_signature_invalid`:
-Provider authenticity validation failed. Check the provider webhook secret, token, or origin settings.
+Provider authenticity validation failed. Check the provider webhook secret, token, origin settings, or Discord public key.
 
 `channel_payload_invalid`:
 The provider payload is malformed or does not match the route provider.
 
+Discord endpoint validation fails in the Developer Portal:
+Confirm `DISCORD_PUBLIC_KEY` is set from the application's public key and the webhook URL is `/channels/<name>/discord/discord/webhook`. AgentKit must validate Discord's signature headers before returning the `PING` PONG.
+
+Discord bot does not answer normal server messages:
+Confirm the channel was created with `--mode bot`, `DISCORD_BOT_TOKEN` is set, Message Content Intent is enabled in the Discord Developer Portal, the app is installed into the server, and the bot has `View Channel`, `Read Message History`, and `Send Messages` permissions for the channel.
+
 `audio_received`:
 The webhook contained a supported audio message and the channel is entering the audio handling path.
 

package/docs/guides/improve-from-production.md

@@ -0,0 +1,151 @@
+# Improve From Production
+
+## Goal
+
+Pull hosted or local conversation evidence into the Agent Capsule, turn it into regression evals, let the local coding agent patch the capsule, and replay before deploying again.
+
+## When To Use This
+
+Use this when a deployed agent gave a wrong answer, failed a tool call, mishandled a channel message, or needs production behavior converted into eval coverage.
+
+AgentKit Cloud only exports redacted evidence. The local coding agent owns source edits, evals, replay, and deploy.
+
+## Commands
+
+Collect evidence from the last hosted deploy:
+
+```sh
+agentkit improve collect --deploy --since 24h
+```
+
+When the CLI is logged in to AgentKit Cloud, this command first asks the control plane for deploy evidence such as failed channel deliveries, deploy errors, and conversation IDs that need review. It then reads replayable hosted conversation traces from the deployed runtime with the deploy access token. If Cloud auth is not available, it still collects hosted conversations directly from the deploy URL.
+
+Hosted conversation reads require a deploy access token even when the chat endpoint is public. `agentkit deploy` normally writes `.agentkit/chat-access-token.json`; refresh it with:
+
+```sh
+agentkit access token create agentkit-chat-ui --out .agentkit/chat-access-token.json
+```
+
+Collect one hosted conversation:
+
+```sh
+agentkit improve collect --deploy --conversation-id <conversation-id>
+```
+
+Collect local conversations instead:
+
+```sh
+agentkit improve collect --since 7d
+```
+
+Generate regression evals from the collected bundle:
+
+```sh
+agentkit improve evals .agentkit/improve/<run>
+```
+
+Replay the bundle against the local capsule:
+
+```sh
+agentkit replay .agentkit/improve/<run> --against local
+```
+
+## Files Created Or Edited
+
+Evidence bundle, ignored local state:
+
+```txt
+.agentkit/improve/<run>/
+  bundle.json
+  report.json
+  traces/
+```
+
+Generated regression evals, committed source:
+
+```txt
+evals/regressions/
+  improve-<conversation>.eval.ts
+```
+
+The local coding agent may then edit:
+
+```txt
+prompts/instructions.md
+agentkit.config.ts
+tools/
+knowledge/
+evals/
+```
+
+Do not edit `.agentkit/improve/<run>/bundle.json` by hand.
+
+## Workflow
+
+```sh
+agentkit improve collect --deploy --since 24h
+agentkit improve evals .agentkit/improve/<run>
+agentkit replay .agentkit/improve/<run> --against local
+```
+
+Then let the local coding agent inspect `report.json`, the generated eval files, prompts, tools, and Knowledge sources. After edits:
+
+```sh
+npm run typecheck
+npm run agentkit -- inspect
+npm run eval
+agentkit replay .agentkit/improve/<run> --against local
+agentkit deploy --smoke "hello"
+```
+
+## Safety Rules
+
+- Do not paste secrets into evals, prompts, Knowledge files, or reports.
+- Keep `.agentkit/improve/` out of commits.
+- Review generated eval assertions before committing them. AgentKit redacts common email, phone, bearer token, and key patterns in generated eval text, but the local coding agent must still remove or generalize domain-specific client PII.
+- For write, delete, payment, email, or customer-system tools, branch inside the tool on `ctx.runtime.environment === "eval"` and return deterministic non-destructive output.
+- Treat hosted traces as customer evidence.
+- If replay uses a real provider instead of `test/fake`, tell the owner because it may cost money and may be nondeterministic.
+
+## Verification
+
+```sh
+npm run typecheck
+npm run agentkit -- inspect
+npm run eval
+agentkit replay .agentkit/improve/<run> --against local
+```
+
+Expected:
+
+- `improve collect` writes a bundle and report under `.agentkit/improve/`.
+- Hosted collection includes a redacted `evidence` summary in `bundle.json` and `report.json` when AgentKit Cloud evidence export is available.
+- `improve evals` writes eval files under `evals/regressions/`.
+- `replay` reports passed, failed, and skipped traces.
+- No production secret values appear in generated files.
+
+## Troubleshooting
+
+`No .agentkit/deploy.json found`:
+
+Run `agentkit deploy` first, or collect local evidence without `--deploy`.
+
+`deploy_conversation_request_failed`:
+
+Refresh the deploy chat token with `agentkit access token create agentkit-chat-ui --out .agentkit/chat-access-token.json`, then retry.
+
+`improve_evidence_store_not_configured`:
+
+The Cloud API does not expose deploy evidence export yet. The CLI falls back to hosted conversation trace collection when possible.
+
+`conversation_access_not_configured`:
+
+The hosted runtime is not configured with a deploy access-token gate for conversation reads. Redeploy through AgentKit Cloud so the runtime gate is injected, or configure an explicit deploy/private token for local hosted testing.
+
+`trace has no user turns`:
+
+The trace cannot become a useful conversation eval. Keep the report for diagnosis, but do not commit an empty eval.
+
+Generated eval is too strict:
+
+Edit the eval to assert the important behavior, such as tool input, safety wording, or knowledge source usage, instead of exact prose.

package/docs/guides/prepare-deploy.md

@@ -25,7 +25,18 @@ npm run agentkit -- db migrate
 npm run chat -- --message "hello"
 ```
 
-All scaffold, local dev, chat, eval, inspect, database, and build commands are token-free. Hosted production deploy and hosted AgentKit Cloud changes require an invited AgentKit Cloud token:
+All scaffold, local dev, chat, eval, inspect, database, and build commands are token-free. Hosted production deploy and hosted AgentKit Cloud changes require an AgentKit Cloud account token with hosted deploy access.
+
+If the user does not have a token yet, start checkout from the CLI, finish Stripe Checkout in the browser, then claim the one-time checkout intent:
+
+```sh
+npm run agentkit -- billing checkout --slots 1 --email user@example.com
+npm run agentkit -- billing claim billint_... --secret bsec_...
+```
+
+The claim command stores the returned `agk_user_...` token in the local AgentKit Cloud auth file. Treat the `bsec_...` checkout secret like a password; it exists only to claim the first token after checkout.
+
+If the user already has a token:
 
 ```sh
 npm run agentkit -- login --token agk_user_...
@@ -42,7 +53,15 @@ OPENAI_API_KEY=sk-...
 ```
 
 `.env` is local-only. Hosted deploy secrets are handled by AgentKit outside the capsule.
-Closed-alpha hosted deploys require an invited account token with `cloudflare_deploy_alpha`.
+Hosted deploys require an account with either `cloudflare_deploy_alpha` or purchased/manual deploy slots. Deploy slots belong to the account, not to a specific token string.
+
+To generate or switch account tokens after login:
+
+```sh
+npm run agentkit -- account token create new-laptop --use
+npm run agentkit -- account token list
+npm run agentkit -- account token revoke apitok_...
+```
 
 ## What The Agent Should Edit
 
@@ -126,6 +145,7 @@ For a final end-to-end test, run:
 
 ```sh
 npm run agentkit -- login --token agk_user_...
+npm run agentkit -- account token list
 npm run agentkit -- secret sync --from-local
 npm run agentkit -- secret list
 npm run agentkit -- deploy --smoke "hello"
@@ -134,7 +154,7 @@ npm run agentkit -- chat-ui --deploy
 npm run agentkit -- access token list
 ```
 
-For private hosted deploys, `npm run agentkit -- deploy` writes the local chat/UI access token to `.agentkit/chat-access-token.json`. Use `npm run agentkit -- deploy --smoke "hello"` for the official hosted chat smoke, and use `npm run agentkit -- chat-ui --deploy` for hosted UI testing. The hosted Chat UI shows the conversation id, tool calls, tool errors, and a new-conversation control; use `npm run agentkit -- conversations trace <conversation-id> --deploy` to pull the hosted trace from the last deploy. Use `npm run agentkit -- access token create <name> --out <path>` only for additional clients.
+For hosted deploys, `npm run agentkit -- deploy` writes the local chat/UI access token to `.agentkit/chat-access-token.json`. Use `npm run agentkit -- deploy --smoke "hello"` for the official hosted chat smoke, and use `npm run agentkit -- chat-ui --deploy` for hosted UI testing. The hosted Chat UI shows the conversation id, tool calls, tool errors, and a new-conversation control; use `npm run agentkit -- conversations trace <conversation-id> --deploy` to pull the hosted trace from the last deploy. Use `npm run agentkit -- access token create <name> --out <path>` only for additional clients.
 
 When the UI is running, open the printed `Chat:` URL and tell the owner the exact URL. If the capsule is still on `test/fake`, say the UI was tested only with the deterministic fake provider.
 
@@ -147,7 +167,7 @@ All required secret names are declared
 Prompt path exists
 Tools have input schemas
 Dangerous tools have permissions
-Managed Composio toolkit auth configs are present when configured
+Managed Composio toolkit auth configs are available in AgentKit Cloud when configured
 Provider model is supported by AgentKit
 schema.sql is idempotent
 README/AGENTS/CLAUDE match the capsule
@@ -193,14 +213,15 @@ Before a hosted production deploy, run:
 npm run agentkit -- deploy doctor
 ```
 
-The doctor checks AgentKit Cloud login, Node version, alpha deploy entitlement, online deploy capacity, declared hosted secrets, local `.env` names that have not been uploaded with `npm run agentkit -- secret set`, and private-access runtime token handling. `agentkit deploy` runs the same readiness check automatically before building and uploading the artifact.
+The doctor checks AgentKit Cloud login, Node version, hosted deploy entitlement, online deploy capacity, declared hosted secrets, local `.env` names that have not been uploaded with `npm run agentkit -- secret set`, and private-access runtime token handling. `agentkit deploy` runs the same readiness check automatically before building and uploading the artifact.
 
-If the capsule configures `composioManaged({...})`, the doctor also checks the paid `managed_composio` entitlement. `COMPOSIO_API_KEY` is AgentKit-managed in this path; the user must not set it with `agentkit secret set`.
+If the capsule configures `composioManaged({...})`, the doctor also checks the paid `managed_composio` entitlement and AgentKit Cloud toolkit readiness. `COMPOSIO_API_KEY` and toolkit auth config resolution are AgentKit-managed in this path; the user must not set them with `agentkit secret set`.
 
 `alpha_access_required`:
 
-Log in with an invited alpha account:
+Log in with an account that has hosted deploy access. If the user needs to buy slots first:
 
 ```sh
-npm run agentkit -- login --token agk_user_...
+npm run agentkit -- billing checkout --slots 1 --email user@example.com
+npm run agentkit -- billing claim billint_... --secret bsec_...
 ```