@andreprado/agentkit 0.1.0-alpha.8 → 0.1.0

package/docs/llms-full.txt

@@ -33,7 +33,8 @@ The capsule root is the runtime boundary. Run AgentKit commands from the directo
 Current commands:
 
 ```sh
-agentkit new <name> [--template blank|support|dentista] [--no-install]
+agentkit new [name] [--template blank|support|dentista] [--no-install]
+agentkit new .
 agentkit dev [--port <number>]
 agentkit open
 agentkit chat-ui --deploy
@@ -49,25 +50,48 @@ agentkit db reset --yes
 agentkit db shell
 agentkit db seed [--file <path>]
 agentkit eval run
+agentkit eval from-conversation <conversation-id> [--out <path>] [--force]
+agentkit improve collect [--deploy] [--since <duration|iso>] [--conversation-id <id>] [--out <directory>]
+agentkit improve evals <bundle-dir-or-json> [--force]
+agentkit replay <bundle-dir-or-json> --against local
+agentkit feedback create [--about last-run|deploy|manual] [--kind bug|confusion|missing_docs|feature_request|deploy_issue|runtime_issue|other] --summary <text> [--message <text>] [--out <path>]
+agentkit feedback preview [draft.json]
+agentkit feedback send [draft.json] [--about last-run|deploy|manual] [--kind <kind>] --summary <text> [--message <text>] [--api <url>] [--save]
 agentkit conversations list
 agentkit conversations show <conversation-id>
+agentkit conversations trace <conversation-id> [--deploy]
 agentkit channels list
-agentkit channels add <website|telegram|whatsapp> <name> [--provider zapster|meta] [--api <url>]
+agentkit channels add <website|telegram|whatsapp|discord|slack|webhook> <name> [--provider zapster|meta|uazapi|evolution] [--mode interactions|bot] [--api <url>]
+agentkit channels connect <website|telegram|whatsapp|discord|slack|webhook> <name> [--provider zapster|meta|uazapi|evolution] [--mode interactions|bot] [--api <url>]
 agentkit channels setup <name> [--apply] [--api <url>]
 agentkit channels status <name> [--api <url>]
 agentkit channels test <name> [--message <text>] [--fixture <path>] [--api <url>]
+agentkit channels test-audio <name> [--fixture voice-note|audio-file|<path>] [--api <url>]
 agentkit channels deliveries list <name> [--api <url>]
 agentkit channels deliveries show <delivery-id> [--api <url>]
+agentkit integrations status [--toolkit <slug>] [--api <url>]
+agentkit integrations connect composio [--toolkit <slug>] [--callback-url <url>] [--api <url>]
+agentkit skills status
+agentkit skills sync
 agentkit inspect
 agentkit build [--target cloudflare|container]
+agentkit billing checkout --slots <count> [--email <email>] [--api <url>]
+agentkit billing status <billing-intent-id> --secret <secret> [--api <url>]
+agentkit billing claim <billing-intent-id> --secret <secret> [--token-name <name>] [--api <url>]
+agentkit billing portal [--api <url>]
+agentkit provider login|status|logout openai-codex
 agentkit login --token <token>
 agentkit logout
+agentkit account token create <name> [--api <url>] [--use] [--out <path>]
+agentkit account token list [--api <url>]
+agentkit account token revoke <token-id> [--api <url>]
 agentkit deploy [--target cloudflare|vps] [--host <host>] [--api <url>] [--dry-run] [--anonymous] [--local-wrangler] [--smoke <message>]
 agentkit deploy doctor [--api <url>] [--anonymous]
 agentkit deploy smoke [--message <text>] [--api <url>]
 agentkit deploy status
 agentkit deploy pause
 agentkit deploy resume
+agentkit transcribe smoke [--provider test|openai|groq] [--model <model>] [--fixture <audio-file>]
 agentkit secret set <NAME> <VALUE>
 agentkit secret set <NAME> --stdin
 agentkit secret set <NAME> --from-env [ENV_NAME]
@@ -93,11 +117,11 @@ agentkit help commands
 
 Prefer `env set --stdin` or `--from-env` for local secret values, and prefer `secret set --stdin`, `--from-env`, or `--from-local-env` for hosted secrets. Inline `<VALUE>` forms exist for simple non-sensitive values, but agents should avoid putting secrets in shell history.
 
-Planned commands described by the contract but not implemented yet:
+Use `agentkit feedback create` when AgentKit itself fails, confuses the coding agent, or lacks docs. Drafts are local files under `.agentkit/feedback/` and are not sent automatically. Use `agentkit feedback send` only after reviewing the draft and logging in with `agentkit login --token agk_user_...`. Feedback upload uses authenticated AgentKit Cloud account auth, redacts common token/key patterns, does not upload arbitrary files, and does not cause the deployed agent runtime to phone home.
 
-```sh
-agentkit eval create-from-conversation <conversation-id>
-```
+On Windows PowerShell, if `npm.ps1` or `npx.ps1` is blocked with `PSSecurityException`, run capsule scripts through the `.cmd` shims instead of changing the workflow. Examples: `npx.cmd @andreprado/agentkit@alpha new demo --template blank`, `npm.cmd run agentkit -- inspect`, `npm.cmd run agentkit -- knowledge sync`, and `npm.cmd run eval`.
+
+Managed Composio is configured with `composioManaged({...})` in `agentkit.config.ts` and is paid hosted AgentKit infrastructure. It requires a non-anonymous AgentKit Cloud deploy with `managed_composio`, uses one Composio settings profile per agent, injects `COMPOSIO_API_KEY` as an AgentKit-managed secret, resolves toolkit auth configs from AgentKit Cloud, validates toolkit readiness during `agentkit deploy doctor`, and exposes the generated `agentkit_composio_execute` tool only for explicit configured action slugs. Calendar starters should include `GOOGLECALENDAR_EVENTS_LIST`, `GOOGLECALENDAR_CREATE_EVENT`, and `GOOGLECALENDAR_UPDATE_EVENT`; create-event calls must pass UTC `start_datetime` plus explicit duration. An integration containing external write actions is operator-only; invoke it directly with `agentkit tool`, and pass `confirmed: true` for writes unless the integration disables that secondary check. See `docs/guides/add-managed-composio.md`.
 
 ## Create And Test A Capsule
 
@@ -117,6 +141,8 @@ npm run agentkit -- conversations list
 npm run 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. Non-interactive scripts should pass a name or `.` explicitly.
+
 Expected first chat output:
 
 ```txt
@@ -139,7 +165,7 @@ Then open the folder in Codex, Claude Code, or another coding agent and ask dire
 Develop an appointment and intake agent for an ophthalmology office.
 ```
 
-The coding agent should infer the first useful version, edit `prompts/instructions.md`, `agentkit.config.ts`, `schema.sql`, `tools/`, and `evals/`, then run the verification commands before finishing. Do not wait for a wizard or recipe. AgentKit provides the scaffold and contract; the coding agent implements directly in the capsule.
+The coding agent should infer the first useful version, edit `prompts/instructions.md`, `agentkit.config.ts`, `schema.sql`, `tools/`, and `evals/`, then run the verification commands before finishing. Do not send the owner back to a CLI brief wizard. AgentKit provides the scaffold, contract, and skills; the coding agent implements directly in the capsule from the owner's chat message.
 
 Optional handoff shortcut:
 
@@ -166,6 +192,7 @@ export default defineAgent({
     name: "test",
     model: "fake",
   },
+  timeZone: "America/New_York",
   instructions: "./prompts/instructions.md",
   secrets: [],
   tools: [],
@@ -178,6 +205,8 @@ export default defineAgent({
 });
 ```
 
+`timeZone` is optional and must be an IANA time zone when set. AgentKit injects dynamic runtime context into every chat run: current ISO timestamp, local date, local weekday, local date/time, and timezone. Use `timeZone` for scheduling, appointments, reminders, deadlines, and any prompt behavior that interprets "today", "tomorrow", weekdays, or relative dates. Do not hardcode today's date in `prompts/instructions.md`. If `timeZone` is omitted, AgentKit falls back to `AGENTKIT_TIME_ZONE`, then valid `TZ`, then the runtime default timezone.
+
 Valid runtime values:
 
 ```txt
@@ -190,8 +219,11 @@ Valid provider names:
 ```txt
 test
 openai
+openai-codex
 anthropic
 openrouter
+opencode
+opencode-go
 custom
 ```
 
@@ -200,8 +232,11 @@ Current provider adapters:
 ```txt
 test/fake
 openai via Pi SDK
+openai-codex via Pi SDK (local ChatGPT OAuth)
 anthropic via Pi SDK
 openrouter via Pi SDK
+opencode via Pi SDK
+opencode-go via Pi SDK
 ```
 
 `custom` is a reserved config value. It is not implemented as a local provider adapter yet.
@@ -220,7 +255,9 @@ secrets: [],
 
 `test/fake` is deterministic. It is useful for scaffold checks, direct tool checks, and fake-provider evals, but it does not validate natural conversation quality.
 
-Before claiming real conversation behavior has been tested, ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, or another supported provider. Do not choose for them. After the owner chooses, update `agentkit.config.ts`, `.env.schema`, local secrets, hosted secrets if deploying, then rerun chat/UI checks.
+Before claiming real conversation behavior has been tested, ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go, or another supported provider. Do not choose for them. After the owner chooses, update `agentkit.config.ts`, `.env.schema`, local secrets, hosted secrets if deploying, then rerun chat/UI checks.
+
+ChatGPT/Codex subscription login (local only): run `agentkit provider login openai-codex` in an interactive terminal, sign in through the printed URL, and set `provider: { name: "openai-codex", model: "gpt-5.4" }`. No `OPENAI_API_KEY` is required for this provider. Keep secrets needed by tools or other services. The AgentKit session is stored outside capsules in `~/.agentkit/providers/openai-codex.json`, renewed through Pi, and never copied from or into the Codex app cache. `agentkit provider status openai-codex` reports local status without tokens; `agentkit provider logout openai-codex` removes the local session without revoking it at OpenAI. Cloudflare, container, and VPS builds reject this provider with `target_runtime_incompatible`; hosted OAuth is not supported. See `docs/guides/use-provider.md`.
 
 OpenAI example:
 
@@ -243,6 +280,32 @@ npm run chat -- --message "hello"
 
 If a provider key is missing, the runtime returns `secret_not_found`.
 
+For OpenRouter, prefer model ids or aliases known to the installed Pi SDK, such as `~google/gemini-flash-latest`. If an OpenRouter id is newer than Pi's registry, AgentKit passes the raw id through to OpenRouter with conservative unknown-model metadata. OpenRouter can still reject invalid, inaccessible, or unsupported models, and unknown-model cost/capability metadata is not authoritative.
+
+OpenCode Zen example:
+
+```ts
+provider: {
+  name: "opencode",
+  model: "big-pickle",
+},
+secrets: ["OPENCODE_API_KEY"],
+```
+
+Use an OpenCode Zen model id listed by the installed Pi SDK, such as `big-pickle`, `deepseek-v4-flash-free`, `claude-sonnet-4-5`, or `gpt-5.4-mini`.
+
+OpenCode Go example:
+
+```ts
+provider: {
+  name: "opencode-go",
+  model: "deepseek-v4-flash",
+},
+secrets: ["OPENCODE_API_KEY"],
+```
+
+Use an OpenCode Go model id listed by the installed Pi SDK, such as `deepseek-v4-flash`, `deepseek-v4-pro`, `glm-5.1`, `kimi-k2.6`, `minimax-m2.7`, or `qwen3.6-plus`.
+
 ## Knowledge Contract
 
 Knowledge is AgentKit's native retrieval layer for facts the agent should ground in source files. Use it for FAQs, prices, policies, service descriptions, procedures, CSV tables, and reference docs. Do not put secrets, credentials, `.env` contents, or live customer/payment records in Knowledge. Use tools for live or authorization-sensitive data.
@@ -292,7 +355,7 @@ agentkit knowledge inspect
 agentkit knowledge search "refund policy" --top-k 3
 ```
 
-`knowledge add` indexes one local path. `knowledge sync` indexes all configured `knowledge.sources` and skips unchanged files by content hash. `agentkit dev` and `agentkit chat` also sync configured Knowledge automatically before local runs. `knowledge inspect` lists indexed sources and chunk counts. `knowledge search` validates retrieval before relying on the agent. When embeddings are configured locally, AgentKit stores canonical chunks in `.agentkit/agentkit.db`, rebuilds a local libSQL vector sidecar at `.agentkit/agentkit.vectors.db`, uses native `libsql_vector_idx` semantic search, and falls back to stored JSON embeddings if the native vector path is unavailable.
+`knowledge add` indexes one local path. `knowledge sync` indexes all configured `knowledge.sources` and skips unchanged files by content hash. `agentkit dev` and `agentkit chat` also sync configured Knowledge automatically before local runs. `knowledge inspect` lists indexed sources and chunk counts. `knowledge search` validates retrieval before relying on the agent. Local lexical search uses SQLite FTS5 when the local SQLite build provides it; when it does not, AgentKit automatically keeps indexing and searching with a normal SQLite table and simpler text matching. When embeddings are configured locally, AgentKit stores canonical chunks in `.agentkit/agentkit.db`, rebuilds a local libSQL vector sidecar at `.agentkit/agentkit.vectors.db`, uses native `libsql_vector_idx` semantic search, and falls back to stored JSON embeddings if the native vector path is unavailable.
 
 When `knowledge` is configured, AgentKit automatically registers the internal chat tool `agentkit_search_knowledge` 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, chunk IDs, or tool output objects. With `test/fake`, verify the internal tool directly:
 
@@ -317,7 +380,7 @@ Channels are hosted inbound/outbound conversation transports. They are separate
 Use these helpers in `agentkit.config.ts`:
 
 ```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",
@@ -330,6 +393,12 @@ export default defineAgent({
     websiteChannel({ name: "website-chat" }),
     telegramChannel({ name: "support-telegram" }),
     whatsappChannel({ name: "support-whatsapp", provider: "zapster" }),
+    whatsappChannel({ name: "support-uazapi", provider: "uazapi" }),
+    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" },
@@ -341,10 +410,13 @@ Rules:
 - `runtime: "edge"` is required when `channels` are configured.
 - Channel names are stable lowercase identifiers and must be unique.
 - Config stores secret names only, never secret values.
+- UAZAPI and Zapster WhatsApp channels require `UAZAPI_WEBHOOK_TOKEN` and `ZAPSTER_WEBHOOK_TOKEN`; webhooks without the matching query token are rejected.
 - AgentKit owns channel webhook URLs, dedupe, identities, queue state, and delivery logs.
 - Do not store channel plumbing in the user's Turso database.
 - Use `buffer.mode: "debounce"` when a channel should coalesce rapid client messages into one agent run.
 - Buffered deliveries show `buffered`, then flush to one `queued` run after `quietWindowMs`, `maxWaitMs`, `maxMessages`, or `maxChars`.
+- Use `replyTo` when an inbound channel should receive on one transport and answer on another configured channel.
+- Use `webhookOutputChannel` when the reply target is a generic HTTPS callback URL stored in a managed secret.
 
 Channel buffer example:
 
@@ -365,11 +437,14 @@ whatsappChannel({
 Useful guides:
 
 - Add a channel: `docs/guides/add-channel.md`
+- Connect Discord: `docs/guides/connect-discord.md`
+- Connect Slack: `docs/guides/connect-slack.md`
 - Connect Telegram: `docs/guides/connect-telegram.md`
+- Connect WhatsApp through Evolution API: `docs/guides/connect-whatsapp-evolution.md`
+- Connect WhatsApp through UAZAPI: `docs/guides/connect-whatsapp-uazapi.md`
 - Connect WhatsApp through Zapster: `docs/guides/connect-whatsapp-zapster.md`
 - Debug a channel: `docs/guides/debug-channel.md`
 - Channel security: `docs/guides/channel-security.md`
-- Production handoff: `docs/guides/channels-production-handoff.md`
 
 Telegram required secrets:
 
@@ -382,9 +457,110 @@ Zapster WhatsApp required secrets:
 
 ```txt
 ZAPSTER_API_KEY
-ZAPSTER_WEBHOOK_SECRET
+ZAPSTER_INSTANCE_ID
+ZAPSTER_WEBHOOK_ID
+ZAPSTER_WEBHOOK_TOKEN
+```
+
+UAZAPI WhatsApp required secrets:
+
+```txt
+UAZAPI_BASE_URL
+UAZAPI_TOKEN
+UAZAPI_WEBHOOK_TOKEN
+```
+
+`UAZAPI_WEBHOOK_TOKEN` and `ZAPSTER_WEBHOOK_TOKEN` are AgentKit-owned secrets generated by the user, not provider-issued credentials. For local `agentkit dev`, expose the printed port through an HTTPS tunnel and register the exact `/channels/<name>/whatsapp/<provider>/webhook?token=<secret>` URL. Only authenticated channel webhook routes accept a tunnel host; other local endpoints remain loopback-only.
+
+Evolution API WhatsApp required secrets:
+
+```txt
+EVOLUTION_API_BASE_URL
+EVOLUTION_API_KEY
+EVOLUTION_INSTANCE_NAME
+EVOLUTION_WEBHOOK_TOKEN
+```
+
+Discord slash-command required secret:
+
+```txt
+DISCORD_PUBLIC_KEY
+```
+
+Discord bot-mode required secret:
+
+```txt
+DISCORD_BOT_TOKEN
+```
+
+Generic webhook required secret:
+
+```txt
+AGENTKIT_WEBHOOK_SECRET
+```
+
+Generic webhook payloads should be canonical JSON:
+
+```json
+{
+  "event_id": "evt_123",
+  "external_id": "customer_123",
+  "message": "hello from n8n"
+}
+```
+
+Use `Authorization: Bearer <AGENTKIT_WEBHOOK_SECRET>`, `X-AgentKit-Webhook-Secret`, or `X-AgentKit-Webhook-Signature: sha256=<hmac>` where the HMAC is SHA-256 over the exact raw JSON body. The hosted URL is `/channels/<name>/webhook`.
+
+Without `replyTo`, generic webhooks are inbound-only and do not call back into the source system. To receive on one channel and answer on another, add a static `replyTo` route:
+
+```ts
+webhookChannel({
+  name: "lead-webhook",
+  replyTo: {
+    channel: "main-whatsapp",
+    recipientFrom: "phone",
+  },
+})
+
+whatsappChannel({
+  name: "main-whatsapp",
+  provider: "evolution",
+})
+```
+
+`recipientFrom` is a dotted JSON path such as `phone`, `customer.phone`, or `payload.customer.phone`. It must resolve to a non-empty scalar in the inbound payload. Do not use `recipientFrom` for Discord or Slack replies because those transports need provider-native source identities.
+
+Multiple webhooks are multiple named channels:
+
+```ts
+webhookChannel({ name: "n8n-webhook" })
+webhookChannel({ name: "make-webhook" })
+webhookChannel({ name: "crm-webhook", replyTo: { channel: "main-whatsapp", recipientFrom: "phone" } })
 ```
 
+Generic output webhook channels send the final agent answer to an HTTPS callback URL:
+
+```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",
+  },
+})
+```
+
+`CRM_CALLBACK_URL` and output auth values are managed secrets only. The URL must be public HTTPS; AgentKit rejects localhost, private network, link-local, and metadata-service hosts. Supported output auth modes are `none`, `bearer`, `header`, and `hmac`. Generic output channels do not have public inbound webhook URLs, so `agentkit channels test <output-name>` is unsupported.
+
 Common channel verification:
 
 ```sh
@@ -392,23 +568,37 @@ agentkit inspect
 agentkit deploy
 agentkit channels list
 agentkit channels add telegram support-telegram
+agentkit channels connect whatsapp main-whatsapp --provider evolution
+agentkit channels connect whatsapp support-whatsapp --provider uazapi
+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 setup support-telegram
 agentkit channels test support-telegram --message "hello"
+agentkit channels test-audio support-telegram --fixture voice-note
+agentkit transcribe smoke --provider groq
 agentkit channels deliveries list support-telegram
 agentkit channels deliveries show <delivery-id>
 ```
 
-`channels setup` is read-only by default. `channels setup <telegram-name> --apply` calls Telegram `setWebhook` and requires `TELEGRAM_BOT_TOKEN` plus `TELEGRAM_WEBHOOK_SECRET`.
+`channels connect` creates or refreshes the channel resource, validates secrets, runs provider setup when supported, then runs the official synthetic smoke. `channels setup` is read-only by default. `channels setup <telegram-name> --apply` calls Telegram `setWebhook` and requires `TELEGRAM_BOT_TOKEN` plus `TELEGRAM_WEBHOOK_SECRET`. `channels setup <uazapi-whatsapp-name> --apply` calls UAZAPI `/webhook` and requires `UAZAPI_BASE_URL`, `UAZAPI_TOKEN`, and `UAZAPI_WEBHOOK_TOKEN`. `channels setup <evolution-whatsapp-name> --apply` calls Evolution API `/webhook/set/{instance}` and requires `EVOLUTION_API_BASE_URL`, `EVOLUTION_API_KEY`, `EVOLUTION_INSTANCE_NAME`, and `EVOLUTION_WEBHOOK_TOKEN`.
+
+Discord slash-command mode validates `X-Signature-Ed25519` and `X-Signature-Timestamp` against `DISCORD_PUBLIC_KEY`, answers signed `PING` requests with `type: 1`, acknowledges slash commands with a deferred response, then sends the final answer as an interaction follow-up. Discord bot mode uses `DISCORD_BOT_TOKEN`, Discord Gateway `MESSAGE_CREATE`, Message Content Intent, and `/channels/<channel_id>/messages` bot replies. Discord channels support buffering but do not support `audio` in V1.
 
 Default tests are offline. Real provider smoke tests are opt-in:
 
 ```sh
 AGENTKIT_RUN_TELEGRAM_CHANNEL_TESTS=1 bun test
 AGENTKIT_RUN_ZAPSTER_CHANNEL_TESTS=1 bun test
+AGENTKIT_RUN_UAZAPI_CHANNEL_TESTS=1 bun test
+AGENTKIT_RUN_EVOLUTION_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`, `AGENTKIT_ZAPSTER_SEND_URL`, and `AGENTKIT_ZAPSTER_TO`.
+Zapster smoke also requires `ZAPSTER_API_KEY`, `ZAPSTER_WEBHOOK_TOKEN`, `AGENTKIT_ZAPSTER_SEND_URL`, and `AGENTKIT_ZAPSTER_TO`.
+UAZAPI smoke also requires `UAZAPI_BASE_URL`, `UAZAPI_TOKEN`, `UAZAPI_WEBHOOK_TOKEN`, and `AGENTKIT_UAZAPI_TO`.
+Evolution smoke also requires `EVOLUTION_API_BASE_URL`, `EVOLUTION_API_KEY`, `EVOLUTION_INSTANCE_NAME`, and `AGENTKIT_EVOLUTION_TO`.
 
 ## Tool Contract
 
@@ -469,9 +659,11 @@ Tool runtime rules:
 - `timeoutMs` overrides the default;
 - tool calls are saved in AgentKit-managed local storage;
 - secret values are redacted before storage.
+- permissions ending in `:read` may run automatically; any other declared permission requires a reviewed direct `agentkit tool` invocation and is blocked from chat, channels, and evals;
 - tools that need SQL use canonical `ctx.db`; `ctx.database` and `ctx.storage.sql` are supported aliases;
 - tools can use `ctx.db.batch([...])` for atomic writes; local tools can also use `ctx.db.transaction(async (tx) => ...)`;
 - tools can inspect `ctx.runtime` with `{ environment, invocation, target, database }`;
+- tools can use `ctx.clock` for the same runtime clock injected into the agent prompt, including `now`, `isoTimestamp`, `timeZone`, `localDate`, `localWeekday`, and `localDateTime`;
 - tools must not import local database drivers or Node-only APIs. Use AgentKit runtime services instead.
 
 ## Database Tools And Dual Storage
@@ -505,7 +697,7 @@ CREATE TABLE IF NOT EXISTS appointments (
 );
 ```
 
-`schema.sql` is an idempotent bootstrap file in v1. Use `CREATE TABLE IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`, and only safe additive `ALTER TABLE` statements. AgentKit does not automatically run destructive changes or ordered `migrations/*.sql` yet.
+`schema.sql` is an idempotent bootstrap file. Use `CREATE TABLE IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`, and only safe additive `ALTER TABLE` statements. Use ordered `migrations/*.sql` for production-shaped schema evolution; `agentkit db migrate` applies unapplied local migrations before `schema.sql`.
 
 Example tool:
 
@@ -670,6 +862,9 @@ GET  /_agentkit
 POST /v1/chat
 GET  /v1/conversations
 GET  /v1/conversations/:id
+GET  /v1/conversations/:id/trace
+POST /channels/<name>/<type>/<provider>/webhook
+POST /channels/<name>/webhook
 ```
 
 Chat request:
@@ -689,6 +884,7 @@ After chat:
 ```sh
 agentkit conversations list
 agentkit conversations show <conversation-id>
+agentkit conversations trace <conversation-id>
 ```
 
 List output columns:
@@ -697,7 +893,7 @@ List output columns:
 id	title	updated_at	messages
 ```
 
-Show output includes the conversation id, title, updated timestamp, and each message as `role: content`.
+Show output includes the conversation id, title, updated timestamp, and each message as `role: content`. Trace output includes stored messages and tool calls for the conversation.
 
 ## Evals
 
@@ -716,17 +912,84 @@ npm run eval
 Supported assertion types:
 
 ```txt
-contains
-not_contains
-regex
-matches_regex
-persisted_tool_call
+response.contains
+response.containsAll
+response.containsAny
+response.caseInsensitiveContains
+response.notContains
+response.regex
+response.matchesRegex
+response.notRegex
+response.maxLength
+tools.called
+tools.calledOnce
+tools.count
+tools.order
+tools.persisted
 ```
 
-`persisted_tool_call` validates the tool call saved in local SQLite `tool_calls`, not a provider-specific raw response shape. It can be a tool name string or an object with `name`, `input`, `output`, `status`, and/or `visibility`. `tool_call` remains accepted as a backwards-compatible alias.
+Import `defineEval` from `@andreprado/agentkit` when writing new evals. `tools.persisted` validates the tool call saved in the eval run's local SQLite `tool_calls`, not a provider-specific raw response shape. It can be a tool name string or an object with `name`, `input`, `output`, `rendered`, `status`, and/or `visibility`. `tool_call` and `persisted_tool_call` remain accepted as backwards-compatible aliases, but new evals should use `tools.persisted`.
+
+For date-sensitive evals, set top-level `now` to an ISO timestamp with an explicit timezone designator such as `Z` or `-05:00`. AgentKit uses that fixed clock for every turn and tool call in the eval so "today", "tomorrow", and weekdays remain deterministic while normal chat continues to use the real current date.
 
 Evals run the normal capsule tools. If a tool would write externally, delete, charge money, send email, or call a real customer system, make its `execute` implementation branch on `ctx.runtime.environment === "eval"` and return deterministic non-destructive output for eval runs. Do not invent an eval-only mock API; keep the behavior inside the registered tool contract unless AgentKit adds a first-class mock facility later.
 
+## Improve From Production
+
+Use AgentKit Improve when a hosted or local conversation should become a reproducible local fix loop. Hosted AgentKit Cloud exports evidence; the local coding agent edits the Agent Capsule, writes evals, replays, and deploys.
+
+Collect hosted evidence from the last deploy:
+
+```sh
+agentkit improve collect --deploy --since 24h
+```
+
+When the CLI is logged in to AgentKit Cloud, hosted collection first exports deploy evidence such as failed channel deliveries, deploy errors, and conversation IDs from the control plane, then reads replayable conversation traces from the deployed runtime. Without Cloud auth, it falls back to deploy-token conversation trace reads.
+
+Hosted conversation reads require a deploy access token even when the chat endpoint is public. `agentkit deploy` normally writes `.agentkit/chat-access-token.json`; use `agentkit access token create agentkit-chat-ui --out .agentkit/chat-access-token.json` to refresh it.
+
+Collect one hosted conversation:
+
+```sh
+agentkit improve collect --deploy --conversation-id <conversation-id>
+```
+
+Collect local evidence:
+
+```sh
+agentkit improve collect --since 7d
+```
+
+The command writes ignored local state:
+
+```txt
+.agentkit/improve/<run>/
+  bundle.json
+  report.json
+  traces/
+```
+
+Generate committed regression evals:
+
+```sh
+agentkit improve evals .agentkit/improve/<run>
+```
+
+Then replay before deploying:
+
+```sh
+agentkit replay .agentkit/improve/<run> --against local
+npm run eval
+agentkit deploy --smoke "hello"
+```
+
+Replay runs collected user turns through the local capsule with `ctx.runtime.environment === "eval"` and `ctx.runtime.invocation === "eval"`. Generated evals live under `evals/regressions/`; review them before committing, especially when traces contain real client details or overly strict prose assertions.
+
+Full guides:
+
+- `docs/guides/improve-from-production.md`
+- `docs/guides/replay-production-traces.md`
+
 ## Security Rules
 
 Never commit:
@@ -750,9 +1013,10 @@ prompts/
 docs/
 ```
 
-Local `.env` is development only. Use `.env.schema` as the committed secret-name contract; local AgentKit commands load `.env` directly. Hosted alpha deploys use `agentkit login --token ...` and managed secrets through `agentkit secret set/list/unset` or `agentkit secret sync --from-local`. Prefer `--stdin`, `--from-env`, `--from-local-env`, or sync from local `.env` so secret values do not appear in shell history. Inline `<VALUE>` forms exist only for compatibility and simple non-sensitive values.
+Local `.env` is development only. Use `.env.schema` as the committed secret-name contract; local AgentKit commands load `.env` directly. Hosted deploys require an AgentKit Cloud account with `cloudflare_deploy_alpha` or purchased/manual deploy slots. First-time paid access uses `agentkit billing checkout --slots <count>` and `agentkit billing claim billint_... --secret bsec_...`; existing accounts use `agentkit login --token ...`. Hosted secrets use `agentkit secret set/list/unset` or `agentkit secret sync --from-local`. Prefer `--stdin`, `--from-env`, `--from-local-env`, or sync from local `.env` so secret values do not appear in shell history. Inline `<VALUE>` forms exist only for compatibility and simple non-sensitive values.
 
 Tools are a security boundary. A tool must declare every secret it needs. The runtime injects only tool-declared secrets.
+Agent Capsules are trusted executable TypeScript, not sandboxed configuration. Run AgentKit commands only in Capsules whose config, tools, evals, and sync modules you trust.
 
 ## Hosted Deploy Contract
 
@@ -762,7 +1026,10 @@ Current flow:
 
 ```sh
 agentkit deploy --dry-run
+agentkit billing checkout --slots 1 --email user@example.com
+agentkit billing claim billint_... --secret bsec_...
 agentkit login --token agk_user_...
+agentkit account token create new-laptop --use
 agentkit deploy doctor
 agentkit deploy --smoke "hello"
 agentkit deploy status
@@ -770,9 +1037,9 @@ agentkit deploy smoke --message "hello"
 agentkit chat-ui --deploy
 ```
 
-`agentkit deploy doctor` checks AgentKit Cloud login, `cloudflare_deploy_alpha`, online deploy capacity, hosted secrets, local `.env` names that still need `agentkit secret set`, and private-access runtime token handling. `agentkit deploy` sends the capsule to AgentKit Cloud, runs the same readiness check automatically before building and uploading, and writes the local chat/UI deploy access token to `.agentkit/chat-access-token.json` for private hosted deploys. `agentkit deploy --smoke "hello"` deploys and then tests `/v1/chat` with the deploy access token. `agentkit deploy smoke --message "hello"` repeats that smoke against the last local deploy. `agentkit chat-ui --deploy` serves a local UI pointed at the hosted deploy using that token without exposing it to browser code. Production alpha deploys require an account with `cloudflare_deploy_alpha`; local commands and dry-run builds do not require login. AgentKit owns infrastructure selection, backend migration, managed secrets, and public URL creation.
+`agentkit deploy doctor` checks AgentKit Cloud login, hosted deploy entitlement, online deploy capacity, hosted secrets, local `.env` names that still need `agentkit secret set`, managed Composio API/auth-config readiness by toolkit, and private-access runtime token handling. `agentkit deploy` sends the capsule to AgentKit Cloud, runs the same readiness check automatically before building and uploading, updates the current project deploy slot by default, writes the local chat/UI deploy access token to `.agentkit/chat-access-token.json`, and prints a production handoff with URL, UI command, secret status, database/schema artifact, integration connect commands, smoke status, and the next recommended command. `agentkit deploy --smoke "hello"` deploys and then tests `/v1/chat` with the deploy access token. `agentkit deploy smoke --message "hello"` repeats that smoke against the last local deploy. `agentkit chat-ui --deploy` serves a local UI pointed at the hosted deploy using that token without exposing it to browser code, shows the conversation id and tool calls, and supports starting a new conversation. Use `agentkit conversations trace <conversation-id> --deploy` to pull hosted conversation messages and tool calls from the last deploy. Production deploys require an account with `cloudflare_deploy_alpha` or purchased/manual deploy slots; local commands and dry-run builds do not require login. AgentKit owns infrastructure selection, backend migration, managed secrets, and public URL creation.
 
-The CLI defaults to the hosted AgentKit Cloud API at `https://agentkit-cloud.aibuilders.com.br`. Use `AGENTKIT_CLOUD_API_URL` or `agentkit deploy --api <url>` only for local or alternate control-plane tests.
+The CLI defaults to the hosted AgentKit Cloud API at `https://agentkit-cloud.aibuilders.com.br`. Use `AGENTKIT_CLOUD_API_URL` or `agentkit deploy --api <url>` only when the owner gives you a non-default AgentKit Cloud API URL.
 
 Account/access flow:
 
@@ -780,6 +1047,9 @@ Account/access flow:
 agentkit secret set OPENAI_API_KEY --from-local-env
 agentkit secret sync --from-local
 agentkit secret list
+agentkit account token list
+agentkit skills status
+agentkit skills sync
 agentkit access token create website-chat --out .agentkit/website-chat-access-token.json
 agentkit access token list
 ```