@andreprado/agentkit 0.1.0-alpha.8 → 0.1.0

package/README.md

@@ -24,12 +24,15 @@ Generated capsules use the built-in `test/fake` provider by default, so the firs
 ## What To Know First
 
 ```sh
-agentkit new <name> [--template blank|support|dentista] [--no-install]
+agentkit new [name] [--template blank|support|dentista] [--no-install]
+agentkit new .
 agentkit dev
 agentkit chat --message <text> [--conversation-id <id>]
 agentkit inspect
 ```
 
+Run `agentkit new` without a name in an interactive terminal to be prompted for the project folder. Use `agentkit new .` to create the capsule in the current directory.
+
 Once the capsule is running:
 
 ```sh
@@ -37,29 +40,43 @@ agentkit tool <name> [--input <path-or-json>]
 agentkit knowledge add <path-or-url>
 agentkit knowledge sync
 agentkit knowledge search <query> [--top-k <number>]
+agentkit integrations status
+agentkit integrations connect composio --toolkit gmail
 agentkit spec init --brief <text>
 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>
 ```
 
 Knowledge indexes local `.md`, `.txt`, and `.csv` sources into the capsule database and registers the internal `agentkit_search_knowledge` chat tool when `knowledge` is configured in `agentkit.config.ts`. `agentkit dev` and `agentkit chat` sync configured sources automatically; when embeddings are configured, local semantic search uses a libSQL vector sidecar. Hosted Cloudflare deploys package configured local Knowledge sources and sync them into the project Turso database automatically during `agentkit deploy`; when embeddings are configured, the deploy also creates and populates the hosted Turso vector index.
 
+Every chat run receives dynamic runtime date context: current ISO timestamp, local date, weekday, local date/time, and timezone. Set `timeZone` in `agentkit.config.ts` for scheduling agents so relative dates like "today" and "next Friday" resolve in the right business/user timezone.
+
+AgentKit-managed Composio is a paid hosted integration layer for per-agent connected apps. Configure it with `composioManaged({...})`, deploy with a `managed_composio` entitlement, then use `agentkit integrations connect composio --toolkit <slug>` to create hosted Connect Links. BYO Composio remains available through normal `defineTool` wrappers.
+
 ## Deploy Later
 
 ```sh
 agentkit login --token <token>
 agentkit deploy doctor
+agentkit skills status
 agentkit secret set OPENAI_API_KEY --from-local-env
 agentkit deploy
 agentkit deploy status
+agentkit channels test support-telegram --message "hello"
+agentkit channels connect webhook n8n-webhook
+agentkit transcribe smoke --provider groq
 agentkit chat-ui --deploy
 ```
 
 Production secrets are managed secrets, not committed `.env` values.
+After upgrading AgentKit in an existing capsule, run `agentkit skills status` and `agentkit skills sync` if local agent-facing skills are stale.
 Private hosted deploys automatically store a local chat/UI deploy access token at `.agentkit/chat-access-token.json`. `agentkit chat-ui --deploy` serves a local UI pointed at the hosted deploy without exposing that token to browser code.
 
 The npm package contains the public CLI/runtime/client surface only. AgentKit Cloud's control-plane server, operator commands, Postgres store, and Cloudflare/Turso/R2 publisher live in the private repo workspace and are not part of the published package.

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, Discord, Slack, or a generic webhook through AgentKit-owned channel infrastructure, or when an inbound channel should reply through another configured channel.
 
 ## Commands
 
@@ -16,26 +16,35 @@ agentkit deploy
 agentkit channels list
 agentkit channels add website website-chat
 agentkit channels add telegram support-telegram
+agentkit channels connect discord support-discord
+agentkit channels connect discord server-discord --mode bot
+agentkit channels connect slack support-slack
+agentkit channels connect webhook n8n-webhook
 agentkit channels add whatsapp support-whatsapp --provider zapster
+agentkit channels connect whatsapp support-uazapi --provider uazapi
+agentkit channels connect whatsapp main-whatsapp --provider evolution
 agentkit channels setup support-telegram
 agentkit channels status support-telegram
 agentkit channels test support-telegram --message "hello"
 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`, `discordChannel`, `slackChannel`, `webhookChannel`, or `webhookOutputChannel`.
 - `.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`.
+- Generic inbound webhook clients must send `AGENTKIT_WEBHOOK_SECRET` as `Authorization: Bearer <token>`, `X-AgentKit-Webhook-Secret`, or `X-AgentKit-Webhook-Signature: sha256=<hmac>`.
+- Generic outbound webhook channels send replies to an HTTPS URL stored in a managed secret such as `CRM_CALLBACK_URL`.
 
 ## Minimal Working Example
 
 ```ts
-import { defineAgent, telegramChannel, whatsappChannel, websiteChannel } from "@andreprado/agentkit";
+import { defineAgent, discordChannel, slackChannel, telegramChannel, webhookChannel, webhookOutputChannel, whatsappChannel, websiteChannel } from "@andreprado/agentkit";
 
 export default defineAgent({
   name: "support-agent",
@@ -48,6 +57,13 @@ export default defineAgent({
     websiteChannel({ name: "website-chat" }),
     telegramChannel({ name: "support-telegram" }),
     whatsappChannel({ name: "support-whatsapp", provider: "zapster" }),
+    whatsappChannel({ name: "support-uazapi", provider: "uazapi" }),
+    whatsappChannel({ name: "main-whatsapp", provider: "evolution" }),
+    discordChannel({ name: "support-discord" }),
+    discordChannel({ name: "server-discord", mode: "bot" }),
+    slackChannel({ name: "support-slack" }),
+    webhookChannel({ name: "n8n-webhook" }),
+    webhookOutputChannel({ name: "crm-callback", urlSecret: "CRM_CALLBACK_URL" }),
   ],
   access: { mode: "public" },
   storage: { driver: "agentkit" },
@@ -76,6 +92,222 @@ Buffering is scoped to one channel conversation. AgentKit still validates and de
 
 Use `buffer: { mode: "off" }` or omit `buffer` to process each inbound message as its own agent run.
 
+Buffer controls:
+
+```sh
+agentkit channels buffers list support-whatsapp
+agentkit channels buffers show support-whatsapp <conversation-id>
+agentkit channels buffers flush support-whatsapp <conversation-id>
+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.
+
+## Generic Webhooks
+
+Use `webhookChannel` when n8n, Make, Zapier, Pipedream, or a custom server should push a text event into the agent.
+
+```ts
+webhookChannel({
+  name: "n8n-webhook",
+})
+```
+
+After deploy:
+
+```sh
+agentkit channels connect webhook n8n-webhook
+```
+
+The hosted webhook URL is:
+
+```txt
+https://<deploy-host>/channels/n8n-webhook/webhook
+```
+
+Send canonical JSON:
+
+```json
+{
+  "event_id": "evt_123",
+  "external_id": "customer_123",
+  "message": "hello from n8n"
+}
+```
+
+`event_id` is required for replay protection. `external_id` is optional but recommended; AgentKit hashes it before storing the channel identity and uses it to continue the same conversation. If `external_id` is omitted, the event id becomes the conversation identity and each event is treated as its own conversation.
+
+Authenticate with a shared secret:
+
+```sh
+curl -X POST https://<deploy-host>/channels/n8n-webhook/webhook \
+  -H 'content-type: application/json' \
+  -H 'authorization: Bearer <AGENTKIT_WEBHOOK_SECRET>' \
+  -d '{"event_id":"evt_123","external_id":"customer_123","message":"hello from n8n"}'
+```
+
+For HMAC auth, compute `HMAC-SHA256(raw JSON body, AGENTKIT_WEBHOOK_SECRET)` and send:
+
+```txt
+X-AgentKit-Webhook-Signature: sha256=<hex digest>
+```
+
+Without `replyTo`, generic webhooks are inbound-only: the agent run is queued and delivery logs show the result, but AgentKit does not call back into the source system.
+
+## Reply Through Another Channel
+
+Use `replyTo` when an inbound channel should receive on one transport and answer on another. The source channel still owns webhook validation, dedupe, and queueing; the target channel owns the outbound provider call.
+
+Receive from a generic webhook and answer on WhatsApp:
+
+```ts
+webhookChannel({
+  name: "lead-webhook",
+  replyTo: {
+    channel: "main-whatsapp",
+    recipientFrom: "phone",
+  },
+})
+
+whatsappChannel({
+  name: "main-whatsapp",
+  provider: "evolution",
+})
+```
+
+The inbound webhook payload must include the configured recipient field:
+
+```json
+{
+  "event_id": "evt_124",
+  "external_id": "lead_123",
+  "phone": "+15551234567",
+  "message": "please follow up"
+}
+```
+
+`recipientFrom` is a dotted JSON path such as `phone`, `customer.phone`, or `payload.customer.phone`. AgentKit reads it from the raw inbound payload, requires a non-empty scalar value, and formats it for the target channel. Do not use `recipientFrom` for Discord or Slack replies; those require provider-native source identities from their own inbound events.
+
+You can declare multiple webhook inputs by giving each `webhookChannel` a unique name:
+
+```ts
+webhookChannel({ name: "n8n-webhook" })
+webhookChannel({ name: "make-webhook" })
+webhookChannel({ name: "crm-webhook", replyTo: { channel: "main-whatsapp", recipientFrom: "phone" } })
+```
+
+## Generic Output Webhooks
+
+Use `webhookOutputChannel` when the agent should send the final answer to a generic callback URL, such as an internal CRM, n8n callback, Make webhook, or a custom API endpoint.
+
+```ts
+webhookOutputChannel({
+  name: "crm-callback",
+  urlSecret: "CRM_CALLBACK_URL",
+  auth: {
+    type: "bearer",
+    tokenSecret: "CRM_CALLBACK_TOKEN",
+  },
+})
+
+webhookChannel({
+  name: "n8n-webhook",
+  replyTo: {
+    channel: "crm-callback",
+    recipientFrom: "crm_id",
+  },
+})
+```
+
+Set `CRM_CALLBACK_URL` as a managed secret. It must be a public HTTPS URL; AgentKit rejects localhost, private network, link-local, and metadata-service hosts before sending. Supported output auth modes are `none`, `bearer`, `header`, and `hmac`, and all auth values come from managed secrets.
+
+Outbound generic webhook requests contain the agent's final text answer:
+
+```json
+{
+  "event_id": "webhook:generic:crm-callback:<conversation-id>",
+  "conversation_id": "<conversation-id>",
+  "channel_id": "crm-callback",
+  "external_identity": "webhook:generic:recipient:acct_123",
+  "message": {
+    "role": "assistant",
+    "content_type": "text",
+    "content": "Thanks, I can help with that."
+  }
+}
+```
+
+Generic output channels do not have public inbound webhook URLs. `agentkit channels test <output-name>` is unsupported because there is no inbound endpoint to smoke.
+
+## Auto Transcribe Audio
+
+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({
+  name: "support-agent",
+  runtime: "edge",
+  provider: { name: "openai", model: "gpt-5.4-mini" },
+  instructions: "./prompts/instructions.md",
+  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" },
+    }),
+    whatsappChannel({
+      name: "support-whatsapp",
+      provider: "zapster",
+      audio: { mode: "transcribe" },
+    }),
+    whatsappChannel({
+      name: "support-uazapi",
+      provider: "uazapi",
+      audio: { mode: "transcribe" },
+    }),
+    whatsappChannel({
+      name: "main-whatsapp",
+      provider: "evolution",
+      audio: { mode: "transcribe" },
+    }),
+  ],
+  access: { mode: "public" },
+  storage: { driver: "agentkit" },
+});
+```
+
+Supported transcription providers in V1:
+
+| Provider | Default secret | Supported models |
+| --- | --- | --- |
+| `openai` | `OPENAI_API_KEY` | `gpt-4o-mini-transcribe`, `gpt-4o-transcribe`, `whisper-1` |
+| `groq` | `GROQ_API_KEY` | `whisper-large-v3-turbo`, `whisper-large-v3`, `distil-whisper-large-v3-en` |
+
+Audio transcription is paid by the capsule owner because AgentKit only passes through the configured provider secret. Hosted channel creation automatically requires the transcription secret when a channel enables `audio.mode: "transcribe"`.
+
+Processing order:
+
+1. Provider webhook is validated and deduped.
+2. Channel adapter normalizes the audio metadata.
+3. AgentKit records `audio_received` and enqueues a channel job before acknowledging the webhook.
+4. The retryable channel worker downloads the audio using the channel provider secret.
+5. The transcription adapter sends the file to the configured transcription provider.
+6. The agent receives a text message containing the transcript.
+
+Zapster audio downloads from trusted HTTPS Zapster media URLs. UAZAPI audio downloads through UAZAPI `/message/download` with base64 return enabled. Evolution audio downloads through Evolution API `/chat/getBase64FromMediaMessage/{instance}` with base64 return enabled. AgentKit does not fetch arbitrary UAZAPI or Evolution webhook media hosts.
+
+V1 keeps the raw audio in memory for the request path and delivery metadata only records redacted status/error fields. `rawAudioTtlSeconds` is part of the manifest contract for future object-storage retention, but V1 does not persist raw audio by default.
+
 ## Safety Rules
 
 - Never put provider token values in `agentkit.config.ts`.
@@ -83,6 +315,7 @@ Use `buffer: { mode: "off" }` or omit `buffer` to process each inbound message a
 - Treat channel webhook URLs as public transport endpoints. Provider validation or the AgentKit website channel token controls authenticity.
 - Keep channels separate from tools. Channels deliver user messages; tools let the agent call external systems.
 - Keep `maxMessages` and `maxChars` bounded so one burst cannot create an oversized prompt or unexpected model spend.
+- Keep `audio.limits` bounded so one voice note cannot create unexpected transcription spend.
 
 ## Verification
 
@@ -91,11 +324,16 @@ npm run typecheck
 bun test
 agentkit inspect
 agentkit channels list
+agentkit channels test n8n-webhook --message "hello"
 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
+agentkit channels buffers list support-telegram
 ```
 
 Expected hosted status includes `NAME`, `TYPE`, `PROVIDER`, `STATUS`, and `LAST_EVENT`. Secret output is name plus `set` or `missing`, never the value.
+Outbound provider success is `provider_sent`. `adapter_stubbed` means no outbound provider call was made, either because explicit dry-run mode is enabled or the channel is inbound-only.
 
 ## Troubleshooting
 
@@ -106,9 +344,15 @@ 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 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`.
+
+`transcription_audio_format_unsupported`:
+The channel delivered an audio format the configured transcription provider does not accept. Telegram voice notes are OGG/Opus and work with Groq in V1; OpenAI accepts MP3, MP4, MPEG, MPGA, M4A, WAV, and WEBM in the AgentKit adapter.
 
 Buffered messages stay in `buffered` delivery state until the quiet window or max wait flushes them into one queued run.

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

@@ -0,0 +1,165 @@
+# Add Managed Composio
+
+## Goal
+
+Enable AgentKit-managed Composio for one deployed agent so the agent can use explicitly allowed external app actions without the user owning Composio credentials.
+
+Use BYO `defineTool` wrappers instead when the user wants to use their own Composio account/API key for free.
+
+## Contract
+
+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.
+
+## Minimal Config
+
+Edit `agentkit.config.ts`:
+
+```ts
+import { composioManaged, defineAgent } from "@andreprado/agentkit";
+
+export default defineAgent({
+  name: "acme-receptionist",
+  runtime: "edge",
+  provider: {
+    name: "test",
+    model: "fake",
+  },
+  instructions: "./prompts/instructions.md",
+  secrets: [],
+  tools: [],
+  integrations: [
+    composioManaged({
+      toolkits: ["gmail", "googlecalendar"],
+      tools: {
+        gmail: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"],
+        googlecalendar: [
+          "GOOGLECALENDAR_EVENTS_LIST",
+          "GOOGLECALENDAR_CREATE_EVENT",
+          "GOOGLECALENDAR_UPDATE_EVENT",
+        ],
+      },
+      confirmExternalWrites: true,
+    }),
+  ],
+  access: {
+    mode: "private",
+  },
+  storage: {
+    driver: "agentkit",
+    database: {
+      driver: "turso",
+    },
+  },
+});
+```
+
+## Deploy
+
+```sh
+agentkit login --token agk_user_...
+agentkit deploy doctor
+agentkit deploy
+agentkit integrations status --toolkit googlecalendar
+```
+
+Expected readiness:
+
+- 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
+
+The Composio connect link is deploy-scoped, so declare `composioManaged(...)` first, deploy, then connect. After deploy, create a hosted Composio Connect Link:
+
+```sh
+agentkit integrations connect composio --toolkit gmail
+agentkit integrations connect composio --toolkit googlecalendar
+```
+
+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.
+
+`agentkit deploy` prints the recommended `integrations connect composio --toolkit <slug>` command for each configured toolkit in its production handoff.
+
+## Calendar Defaults
+
+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.
+
+Use these starter actions:
+
+```ts
+googlecalendar: [
+  "GOOGLECALENDAR_EVENTS_LIST",
+  "GOOGLECALENDAR_CREATE_EVENT",
+  "GOOGLECALENDAR_UPDATE_EVENT",
+]
+```
+
+`GOOGLECALENDAR_CREATE_EVENT` requires extra care:
+
+- `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
+
+Managed Composio requires operator invocation for external write actions. If an integration allows create, update, delete, send, patch, move, insert, clear, remove, import, or quick-add actions, AgentKit blocks that generated tool during model-driven chat, channel, and eval runs. Review the exact action and invoke `agentkit_composio_execute` directly with `agentkit tool`; write actions also require `confirmed: true` by default.
+
+`confirmExternalWrites: false` disables only Composio's secondary `confirmed` input check. It does not bypass AgentKit's operator-only permission boundary:
+
+```ts
+composioManaged({
+  toolkits: ["googlecalendar"],
+  tools: {
+    googlecalendar: ["GOOGLECALENDAR_EVENTS_LIST", "GOOGLECALENDAR_CREATE_EVENT"],
+  },
+  confirmExternalWrites: false,
+})
+```
+
+## Verification
+
+```sh
+agentkit inspect
+agentkit build --target cloudflare
+agentkit deploy doctor
+agentkit integrations status --toolkit googlecalendar
+```
+
+Expected:
+
+- `inspect.integrations[0].provider` is `composio`.
+- `inspect.tools` includes `agentkit_composio_execute` when allowed actions are configured.
+- 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
+
+`managed_composio_entitlement_required`:
+
+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 configured in AgentKit Cloud yet. Report the exact error code and toolkit slug to the AgentKit owner.
+
+`managed_composio_not_configured`:
+
+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`:
+
+The deploy has multiple configured toolkits. Re-run connect with `--toolkit <slug>`.

package/docs/guides/add-tool.md

@@ -8,6 +8,8 @@ Add a TypeScript tool to an Agent Capsule, register it in `agentkit.config.ts`,
 
 Use this when the agent needs to call code, read an API, query a database, or perform a small action behind a typed contract.
 
+For requests such as “use Jev to qualify leads” or “use TypeSafe to rank candidates,” follow [Use Jev](use-jev.md) and adapt the bundled tool example to the requested behavior.
+
 ## Commands
 
 From a capsule root:
@@ -112,6 +114,8 @@ Direct tool test:
 npm run agentkit -- tool lookup_order --input '{"orderId":"A100"}'
 ```
 
+When the tool touches live data, writes externally, or enforces business rules, also add deterministic checks. Use fixtures, eval-safe branches, seed data, or direct tool inputs for success and failure paths such as missing confirmation, validation errors, provider 429s/timeouts, unavailable records, and privacy/no-leak behavior. Add an eval when the agent should call the tool with specific inputs or refuse to call it until required intake or confirmation is complete.
+
 Expected output:
 
 ```json
@@ -129,9 +133,10 @@ Use this when a tool needs agent-owned tables and must work locally and after de
 
 Recommended contract:
 
-- Put all agent-owned tables in `schema.sql`.
+- Put the idempotent bootstrap view of agent-owned tables in `schema.sql`.
+- For production-shaped schema evolution, add ordered `migrations/*.sql` files such as `migrations/0001_clients.sql`.
 - Keep deploy-ready capsules on `storage.driver: "agentkit"`.
-- Local `agentkit chat`, `agentkit tool`, `agentkit dev`, and eval runs apply `schema.sql` to local development storage.
+- Local `agentkit chat`, `agentkit tool`, `agentkit dev`, and eval runs apply ordered local migrations before `schema.sql`.
 - Use `agentkit db migrate`, `agentkit db reset --yes`, `agentkit db seed [--file seed.sql]`, and `agentkit db shell` for local database setup and inspection.
 - Hosted deploy migrates/provisions the managed database internally and applies the same `schema.sql`.
 - Tools use `ctx.db` as the canonical helper. `ctx.database` and `ctx.storage.sql` are supported aliases.
@@ -176,7 +181,7 @@ CREATE TABLE IF NOT EXISTS appointments (
 );
 ```
 
-`schema.sql` is an idempotent bootstrap file in v1. Prefer `CREATE TABLE IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`, and safe additive `ALTER TABLE` statements. AgentKit does not run destructive schema changes or ordered `migrations/*.sql` automatically yet.
+`schema.sql` is an idempotent bootstrap file. Prefer `CREATE TABLE IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`, and safe additive `ALTER TABLE` statements. Use ordered `migrations/*.sql` for production-shaped schema evolution; `agentkit db migrate` applies unapplied local migrations before `schema.sql`.
 
 `tools/schedule-appointment.ts`:
 
@@ -262,6 +267,8 @@ Use it for diagnostics only, not for bypassing AgentKit runtime services or choo
 - Do not read arbitrary `process.env` inside tools.
 - Use `ctx.secrets.SECRET_NAME`.
 - Set `timeoutMs` for slow external calls.
+- End read-only permissions with `:read`, for example `crm:contacts:read`.
+- Declare writes, sends, deletes, payments, or broad external calls with a non-read permission such as `email:send`. AgentKit blocks those permissions during model-driven chat, channel, and eval runs; the local operator must review and invoke the exact call with `agentkit tool`.
 - Set `visibility: "internal"` for operational outputs such as classifications, scores, routing labels, fraud decisions, or other fields the agent should persist but not reveal literally to the user.
 - Do not log secret values.