@andreprado/agentkit 0.1.0-alpha.18 → 0.1.0-alpha.19

package/docs/guides/replay-production-traces.md

@@ -0,0 +1,72 @@
+# Replay Production Traces
+
+## Goal
+
+Run collected production or local traces against the local Agent Capsule before redeploying a fix.
+
+## When To Use This
+
+Use this after `agentkit improve collect` and before `agentkit deploy` whenever prompts, tools, Knowledge, provider config, or channel behavior changed because of production evidence.
+
+## Commands
+
+```sh
+agentkit replay .agentkit/improve/<run> --against local
+```
+
+Run the full local eval suite too:
+
+```sh
+npm run eval
+```
+
+## What Replay Checks
+
+Replay sends each collected user turn through the local capsule in eval mode:
+
+```txt
+ctx.runtime.environment === "eval"
+ctx.runtime.invocation === "eval"
+```
+
+This proves the current capsule can process the production turns without runtime errors. Generated eval files under `evals/regressions/` add committed behavior assertions.
+
+## Write Tool Safety
+
+Replay still runs the registered capsule tools. Any tool that can write externally must guard eval mode:
+
+```ts
+if (ctx.runtime.environment === "eval") {
+  return { sent: false, evalFixture: true };
+}
+```
+
+Do not depend on prompt wording alone to prevent side effects.
+
+## Deploy Gate
+
+Before redeploying a production fix:
+
+```sh
+npm run typecheck
+npm run agentkit -- inspect
+npm run eval
+agentkit replay .agentkit/improve/<run> --against local
+agentkit deploy --smoke "hello"
+```
+
+If replay fails, inspect the failed trace id in `.agentkit/improve/<run>/traces/`, patch the capsule, and rerun replay.
+
+## Troubleshooting
+
+`Replay failed`:
+
+Read the printed error and the matching trace file. Common causes are missing local secrets, unsafe tools that do not branch on eval mode, stale Knowledge sources, or provider differences.
+
+`Replay skipped`:
+
+The trace had no user message. It may still help diagnose delivery or deploy state, but it cannot be replayed as a conversation.
+
+`provider_model_unsupported`:
+
+The local provider config does not match the replay environment. Keep deterministic regression replay on `test/fake` unless the owner intentionally selected a real provider.

package/docs/guides/run-evals.md

@@ -22,6 +22,12 @@ Run evals:
 agentkit eval run
 ```
 
+If the capsule uses npm scripts and Windows PowerShell blocks `npm.ps1`, use:
+
+```sh
+npm.cmd run eval
+```
+
 Create an eval from a stored conversation:
 
 ```sh
@@ -31,6 +37,15 @@ agentkit eval from-conversation <conversation-id>
 agentkit eval run
 ```
 
+Create evals from hosted or local production evidence:
+
+```sh
+agentkit improve collect --deploy --since 24h
+agentkit improve evals .agentkit/improve/<run>
+agentkit replay .agentkit/improve/<run> --against local
+agentkit eval run
+```
+
 ## Files Created Or Edited
 
 Create or edit:
@@ -43,9 +58,11 @@ Use conversations as source material:
 
 ```txt
 .agentkit/agentkit.db
+.agentkit/improve/<run>/
 ```
 
 Do not edit `.agentkit/agentkit.db` by hand.
+Do not edit `.agentkit/improve/<run>/bundle.json` by hand.
 
 ## Minimal Working Example
 
@@ -200,6 +217,7 @@ export const sendFollowupEmail = defineTool({
 - Keep eval tool calls deterministic and non-destructive.
 - For tools that would write, delete, charge money, send email, or call a real customer system, branch inside the registered tool on `ctx.runtime.environment === "eval"` and return safe fixture output.
 - Treat conversations as source material, not as automatically safe training data.
+- Review generated regression evals from `agentkit improve evals` before committing them. AgentKit redacts common email, phone, bearer token, and key patterns in generated eval text, but you must still remove or generalize domain-specific client PII and replace brittle exact prose assertions with the important behavior when needed.
 
 ## Verification
 

package/docs/guides/security-rules.md

@@ -93,14 +93,14 @@ defineTool({
 - `.env.schema` is the committed contract for local secret names.
 - AgentKit local commands load `.env` directly so inspect, chat, tools, and evals share the same secret loader.
 - Production uses managed secrets.
-- Hosted alpha deploys require `cloudflare_deploy_alpha`; local commands do not require login.
+- Hosted deploys require `cloudflare_deploy_alpha` or purchased/manual deploy slots; local commands do not require login.
 - Secret values must not appear in config, docs, prompts, evals, logs, exports, or SQLite.
 - A tool receives only secrets listed in that tool.
 - Avoid direct `process.env` reads inside tools.
 - Use `permissions` to describe external capabilities.
 - Add timeouts to network tools.
-- Treat public deploy URLs as unauthenticated transport, not access control.
-- Use access tokens and limits for clients.
+- Treat hosted deploy URLs as addresses, not access control.
+- Use deploy access tokens for hosted chat, hosted conversation reads, hosted trace reads, and any client app that talks to AgentKit Cloud.
 - Remove client PII before writing evals.
 
 ## Verification
@@ -132,9 +132,9 @@ Add the secret name to the tool `secrets` field and set it locally:
 npm run agentkit -- inspect
 ```
 
-Public URL is reachable:
+Hosted URL is reachable without a token:
 
-Check hosted access mode. Default should be `private`.
+Treat this as a security bug. Hosted AgentKit Cloud routes should reject missing deploy tokens except authenticated channel webhook ingress.
 
 ## Backend Contracts Used
 

package/docs/guides/use-provider.md

@@ -21,6 +21,14 @@ npm run chat -- --message "hello"
 npm run agentkit -- inspect
 ```
 
+On Windows PowerShell, if `npm.ps1` is blocked by `PSSecurityException`, use the Windows command shim:
+
+```sh
+npm.cmd run typecheck
+npm.cmd run chat -- --message "hello"
+npm.cmd run agentkit -- inspect
+```
+
 ## Files Created Or Edited
 
 Edit:
@@ -77,6 +85,8 @@ provider: {
 secrets: ["OPENROUTER_API_KEY"],
 ```
 
+Prefer model ids or aliases listed by the installed Pi SDK when available, such as `~google/gemini-flash-latest`. If an OpenRouter model id is newer than the Pi model registry, AgentKit passes the id through to OpenRouter using Pi's OpenAI-compatible transport with conservative unknown-model metadata. The provider may still reject the request if the id is invalid, inaccessible, or does not support the tools/features the agent uses.
+
 ## UI Verification
 
 After the provider is configured and the local secret is set, test through chat and UI:
@@ -125,7 +135,7 @@ npm run agentkit -- inspect
 
 `provider_model_unsupported`:
 
-Use a model id known to the installed Pi SDK for that provider.
+For OpenAI or Anthropic, use a model id known to the installed Pi SDK for that provider. For OpenRouter, prefer a known Pi alias when possible; otherwise a raw OpenRouter model id is passed through and any remaining model error comes from OpenRouter.
 
 Provider returns auth failure:
 

package/docs/llms-full.txt

@@ -49,11 +49,16 @@ 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 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> <name> [--provider zapster|meta] [--mode interactions|bot] [--api <url>]
+agentkit channels connect <website|telegram|whatsapp|discord> <name> [--provider zapster|meta] [--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>]
@@ -66,8 +71,15 @@ 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 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>]
@@ -100,13 +112,9 @@ 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.
 
-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, validates toolkit auth configs 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. Managed external write actions require tool input `confirmed: true` by default unless the integration sets `confirmExternalWrites: false`. See `docs/guides/add-managed-composio.md`.
+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`.
 
-Planned commands described by the contract but not implemented yet:
-
-```sh
-agentkit eval from-conversation <conversation-id>
-```
+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. Managed external write actions require tool input `confirmed: true` by default unless the integration sets `confirmExternalWrites: false`. See `docs/guides/add-managed-composio.md`.
 
 ## Create And Test A Capsule
 
@@ -255,6 +263,8 @@ 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.
+
 ## 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.
@@ -304,7 +314,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:
 
@@ -329,7 +339,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, telegramChannel, whatsappChannel, websiteChannel } from "@andreprado/agentkit";
 
 export default defineAgent({
   name: "support-agent",
@@ -342,6 +352,8 @@ export default defineAgent({
     websiteChannel({ name: "website-chat" }),
     telegramChannel({ name: "support-telegram" }),
     whatsappChannel({ name: "support-whatsapp", provider: "zapster" }),
+    discordChannel({ name: "support-discord" }),
+    discordChannel({ name: "server-discord", mode: "bot" }),
   ],
   access: { mode: "public" },
   storage: { driver: "agentkit" },
@@ -377,6 +389,7 @@ whatsappChannel({
 Useful guides:
 
 - Add a channel: `docs/guides/add-channel.md`
+- Connect Discord: `docs/guides/connect-discord.md`
 - Connect Telegram: `docs/guides/connect-telegram.md`
 - Connect WhatsApp through Zapster: `docs/guides/connect-whatsapp-zapster.md`
 - Debug a channel: `docs/guides/debug-channel.md`
@@ -397,6 +410,18 @@ ZAPSTER_INSTANCE_ID
 ZAPSTER_WEBHOOK_ID
 ```
 
+Discord slash-command required secret:
+
+```txt
+DISCORD_PUBLIC_KEY
+```
+
+Discord bot-mode required secret:
+
+```txt
+DISCORD_BOT_TOKEN
+```
+
 Common channel verification:
 
 ```sh
@@ -404,6 +429,8 @@ agentkit inspect
 agentkit deploy
 agentkit channels list
 agentkit channels add telegram support-telegram
+agentkit channels connect discord support-discord
+agentkit channels connect discord server-discord --mode bot
 agentkit channels setup support-telegram
 agentkit channels test support-telegram --message "hello"
 agentkit channels test-audio support-telegram --fixture voice-note
@@ -414,6 +441,8 @@ 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`.
 
+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
@@ -755,6 +784,62 @@ 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:
+
+```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:
@@ -778,7 +863,7 @@ 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.
 
@@ -790,7 +875,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
@@ -798,7 +886,7 @@ 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`, 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, 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, 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 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, and writes the local chat/UI deploy access token to `.agentkit/chat-access-token.json` for 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, 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.
 
@@ -808,6 +896,7 @@ 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

package/docs/llms.txt

@@ -10,6 +10,8 @@ Task guides:
 - Add a TypeScript tool: `docs/guides/add-tool.md`
 - Add Knowledge from local docs/CSVs: `docs/guides/add-knowledge.md`
 - Run or prepare evals: `docs/guides/run-evals.md`
+- Improve from production traces: `docs/guides/improve-from-production.md`
+- Replay collected traces locally: `docs/guides/replay-production-traces.md`
 - Switch from `test/fake` to a real provider: `docs/guides/use-provider.md`
 - Prepare for hosted deploy: `docs/guides/prepare-deploy.md`
 - Build Cloudflare artifact: `agentkit build --target cloudflare`
@@ -18,6 +20,7 @@ Task guides:
 - Add hosted channels: `docs/guides/add-channel.md`
 - Add AgentKit-managed Composio: `docs/guides/add-managed-composio.md`
 - Buffer rapid channel messages: `docs/guides/add-channel.md#buffer-bursty-messages`
+- Connect Discord: `docs/guides/connect-discord.md`
 - Connect Telegram: `docs/guides/connect-telegram.md`
 - Connect WhatsApp through Zapster: `docs/guides/connect-whatsapp-zapster.md`
 - Follow channel webhook and delivery-log safety rules: `docs/guides/channel-security.md`
@@ -40,11 +43,16 @@ agentkit knowledge sync
 agentkit knowledge inspect
 agentkit knowledge search <query> [--top-k <number>]
 agentkit eval run
+agentkit improve collect --deploy --since 24h
+agentkit improve evals .agentkit/improve/<run>
+agentkit replay .agentkit/improve/<run> --against local
 agentkit conversations list
 agentkit conversations show <conversation-id>
 agentkit conversations trace <conversation-id> [--deploy]
 agentkit channels list
 agentkit channels add telegram support-telegram
+agentkit channels connect discord support-discord
+agentkit channels connect discord server-discord --mode bot
 agentkit channels setup support-telegram
 agentkit channels status support-telegram
 agentkit channels test support-telegram --message "hello"
@@ -55,7 +63,11 @@ agentkit integrations status [--toolkit googlecalendar]
 agentkit integrations connect composio --toolkit gmail
 agentkit skills status
 agentkit skills sync
+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 account token list
 agentkit deploy doctor
 agentkit deploy --smoke "hello"
 agentkit deploy status
@@ -71,6 +83,8 @@ agentkit dev
 agentkit open
 ```
 
+On Windows PowerShell, if `npm.ps1` or `npx.ps1` is blocked with `PSSecurityException`, run capsule scripts through the `.cmd` shims, for example `npm.cmd run agentkit -- inspect`, `npm.cmd run agentkit -- knowledge sync`, or `npm.cmd run eval`.
+
 Generated capsules include `AGENTKIT.md`, `AGENTS.md`, and a repo-local `skills/` pack so Codex, Claude Code, or another coding agent can treat the owner's natural-language request as the brief and start building immediately without loading the full contract by default. Start with `skills/agentkit-capsule/SKILL.md`, then load the task skill for the current work. `agentkit handoff codex "Develop an ophthalmology office intake agent"` is an optional prompt-printing shortcut for users who are not already inside a coding-agent workspace. There is no wizard or recipe layer: the coding agent edits the capsule directly from the scaffold and contract.
 
 UI testing is part of the handoff. For local UI testing, run `agentkit dev`, open the printed `Chat:` URL, and tell the owner the exact URL. After hosted deploy, run `agentkit chat-ui --deploy`, open the printed `Chat:` URL, and tell the owner it is connected to the deploy.
@@ -79,6 +93,8 @@ Hosted Chat UI shows the current conversation id, tool calls, tool errors, and a
 
 `test/fake` is deterministic and validates scaffold, direct tool calls, and fake-provider evals. 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.
 
+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.
+
 AgentKit injects the current ISO timestamp, local date, weekday, local date/time, and timezone dynamically into every chat run. Set `timeZone` in `agentkit.config.ts` for scheduling agents so "today", "tomorrow", and weekdays resolve in the business/user timezone; otherwise AgentKit falls back to `AGENTKIT_TIME_ZONE`, valid `TZ`, then the runtime default. Do not hardcode today's date in prompts.
 
 Current local endpoints from `agentkit dev`:
@@ -91,4 +107,4 @@ GET  /v1/conversations/:id
 GET  /v1/conversations/:id/trace
 ```
 
-Local `.env` is for development only. Use `.env.schema` as the committed secret-name contract; local AgentKit commands load `.env` directly. Hosted alpha deploys require `cloudflare_deploy_alpha` through `agentkit login --token ...`; production uses managed secrets in the hosted contract.
+Local `.env` is for 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. Use `agentkit billing checkout` + `agentkit billing claim` for first-time paid access, or `agentkit login --token ...` when the user already has an `agk_user_...` token. Production uses managed secrets in the hosted contract.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andreprado/agentkit",
-  "version": "0.1.0-alpha.18",
+  "version": "0.1.0-alpha.19",
   "private": false,
   "type": "module",
   "repository": {

package/src/cli/args.ts

@@ -4,6 +4,15 @@ export type ParsedArgs = {
   flags: Record<string, string | boolean>;
 };
 
+const dashPrefixedValueFlags = new Set([
+  "brief",
+  "input",
+  "input-json",
+  "message",
+  "prompt",
+  "smoke",
+]);
+
 export function parseArgs(argv: string[]): ParsedArgs {
   const [command, ...rest] = argv;
   const positional: string[] = [];
@@ -12,15 +21,27 @@ export function parseArgs(argv: string[]): ParsedArgs {
   for (let index = 0; index < rest.length; index += 1) {
     const value = rest[index];
 
+    if (value === "--") {
+      positional.push(...rest.slice(index + 1));
+      break;
+    }
+
     if (!value.startsWith("--")) {
       positional.push(value);
       continue;
     }
 
-    const name = value.slice(2);
+    const equalsIndex = value.indexOf("=");
+    const name = equalsIndex === -1 ? value.slice(2) : value.slice(2, equalsIndex);
+
+    if (equalsIndex !== -1) {
+      flags[name] = value.slice(equalsIndex + 1);
+      continue;
+    }
+
     const next = rest[index + 1];
 
-    if (next && !next.startsWith("--")) {
+    if (next && (dashPrefixedValueFlags.has(name) || !next.startsWith("--"))) {
       flags[name] = next;
       index += 1;
     } else {

package/src/cli/cloud-client.ts

@@ -47,6 +47,7 @@ export type CloudManagedComposioResponse = {
       toolkit?: string;
       auth_config_env?: string;
       auth_config?: "set" | "missing" | string;
+      auth_config_source?: "project" | "account" | "global" | "env" | string;
     }>;
   };
 };
@@ -84,6 +85,68 @@ export type DeployAccessTokenListResponse = {
   }>;
 };
 
+export type AccountApiTokenCreateResponse = {
+  token?: {
+    id?: string;
+    account_id?: string;
+    name?: string;
+    token?: string;
+    created_at?: string;
+    expires_at?: string;
+    last_used_at?: string;
+  };
+};
+
+export type AccountApiTokenListResponse = {
+  tokens?: Array<{
+    id?: string;
+    account_id?: string;
+    name?: string;
+    created_at?: string;
+    expires_at?: string;
+    last_used_at?: string;
+    revoked_at?: string;
+  }>;
+};
+
+export type BillingCheckoutResponse = {
+  checkout?: {
+    id?: string;
+    url?: string;
+  };
+  billing_intent?: {
+    id?: string;
+    account_id?: string;
+    email?: string;
+    requested_slots?: number;
+    status?: string;
+    secret?: string;
+  };
+};
+
+export type BillingCheckoutIntentResponse = {
+  billing_intent?: {
+    id?: string;
+    account_id?: string;
+    email?: string;
+    requested_slots?: number;
+    status?: string;
+    checkout_session_id?: string;
+    stripe_customer_id?: string;
+    stripe_subscription_id?: string;
+    completed_at?: string;
+    token_claimed_at?: string;
+  };
+};
+
+export type BillingClaimResponse = BillingCheckoutIntentResponse & AccountApiTokenCreateResponse;
+
+export type BillingPortalResponse = {
+  portal?: {
+    url?: string;
+  };
+};
+
 export type CloudSecretsResponse = {
   secrets?: Array<{
     name?: string;