@andreprado/agentkit 0.1.0-alpha.9 → 0.1.1

package/docs/guides/connect-whatsapp-evolution.md

@@ -0,0 +1,121 @@
+# Connect WhatsApp Through Evolution API
+
+## Goal
+
+Connect a self-hosted Evolution API WhatsApp instance to a hosted AgentKit WhatsApp channel.
+
+## When To Use It
+
+Use this after `whatsappChannel({ name: "main-whatsapp", provider: "evolution" })` exists in `agentkit.config.ts` and the capsule has been deployed.
+
+## Commands
+
+```sh
+agentkit deploy
+agentkit channels connect whatsapp main-whatsapp --provider evolution
+agentkit channels status main-whatsapp
+agentkit channels test main-whatsapp --message "hello"
+agentkit channels deliveries list main-whatsapp
+agentkit channels buffers list main-whatsapp
+```
+
+Required secrets:
+
+```txt
+EVOLUTION_API_BASE_URL
+EVOLUTION_API_KEY
+EVOLUTION_INSTANCE_NAME
+EVOLUTION_WEBHOOK_TOKEN
+```
+
+If WhatsApp audio transcription is enabled, also set the transcription provider secret declared by `agentkit inspect`, usually `OPENAI_API_KEY` or `GROQ_API_KEY`.
+
+## Minimal Working Example
+
+```ts
+import { defineAgent, whatsappChannel } from "@andreprado/agentkit";
+
+export default defineAgent({
+  name: "my-agent",
+  runtime: "edge",
+  provider: { name: "test", model: "fake" },
+  instructions: "./prompts/instructions.md",
+  secrets: [],
+  tools: [],
+  channels: [whatsappChannel({ name: "main-whatsapp", provider: "evolution" })],
+  access: { mode: "public" },
+  storage: { driver: "agentkit" },
+});
+```
+
+## Setup Behavior
+
+`agentkit channels connect whatsapp main-whatsapp --provider evolution` creates or updates the hosted channel, verifies managed secrets, calls Evolution API `POST /webhook/set/{instance}`, confirms the configured webhook through `GET /webhook/find/{instance}`, then runs a synthetic inbound smoke.
+
+Expected webhook URL shape:
+
+```txt
+https://<deploy-host>/channels/main-whatsapp/whatsapp/evolution/webhook
+```
+
+AgentKit registers the webhook URL with the required token query parameter:
+
+```txt
+https://<deploy-host>/channels/main-whatsapp/whatsapp/evolution/webhook?token=<EVOLUTION_WEBHOOK_TOKEN>
+```
+
+`EVOLUTION_API_BASE_URL` must be the public HTTPS origin for the Evolution API server, for example `https://evolution.example.com`. AgentKit rejects HTTP, localhost, private-network, link-local, metadata, and credential-bearing base URLs before sending `EVOLUTION_API_KEY`.
+
+## Audio
+
+Use `transcription` at the agent level and `audio.mode: "transcribe"` on the Evolution channel.
+
+```ts
+whatsappChannel({
+  name: "main-whatsapp",
+  provider: "evolution",
+  audio: {
+    mode: "transcribe",
+  },
+})
+```
+
+Evolution audio webhooks become normalized audio messages. The retryable channel worker downloads media through Evolution API `POST /chat/getBase64FromMediaMessage/{instance}` and sends the bytes to AgentKit's configured transcription provider.
+
+## Safety Rules
+
+- Keep phone numbers redacted in logs by default.
+- Do not store Evolution API keys or webhook tokens in `agentkit.config.ts`.
+- `EVOLUTION_WEBHOOK_TOKEN` is required because AgentKit V1 does not rely on an Evolution webhook body-signature contract.
+- AgentKit ignores `fromMe` messages to avoid reply loops.
+- Text replies call Evolution API `POST /message/sendText/{instance}` with the `apikey` header and a body containing `number` and `text`.
+- Real provider success is recorded as `provider_sent` only when Evolution returns a provider message id.
+- Only set `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` in tests when Evolution should not receive a real message. Dry-run deliveries are recorded as `adapter_stubbed`, not sent.
+
+## Verification
+
+```sh
+agentkit channels setup main-whatsapp --apply
+agentkit channels status main-whatsapp
+agentkit channels test main-whatsapp --message "hello"
+agentkit channels test-audio main-whatsapp --fixture voice-note
+agentkit channels deliveries list main-whatsapp
+agentkit channels deliveries show <delivery-id>
+```
+
+## Troubleshooting
+
+`channel_secret_missing`:
+Set `EVOLUTION_API_BASE_URL`, `EVOLUTION_API_KEY`, `EVOLUTION_INSTANCE_NAME`, and `EVOLUTION_WEBHOOK_TOKEN` as hosted managed secrets.
+
+`channel_signature_invalid`:
+The Evolution webhook query token does not match.
+
+`channel_provider_setup_invalid`:
+`EVOLUTION_API_BASE_URL` is not an allowed public HTTPS base URL.
+
+`channel_provider_setup_failed`:
+AgentKit could not configure or verify the Evolution webhook through `/webhook/set/{instance}` and `/webhook/find/{instance}`.
+
+`channel_audio_download_unavailable`:
+Evolution did not return base64 media data from `/chat/getBase64FromMediaMessage/{instance}`, or the audio payload did not include a provider message id.

package/docs/guides/connect-whatsapp-uazapi.md

@@ -0,0 +1,139 @@
+# Connect WhatsApp Through UAZAPI
+
+## Goal
+
+Connect a UAZAPI WhatsApp instance to an AgentKit WhatsApp channel locally or when hosted.
+
+## When To Use It
+
+Use this after `whatsappChannel({ name: "support-whatsapp", provider: "uazapi" })` exists in `agentkit.config.ts`.
+
+## Commands
+
+```sh
+node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))" | agentkit env set UAZAPI_WEBHOOK_TOKEN --stdin
+agentkit dev
+```
+
+Required secrets:
+
+```txt
+UAZAPI_BASE_URL
+UAZAPI_TOKEN
+UAZAPI_WEBHOOK_TOKEN
+```
+
+If WhatsApp audio transcription is enabled, also set the transcription provider secret declared by `agentkit inspect`, usually `OPENAI_API_KEY` or `GROQ_API_KEY`.
+
+## Minimal Working Example
+
+```ts
+import { defineAgent, whatsappChannel } from "@andreprado/agentkit";
+
+export default defineAgent({
+  name: "support-agent",
+  runtime: "edge",
+  provider: { name: "test", model: "fake" },
+  instructions: "./prompts/instructions.md",
+  secrets: [],
+  tools: [],
+  channels: [whatsappChannel({ name: "support-whatsapp", provider: "uazapi" })],
+  access: { mode: "public" },
+  storage: { driver: "agentkit" },
+});
+```
+
+## Local Usage
+
+`UAZAPI_WEBHOOK_TOKEN` is an AgentKit-owned secret, not a token issued by UAZAPI. Generate a different value for every channel and keep it in the ignored local `.env`:
+
+```sh
+node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))" | npm run agentkit -- env set UAZAPI_WEBHOOK_TOKEN --stdin
+npm run agentkit -- env set UAZAPI_BASE_URL --stdin
+npm run agentkit -- env set UAZAPI_TOKEN --stdin
+npm run agentkit -- dev
+```
+
+Expose the printed local port through an HTTPS tunnel, then register this exact URL with UAZAPI:
+
+```txt
+https://<tunnel-host>/channels/support-whatsapp/whatsapp/uazapi/webhook?token=<UAZAPI_WEBHOOK_TOKEN>
+```
+
+Configure UAZAPI with `addUrlEvents: false` and `addUrlTypesMessages: false` so it calls that exact URL. AgentKit allows a public tunnel host only on authenticated channel webhook paths; local chat, inspect, tools, files, and conversation APIs remain loopback-only.
+
+Send a real WhatsApp message after registration. A `200` response proves UAZAPI preserved the tokenized URL and AgentKit accepted it. A `channel_signature_invalid` response means the configured URL omitted, changed, or stripped the token. If the tunnel hostname changes, update the registered webhook URL.
+
+## Hosted Setup Behavior
+
+`agentkit channels connect whatsapp support-whatsapp --provider uazapi` creates or updates the hosted channel, verifies managed secrets, calls UAZAPI `/webhook`, confirms the configured webhook is listed by UAZAPI, then runs a synthetic inbound smoke.
+
+Expected webhook URL shape:
+
+```txt
+https://<deploy-host>/channels/support-whatsapp/whatsapp/uazapi/webhook
+```
+
+AgentKit requires `UAZAPI_WEBHOOK_TOKEN` and registers the webhook URL with the token query parameter:
+
+```txt
+https://<deploy-host>/channels/support-whatsapp/whatsapp/uazapi/webhook?token=<UAZAPI_WEBHOOK_TOKEN>
+```
+
+`UAZAPI_BASE_URL` must be an HTTPS UAZAPI instance URL, for example `https://api.uazapi.com`. AgentKit rejects localhost, private-network, link-local, metadata, and credential-bearing base URLs before sending `UAZAPI_TOKEN`.
+
+## Audio
+
+Use `transcription` at the agent level and `audio.mode: "transcribe"` on the UAZAPI channel.
+
+```ts
+whatsappChannel({
+  name: "support-whatsapp",
+  provider: "uazapi",
+  audio: {
+    mode: "transcribe",
+  },
+})
+```
+
+UAZAPI audio webhooks become normalized audio messages. The retryable channel worker downloads media through UAZAPI `/message/download` using `return_base64: true`; AgentKit does not fetch arbitrary webhook-provided media URLs.
+
+## Safety Rules
+
+- Keep phone numbers redacted in logs by default.
+- Do not store UAZAPI tokens in `agentkit.config.ts`.
+- Keep `UAZAPI_WEBHOOK_TOKEN` configured. UAZAPI V1 has no body-signature contract, so AgentKit rejects webhooks without the secret query token.
+- UAZAPI does not expose a documented webhook body-signature contract in AgentKit V1; the AgentKit-owned query token is the authentication layer.
+- Treat the complete tokenized URL as a secret and rotate `UAZAPI_WEBHOOK_TOKEN` if it appears in logs or screenshots.
+- AgentKit ignores `fromMe` and `wasSentByApi` messages to avoid reply loops.
+- Text replies call UAZAPI `POST /send/text` with the `token` header and a body containing `number`, `text`, `readchat`, `async`, `track_source`, and `track_id`.
+- Real provider success is recorded as `provider_sent` only when UAZAPI returns a provider message id.
+- Only set `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` in tests when UAZAPI should not receive a real message. Dry-run deliveries are recorded as `adapter_stubbed`, not sent.
+
+## Verification
+
+```sh
+agentkit channels setup support-whatsapp --apply
+agentkit channels status support-whatsapp
+agentkit channels test support-whatsapp --message "hello"
+agentkit channels test-audio support-whatsapp --fixture voice-note
+agentkit channels deliveries list support-whatsapp
+agentkit channels deliveries show <delivery-id>
+```
+
+## Troubleshooting
+
+`channel_secret_missing`:
+Set `UAZAPI_BASE_URL`, `UAZAPI_TOKEN`, and `UAZAPI_WEBHOOK_TOKEN` as secrets.
+
+`channel_signature_invalid`:
+The required UAZAPI webhook query token does not match.
+
+`channel_provider_setup_invalid`:
+`UAZAPI_BASE_URL` is not an allowed HTTPS public base URL.
+
+`channel_provider_setup_failed`:
+AgentKit could not configure or verify the UAZAPI webhook through `/webhook`.
+
+`channel_audio_download_unavailable`:
+UAZAPI did not return base64 media data from `/message/download`, or the audio payload did not include a provider message id.

package/docs/guides/connect-whatsapp-zapster.md

@@ -2,34 +2,45 @@
 
 ## Goal
 
-Connect a Zapster WhatsApp account to a hosted AgentKit WhatsApp channel.
+Connect a Zapster WhatsApp account to an AgentKit WhatsApp channel locally or when hosted.
 
 ## When To Use It
 
-Use this after `whatsappChannel({ name: "support-whatsapp", provider: "zapster" })` exists in `agentkit.config.ts` and the capsule has been deployed.
+Use this after `whatsappChannel({ name: "support-whatsapp", provider: "zapster" })` exists in `agentkit.config.ts`.
 
 ## Commands
 
 ```sh
-agentkit deploy
-agentkit channels add whatsapp support-whatsapp --provider zapster
-agentkit channels setup support-whatsapp
-agentkit channels status support-whatsapp
-agentkit channels test support-whatsapp --message "hello"
-agentkit channels deliveries list support-whatsapp --since 24h
+node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))" | agentkit env set ZAPSTER_WEBHOOK_TOKEN --stdin
+agentkit dev
 ```
 
 Required secrets:
 
 ```txt
 ZAPSTER_API_KEY
-ZAPSTER_WEBHOOK_SECRET
+ZAPSTER_INSTANCE_ID
+ZAPSTER_WEBHOOK_ID
+ZAPSTER_WEBHOOK_TOKEN
+```
+
+If WhatsApp audio transcription is enabled, also set the transcription provider secret declared by `agentkit inspect`, usually:
+
+```txt
+OPENAI_API_KEY
+```
+
+or:
+
+```txt
+GROQ_API_KEY
 ```
 
 ## Files Created Or Edited
 
 - `agentkit.config.ts`: `whatsappChannel({ name: "support-whatsapp", provider: "zapster" })`.
-- `.agentkit/deploy.json`: deploy state for resolving the hosted deploy.
+- `.env`: ignored local provider credentials and the AgentKit-owned webhook token.
+- `.agentkit/deploy.json`: deploy state only when using the hosted workflow.
 - No user-managed webhook server.
 
 ## Minimal Working Example
@@ -50,6 +61,28 @@ export default defineAgent({
 });
 ```
 
+## Local Usage
+
+`ZAPSTER_WEBHOOK_TOKEN` is an AgentKit-owned secret, not a token issued by Zapster. Generate a different value for every channel and keep it in the ignored local `.env`:
+
+```sh
+node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))" | npm run agentkit -- env set ZAPSTER_WEBHOOK_TOKEN --stdin
+npm run agentkit -- env set ZAPSTER_API_KEY --stdin
+npm run agentkit -- env set ZAPSTER_INSTANCE_ID --stdin
+npm run agentkit -- env set ZAPSTER_WEBHOOK_ID --stdin
+npm run agentkit -- dev
+```
+
+Expose the printed local port through an HTTPS tunnel, then register this exact URL with Zapster:
+
+```txt
+https://<tunnel-host>/channels/support-whatsapp/whatsapp/zapster/webhook?token=<ZAPSTER_WEBHOOK_TOKEN>
+```
+
+Zapster stores a complete webhook URL and sends `X-Instance-ID` and `X-Webhook-ID` with deliveries. AgentKit requires both expected IDs and the URL secret because those identifiers alone are not cryptographic authentication. AgentKit allows a public tunnel host only on authenticated channel webhook paths; local chat, inspect, tools, files, and conversation APIs remain loopback-only.
+
+Send a real WhatsApp message after registration. A `200` response proves Zapster preserved the tokenized URL and AgentKit accepted it. A `channel_signature_invalid` response means the URL token or expected Zapster IDs did not match. If the tunnel hostname changes, update the registered webhook URL.
+
 To handle clients who send several WhatsApp messages before waiting, enable channel buffering:
 
 ```ts
@@ -66,22 +99,82 @@ whatsappChannel({
 })
 ```
 
-## Setup Behavior
+## Auto Transcribe WhatsApp Audio
 
-`agentkit channels setup support-whatsapp` prints the stable AgentKit webhook URL. Paste it into Zapster webhook settings and configure Zapster to send the same shared secret as `ZAPSTER_WEBHOOK_SECRET`.
+Use `transcription` at the agent level and `audio.mode: "transcribe"` on the Zapster channel.
+
+```ts
+import { defineAgent, whatsappChannel } from "@andreprado/agentkit";
+
+export default defineAgent({
+  name: "support-agent",
+  runtime: "edge",
+  provider: { name: "openai", model: "gpt-5.4-mini" },
+  instructions: "./prompts/instructions.md",
+  transcription: {
+    provider: "openai",
+    model: "gpt-4o-mini-transcribe",
+    secret: "OPENAI_API_KEY",
+    language: "pt",
+    limits: {
+      maxDurationSeconds: 180,
+      maxBytes: 20_000_000,
+    },
+  },
+  channels: [
+    whatsappChannel({
+      name: "support-whatsapp",
+      provider: "zapster",
+      audio: {
+        mode: "transcribe",
+      },
+    }),
+  ],
+  access: { mode: "public" },
+  storage: { driver: "agentkit" },
+});
+```
+
+Processing order:
+
+1. AgentKit validates Zapster origin headers and the required webhook token.
+2. Zapster audio payloads become normalized audio messages.
+3. AgentKit records `audio_received` and enqueues a channel job before acknowledging Zapster.
+4. The retryable channel worker downloads the media URL from a trusted Zapster HTTPS host using `ZAPSTER_API_KEY`.
+5. AgentKit sends the audio bytes to the configured transcription provider using the user's managed secret.
+6. The agent run receives a text message with the transcript.
+
+Zapster payloads must include a media download URL such as `audio.downloadUrl`, `audio.url`, `audio.mediaUrl`, or the snake_case equivalents. The URL must be HTTPS and hosted by Zapster; AgentKit rejects arbitrary webhook-provided hosts before sending `ZAPSTER_API_KEY`. If Zapster sends only a media ID without a download URL, AgentKit records `channel_audio_download_unavailable` and does not create an agent run for that audio in V1.
+
+## Hosted Setup Behavior
+
+`agentkit channels setup support-whatsapp` prints the stable AgentKit webhook URL. Paste it into Zapster webhook settings.
 
 Expected webhook URL shape:
 
 ```txt
-https://<deploy-host>/channels/chn_<id>/whatsapp/zapster/webhook
+https://<deploy-host>/channels/support-whatsapp/whatsapp/zapster/webhook
+```
+
+AgentKit requires `ZAPSTER_WEBHOOK_TOKEN`; register the Zapster URL with the token as a query parameter:
+
+```txt
+https://<deploy-host>/channels/support-whatsapp/whatsapp/zapster/webhook?token=<ZAPSTER_WEBHOOK_TOKEN>
 ```
 
 ## Safety Rules
 
 - Keep phone numbers redacted in logs by default.
 - Do not store Zapster API keys in `agentkit.config.ts`.
-- Inbound validation uses `X-Zapster-Webhook-Secret`.
+- Inbound validation uses Zapster's `X-Instance-ID`, `X-Webhook-ID`, `X-Message-ID`, `X-Attempt-Count`, and `User-Agent: Zapsterapi/...` headers.
+- Zapster webhook headers are origin validation, not a cryptographic body signature.
+- Keep `ZAPSTER_WEBHOOK_TOKEN` in the webhook URL. Zapster's metadata headers are not a shared-secret signature, so AgentKit rejects webhooks without the secret query token.
+- Treat the complete tokenized URL as a secret and rotate `ZAPSTER_WEBHOOK_TOKEN` if it appears in logs or screenshots.
 - Unsupported media should be logged as skipped/unsupported without creating an agent run.
+- AgentKit handles Zapster `message.received` envelopes with event id at `id`, message text at `data.content.text`, and contact identity at `data.sender.id`.
+- Outbound replies call `POST https://api.zapsterapi.com/v1/wa/messages` with bearer auth and a JSON body containing `recipient`, `text`, and `instance_id`.
+- Real provider success is recorded as `provider_sent` only when Zapster returns a provider message ID.
+- Only set `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` in tests when Zapster should not receive a real message. Dry-run deliveries are recorded as `adapter_stubbed`, not sent.
 
 ## Verification
 
@@ -90,15 +183,25 @@ agentkit channels status support-whatsapp
 agentkit channels test support-whatsapp --message "hello"
 agentkit channels deliveries list support-whatsapp
 agentkit channels deliveries show <delivery-id>
+agentkit channels buffers list support-whatsapp
+agentkit channels buffers flush support-whatsapp <conversation-id>
+agentkit channels buffers clear support-whatsapp <conversation-id>
+agentkit channels buffers retry support-whatsapp <conversation-id>
 ```
 
 ## Troubleshooting
 
 `channel_secret_missing`:
-Set `ZAPSTER_API_KEY` and `ZAPSTER_WEBHOOK_SECRET` as hosted managed secrets.
+Set `ZAPSTER_API_KEY`, `ZAPSTER_INSTANCE_ID`, `ZAPSTER_WEBHOOK_ID`, and `ZAPSTER_WEBHOOK_TOKEN` as secrets.
 
 `channel_signature_invalid`:
-Zapster is not sending the expected webhook secret.
+Zapster is not sending the expected instance/webhook IDs, or the required query token does not match.
 
 `channel_unsupported_message_type` or skipped delivery:
 The inbound WhatsApp event was not supported text. Inspect the delivery record for provider metadata.
+
+`channel_audio_download_unavailable`:
+Zapster sent an audio event without a usable media download URL, or the URL was not an HTTPS Zapster media host. Configure Zapster to include a trusted Zapster media URL in webhook payloads, or add a Zapster media lookup adapter before enabling `audio.mode: "transcribe"`.
+
+`transcription_secret_missing`:
+Set `OPENAI_API_KEY`, `GROQ_API_KEY`, or the custom secret named in `transcription.secret` as a managed hosted secret.

package/docs/guides/create-agent.md

@@ -39,6 +39,31 @@ cd support-demo
 npm run agentkit -- tool lookup_order --input '{"orderId":"A100"}'
 ```
 
+`agentkit new` can prompt for the project folder name when run in an interactive terminal:
+
+```sh
+npx @andreprado/agentkit@alpha new
+```
+
+Use `.` to create the capsule in the current directory:
+
+```sh
+npx @andreprado/agentkit@alpha new . --template blank
+```
+
+## Windows PowerShell
+
+If PowerShell blocks `npm.ps1` or `npx.ps1` with `PSSecurityException`, run the same commands through the Windows command shims:
+
+```sh
+npx.cmd @andreprado/agentkit@alpha new demo --template blank
+npm.cmd run typecheck
+npm.cmd run chat -- --message "hello"
+npm.cmd run agentkit -- inspect
+```
+
+This keeps the capsule workflow the same without changing the machine-wide PowerShell execution policy.
+
 ## Files Created Or Edited
 
 Generated files:
@@ -76,7 +101,7 @@ Runtime files created after chat:
 
 ## Handoff To A Coding Agent
 
-The owner does not need to fill a separate brief file. The natural-language request they type into Codex, Claude Code, or another coding agent is the brief.
+The owner does not need to run a brief wizard or fill a separate brief file. The natural-language request they type into Codex, Claude Code, or another coding agent is the brief.
 
 Primary flow:
 
@@ -84,9 +109,9 @@ Primary flow:
 Develop an appointment and intake agent for an ophthalmology office.
 ```
 
-The generated `AGENTS.md`, `AGENTKIT.md`, `CLAUDE.md`, and `skills/` pack tell the coding agent which files to edit, which task skill to load, and which verification commands to run. There is no wizard or recipe layer: the coding agent edits the capsule directly from the scaffold, contract, and owner request. The default router is `skills/agentkit-capsule/SKILL.md`; `llms-full.txt` is reserved for complete-contract checks.
+The generated `AGENTS.md`, `AGENTKIT.md`, `CLAUDE.md`, and `skills/` pack tell the coding agent which files to edit, which task skill to load, and which verification commands to run. There is no AgentKit CLI wizard in the normal flow: the coding agent edits the capsule directly from the scaffold, contract, and owner request. The default router is `skills/agentkit-capsule/SKILL.md`; `llms-full.txt` is reserved for complete-contract checks.
 
-After the owner gives the general idea, the coding agent should create or update the implementation contract itself:
+After the owner gives the general idea inside the coding-agent chat, the coding agent should create or update the implementation contract itself:
 
 ```sh
 npm run agentkit -- spec init --brief "Develop an appointment and intake agent for an ophthalmology office."
@@ -95,6 +120,8 @@ npm run agentkit -- spec check
 
 `AGENT_SPEC.md` is an internal working contract for the coding agent. It is not a form the owner must fill before work starts.
 
+The coding agent should build a testable capsule, not only a prompt. For each meaningful requirement in the brief or `AGENT_SPEC.md`, decide whether it needs a prompt instruction, tool, schema/migration, fixture, eval, direct tool check, or deploy/readiness check. Privacy, confirmation, external writes, bookings, customer data, business hours, dates, and integration failures should have evals or deterministic checks before the capsule is called done.
+
 Optional shortcut when copying a prompt into another coding agent:
 
 ```sh
@@ -163,7 +190,7 @@ npm run agentkit -- chat-ui --deploy
 
 Open the printed `Chat:` URL and tell the owner this local UI is connected to the hosted deploy.
 
-`test/fake` is deterministic. It validates the scaffold, direct tool checks, and fake-provider evals, but it does not validate natural conversation quality. Before claiming real conversation behavior is tested, ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, or another supported provider.
+`test/fake` is deterministic. It validates the scaffold, direct tool checks, and fake-provider evals, but it does not validate natural conversation quality. Before claiming real conversation behavior is tested, ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go, or another supported provider.
 
 ## Safety Rules