@andreprado/agentkit 0.1.0-alpha.2 → 0.1.0-alpha.20

package/README.md

@@ -1,21 +1,82 @@
 # AgentKit
 
-AgentKit is a toolkit for creating, running, inspecting, and deploying Agent Capsules.
+AgentKit is a CLI-first toolkit for creating, running, inspecting, and deploying Agent Capsules.
+
+## Quick Start
 
 ```sh
 npx @andreprado/agentkit@alpha new support-agent --template support
 cd support-agent
-npm install
 npm run dev
+npm run chat -- --message "hello"
+```
+
+For a Portuguese dental-office starter, use:
+
+```sh
+npx @andreprado/agentkit@alpha new clara-dentista --template dentista
+```
+
+`agentkit new` installs the generated capsule dependencies by default so `agentkit.config.ts` resolves `@andreprado/agentkit` immediately in editors. Use `--no-install` only for offline or scripted scaffolds where you want to run `npm install` later.
+
+Generated capsules use the built-in `test/fake` provider by default, so the first local run works without provider keys.
+
+## What To Know First
+
+```sh
+agentkit new <name> [--template blank|support|dentista] [--no-install]
+agentkit dev
+agentkit chat --message <text> [--conversation-id <id>]
+agentkit inspect
 ```
 
-Local scaffolding, development, inspection, evals, and builds do not require an AgentKit Cloud token. Hosted production deploys do:
+Once the capsule is running:
 
 ```sh
-agentkit login --token agk_user_...
+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 secret set OPENAI_API_KEY "$OPENAI_API_KEY"
+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 transcribe smoke --provider groq
+agentkit chat-ui --deploy
 ```
 
-See `docs/guides/create-agent.md` and `docs/guides/prepare-deploy.md` for the user workflow.
+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.
+
+## Full Reference
+
+`agentkit --help` keeps the first surface focused. Run `agentkit help commands` for the full CLI reference and `agentkit docs full` to print the path to the full agent-facing operating contract.

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
 
@@ -16,26 +16,30 @@ 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 add whatsapp support-whatsapp --provider zapster
 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`, or `slackChannel`.
 - `.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, slackChannel, telegramChannel, whatsappChannel, websiteChannel } from "@andreprado/agentkit";
 
 export default defineAgent({
   name: "support-agent",
@@ -48,18 +52,113 @@ 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" }),
+    slackChannel({ name: "support-slack" }),
   ],
   access: { mode: "public" },
   storage: { driver: "agentkit" },
 });
 ```
 
+## Buffer Bursty Messages
+
+Use `buffer` 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,
+  },
+})
+```
+
+Buffering is scoped to one channel conversation. AgentKit still validates and dedupes each provider webhook, then stores the messages in a short-lived channel buffer. When the quiet window expires, AgentKit creates one agent run with the buffered messages and sends one outbound reply.
+
+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.
+
+## 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" },
+    }),
+  ],
+  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.
+
+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`.
 - Keep local values in ignored `.env`; hosted production uses managed secrets with no readback.
 - 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
 
@@ -69,10 +168,14 @@ bun test
 agentkit inspect
 agentkit channels list
 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`. Explicit dry-run mode is `adapter_stubbed`, which means the provider was not called.
 
 ## Troubleshooting
 
@@ -83,7 +186,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

@@ -0,0 +1,144 @@
+# Add Knowledge
+
+Knowledge is AgentKit's native retrieval layer for facts the agent should not invent: policies, prices, service details, FAQs, CSV tables, procedures, and internal reference docs.
+
+Use Knowledge when the answer should come from source files instead of the base prompt. Do not use Knowledge for secrets, credentials, or data that should only be fetched live through a tool.
+
+## Configure
+
+Create a `knowledge/` directory in the Agent Capsule and list the sources in `agentkit.config.ts`:
+
+```ts
+export default defineAgent({
+  // ...
+  knowledge: {
+    sources: [
+      "knowledge/faq.md",
+      { path: "knowledge/prices.csv", title: "Prices" },
+    ],
+    retrieval: {
+      topK: 8,
+      hybrid: false,
+    },
+  },
+});
+```
+
+Local Knowledge supports `.md`, `.markdown`, `.txt`, and `.csv` files. Markdown is chunked by headings, text is chunked by paragraphs, and CSV rows preserve column headers.
+
+The default embedding provider is `none`, which gives local lexical search without an API key. To add embeddings, configure them separately from the chat provider:
+
+```ts
+knowledge: {
+  sources: ["knowledge/faq.md"],
+  embedding: {
+    provider: "openai",
+    model: "text-embedding-3-small",
+    secret: "KNOWLEDGE_OPENAI_API_KEY",
+  },
+  retrieval: {
+    topK: 8,
+    hybrid: true,
+  },
+},
+```
+
+Then set the local secret without committing it:
+
+```sh
+printf %s "$KNOWLEDGE_OPENAI_API_KEY" | agentkit env set KNOWLEDGE_OPENAI_API_KEY --stdin
+```
+
+## Index Locally
+
+Index one source:
+
+```sh
+agentkit knowledge add knowledge/faq.md
+```
+
+Sync all configured sources:
+
+```sh
+agentkit knowledge sync
+```
+
+Inspect indexed sources:
+
+```sh
+agentkit knowledge inspect
+```
+
+Search locally:
+
+```sh
+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.
+
+With the deterministic `test/fake` provider, verify the internal tool directly:
+
+```sh
+agentkit chat --message '{"tool":"agentkit_search_knowledge","input":{"query":"refund policy","topK":1}}'
+```
+
+Expected output:
+
+```txt
+Tool agentkit_search_knowledge: completed
+```
+
+The retrieved chunks are persisted as internal tool output in local SQLite for evals and inspection, but they are not shown directly to the user.
+
+## Hosted Deploy
+
+Cloudflare Knowledge deploys require AgentKit-managed Turso storage:
+
+```ts
+storage: {
+  driver: "agentkit",
+  database: {
+    driver: "turso",
+    schema: "./schema.sql",
+  },
+},
+```
+
+`agentkit deploy doctor` and `agentkit build --target cloudflare` fail with an actionable error when Knowledge is configured without Turso. The Cloudflare artifact includes the Knowledge manifest, required embedding secret names, internal Knowledge schema, local source file contents, prompt policy, and hosted `agentkit_search_knowledge` runtime.
+
+During `agentkit deploy`, AgentKit Cloud provisions or resolves the project Turso database, applies the Knowledge schema, chunks every packaged local source, creates embeddings when an embedding provider is configured, and writes sources, chunks, embedding metadata, FTS rows, and a native Turso `libsql_vector_idx` index into Turso before publishing the Worker. Removed configured sources are deleted from the hosted Knowledge tables during sync.
+
+Local `agentkit knowledge add`, `agentkit knowledge sync`, `agentkit dev`, and `agentkit chat` index configured Knowledge into the local SQLite database and local libSQL vector sidecar. Hosted deploy syncs configured local Knowledge sources automatically from the deploy artifact so embedding secrets stay server-side and private source material does not move into client code. Hosted semantic search uses Turso native vector search when embeddings are configured and falls back to stored JSON embeddings if the native vector path is unavailable.
+
+## Safety Rules
+
+- Do not put API keys, passwords, private tokens, `.env` contents, or credential exports in Knowledge files.
+- Treat committed Knowledge files as repository content. Use a private repo for private business docs.
+- Use tools for live customer records, payments, orders, or anything requiring authorization checks.
+- Use explicit `title` fields for CSVs or ambiguous files so search results have useful citations.
+- Use `agentkit knowledge sync` to validate source changes explicitly; local `agentkit dev` and `agentkit chat` also sync configured sources automatically.
+
+## Troubleshooting
+
+- `No knowledge.sources are configured`: add `knowledge.sources` to `agentkit.config.ts` or use `agentkit knowledge add <path>`.
+- `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,163 @@
+# 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
+
+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.
+
+## 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 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
+
+```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

@@ -329,7 +329,7 @@ Compare the JSON message input to `inputSchema`.
 Add the secret name to `.env.schema`, write the local value to ignored `.env`, and inspect again:
 
 ```sh
-npm run agentkit -- env set CRM_API_KEY "<value>"
+printf %s "$CRM_API_KEY" | npm run agentkit -- env set CRM_API_KEY --stdin
 npm run agentkit -- inspect
 ```