@andreprado/agentkit 0.1.1 → 0.2.0

package/docs/llms-full.txt

@@ -37,8 +37,6 @@ agentkit new [name] [--template blank|support|dentista] [--no-install]
 agentkit new .
 agentkit dev [--port <number>]
 agentkit open
-agentkit chat-ui --deploy
-agentkit chat-ui --deploy [--port <number>] [--token-file <path>]
 agentkit chat --message <text> [--conversation-id <id>]
 agentkit tool <name> [--input <path-or-json>]
 agentkit knowledge add <path-or-url>
@@ -51,57 +49,20 @@ 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 collect [--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 create [--about last-run|manual] [--kind bug|confusion|missing_docs|feature_request|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 conversations trace <conversation-id>
 agentkit channels list
-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]
-agentkit secret set <NAME> --from-local-env
-agentkit secret sync --from-local
-agentkit secret list
-agentkit secret unset <NAME>
-agentkit access token create <name> [--api <url>] [--out <path>]
-agentkit access token list
-agentkit access token revoke <token-id>
 agentkit env set <NAME> <VALUE>
 agentkit env set <NAME> --stdin
 agentkit env set <NAME> --from-env [ENV_NAME]
@@ -115,13 +76,12 @@ agentkit handoff claude [goal]
 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.
+Keep secrets in ignored `.env`. Prefer `agentkit env set <NAME> --stdin` or `--from-env`; never put values in shell history or committed files.
 
-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.
+Use `agentkit feedback create` and `preview` to prepare a local redacted report. Review and share it manually; no report is uploaded.
 
 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
 
@@ -176,7 +136,7 @@ npm run agentkit -- handoff claude "Develop an appointment and intake agent for
 
 The command prints a ready-to-paste prompt that points the coding agent at `AGENTKIT.md`, the repo-local `skills/agentkit-capsule/SKILL.md` router when present, and the packaged `llms.txt` docs router. Load `llms-full.txt` only when a skill or ambiguous framework behavior requires the complete contract.
 
-The generated docs and handoff prompt must make UI testing explicit. For local UI testing, run `npm run dev`, open the printed `Chat:` URL, and tell the owner the exact URL. For hosted UI testing after deploy, run `npm run agentkit -- chat-ui --deploy`, open the printed `Chat:` URL, and tell the owner it is connected to the hosted deploy.
+The generated docs and handoff prompt must make UI testing explicit. For local UI testing, run `npm run dev`, open the printed `Chat:` URL, and tell the owner the exact URL.
 
 ## Agent Config
 
@@ -187,7 +147,7 @@ import { defineAgent } from "@andreprado/agentkit";
 
 export default defineAgent({
   name: "support-agent",
-  runtime: "edge",
+  runtime: "local",
   provider: {
     name: "test",
     model: "fake",
@@ -255,9 +215,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, 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.
+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, 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`.
+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. See `docs/guides/use-provider.md`.
 
 OpenAI example:
 
@@ -369,236 +329,39 @@ Expected output:
 Tool agentkit_search_knowledge: completed
 ```
 
-Cloudflare Knowledge deploys require `storage.driver: "agentkit"` and `storage.database.driver: "turso"`. `agentkit deploy doctor` and `agentkit build --target cloudflare` fail clearly when Knowledge is configured without Turso. Cloudflare artifacts include the Knowledge manifest, required embedding secret names, internal Knowledge schema, packaged local source contents, prompt policy, and hosted `agentkit_search_knowledge` runtime. During `agentkit deploy`, AgentKit Cloud applies the Knowledge schema, chunks packaged local sources, creates embeddings when configured, deletes stale hosted sources, and syncs sources, chunks, embedding metadata, FTS rows, and a native Turso `libsql_vector_idx` index into the project Turso database before publishing the Worker. Local `agentkit knowledge add/sync`, `agentkit dev`, and `agentkit chat` index configured Knowledge into local SQLite and the local libSQL vector sidecar; hosted deploy syncs configured local Knowledge sources automatically from the deploy artifact so private source material and embedding secrets do 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.
-
 Full guide: `docs/guides/add-knowledge.md`.
 
 ## Channel Contract
 
-Channels are hosted inbound/outbound conversation transports. They are separate from tools: channels receive user messages, while tools let the agent call external systems.
-
-Use these helpers in `agentkit.config.ts`:
+Configure channels in `agentkit.config.ts` with `runtime: "local"`. Channels receive messages; tools let an agent call external systems. Helpers include `websiteChannel`, `telegramChannel`, `whatsappChannel`, `discordChannel`, `slackChannel`, `webhookChannel`, and `webhookOutputChannel`.
 
 ```ts
-import { defineAgent, discordChannel, slackChannel, telegramChannel, webhookChannel, webhookOutputChannel, whatsappChannel, websiteChannel } from "@andreprado/agentkit";
+import { defineAgent, webhookChannel } from "@andreprado/agentkit";
 
 export default defineAgent({
-  name: "support-agent",
-  runtime: "edge",
+  name: "local-agent",
+  runtime: "local",
   provider: { name: "test", model: "fake" },
   instructions: "./prompts/instructions.md",
   secrets: [],
   tools: [],
-  channels: [
-    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" },
+  channels: [webhookChannel({ name: "inbox" })],
+  access: { mode: "private" },
   storage: { driver: "agentkit" },
 });
 ```
 
-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:
-
-```ts
-whatsappChannel({
-  name: "support-whatsapp",
-  provider: "zapster",
-  buffer: {
-    mode: "debounce",
-    quietWindowMs: 2500,
-    maxWaitMs: 12000,
-    maxMessages: 20,
-    maxChars: 8000,
-  },
-})
-```
-
-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`
-
-Telegram required secrets:
-
-```txt
-TELEGRAM_BOT_TOKEN
-TELEGRAM_WEBHOOK_SECRET
-```
-
-Zapster WhatsApp required secrets:
-
-```txt
-ZAPSTER_API_KEY
-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:
+Run `agentkit env set AGENTKIT_WEBHOOK_SECRET --stdin`, `agentkit channels list`, and `agentkit dev`. POST authenticated fixtures to `/channels/inbox/webhook`. Generic webhooks accept bearer/header secrets or raw-body HMAC. Other providers use `/channels/<name>/<type>/<provider>/webhook` and their own signature/token contracts.
 
-```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:
+Only authenticated channel webhook routes accept public HTTPS tunnel hosts. Non-webhook APIs stay loopback-only. Register provider webhooks manually, and keep the local process running. The dev UI supports chat; it does not include a channel dashboard. Inspect webhook responses and `agentkit conversations trace <id>` for diagnostics.
 
-```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.
+Buffers and duplicate tracking are in-memory and best-effort. Restarting the process loses pending buffered messages and deduplication state. There is no durable queue, retry worker, or buffer-management API. Discord interaction replies run inline and can exceed Discord's deadline with slow providers. No Discord Gateway worker is included; bot-mode events require an external bridge.
 
-Multiple webhooks are multiple named channels:
+Declare secret names through channel helpers and store values in ignored `.env`. Use `replyTo` to route replies to another configured channel, and `webhookOutputChannel` for public HTTPS callback destinations. Output URLs and auth values come from local secrets; SSRF guards reject private-network targets.
 
-```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:
+Telegram and WhatsApp adapters support configured audio transcription. Declare top-level `transcription` and channel `audio: { mode: "transcribe" }`. Media download and transcription run locally with the configured external provider. Signature checks, trusted download origins, and byte/duration limits still apply. Discord and Slack audio are unsupported.
 
-```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
-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 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`, `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`.
+See `docs/guides/add-channel.md`, the provider-specific guides, `docs/guides/channel-security.md`, and `docs/guides/debug-channel.md` for setup and verification.
 
 ## Tool Contract
 
@@ -666,7 +429,7 @@ Tool runtime rules:
 - 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
+## Database Tools And Local Storage
 
 For agent-owned application tables, `schema.sql` is the single source of truth.
 
@@ -678,12 +441,6 @@ Local behavior:
 - before a tool runs, AgentKit applies `schema.sql` locally;
 - use `agentkit db migrate`, `agentkit db reset --yes`, `agentkit db seed [--file seed.sql]`, and `agentkit db shell` for local setup and inspection.
 
-Hosted behavior:
-
-- `agentkit deploy` builds and deploys the capsule;
-- AgentKit migrates/provisions hosted storage internally and applies the same `schema.sql`;
-- the user should not create hosted databases, buckets, or runtimes manually.
-
 Example `schema.sql`:
 
 ```sql
@@ -772,61 +529,7 @@ Agent-owned tables from `schema.sql` live in the same SQLite file locally. Runti
 
 ## Inspect Contract
 
-Run:
-
-```sh
-agentkit inspect
-```
-
-Example output:
-
-```json
-{
-  "agent": "demo",
-  "runtime": "local",
-  "provider": {
-    "name": "test",
-    "model": "fake"
-  },
-  "prompt": "prompts/instructions.md",
-  "tools": [],
-  "access": {
-    "mode": "private"
-  },
-  "storage": ".agentkit/agentkit.db",
-  "database": {
-    "local": {
-      "driver": "sqlite",
-      "path": ".agentkit/agentkit.db",
-      "schema": "./schema.sql"
-    },
-    "hosted": {
-      "driver": "turso",
-      "provisioning": "agentkit-managed",
-      "schema": "./schema.sql"
-    }
-  },
-  "secrets": {},
-  "managedSecrets": ["TURSO_AUTH_TOKEN", "TURSO_DATABASE_URL"],
-  "userSecrets": [],
-  "runtimeContract": {
-    "local": {
-      "environment": "local",
-      "target": "bun",
-      "database": "sqlite"
-    },
-    "hosted": {
-      "environment": "hosted",
-      "target": "cloudflare",
-      "database": "turso",
-      "providerSupported": true
-    },
-    "aliases": ["ctx.db", "ctx.database", "ctx.storage.sql"]
-  }
-}
-```
-
-Secret values never appear. Each declared user secret appears as `set` or `missing`. `managedSecrets` are provisioned and injected by AgentKit Cloud; users do not put those values in local `.env`.
+`agentkit inspect` reports the local runtime, provider, tools, channels, transcription, knowledge, SQLite path/schema/migrations, skill status, and missing secret names. Secret values never appear. There is no remote storage provisioning.
 
 ## Dev Server Contract
 
@@ -934,61 +637,9 @@ For date-sensitive evals, set top-level `now` to an ISO timestamp with an explic
 
 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:
+## Improve From Local Conversations
 
-```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`
+See `docs/guides/improve-local.md` and `docs/guides/replay-local-traces.md`. Collect local traces, generate regression evals, change capsule files, and replay before accepting a fix.
 
 ## Security Rules
 
@@ -1013,83 +664,9 @@ prompts/
 docs/
 ```
 
-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
-
-For the coding agent and user, deploy is one command. Do not ask the user to choose a hosting target.
-
-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
-agentkit deploy smoke --message "hello"
-agentkit chat-ui --deploy
-```
-
-`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 when the owner gives you a non-default AgentKit Cloud API URL.
-
-Account/access flow:
-
-```sh
-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
-```
-
-Production storage uses `storage.driver: "agentkit"`. `.env` is never uploaded.
-
-Hosted backend responses use this error envelope:
-
-```json
-{
-  "error": {
-    "code": "secret_not_found",
-    "message": "Secret OPENAI_API_KEY is not set for this deploy.",
-    "request_id": "req_123",
-    "details": {
-      "secret": "OPENAI_API_KEY"
-    }
-  }
-}
-```
-
-Common hosted error codes:
-
-```txt
-unauthorized
-forbidden
-not_found
-validation_error
-conflict
-rate_limited
-quota_exceeded
-secret_not_found
-access_token_invalid
-deploy_not_ready
-deploy_paused
-tool_timeout
-provider_error
-internal_error
-```
-
 ## Troubleshooting
 
 Missing `@andreprado/agentkit` types:
@@ -1143,3 +720,5 @@ tool_validation_error
 ```
 
 Check the tool call input against `inputSchema`.
+
+For existing capsules, read `docs/guides/local-only-migration.md` before upgrading.