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

package/src/templates/skills/agentkit-knowledge/templates/faq.md

@@ -0,0 +1,14 @@
+# FAQ
+
+## What services do you offer?
+
+Replace this answer with the owner's real services.
+
+## What are your hours?
+
+Replace this answer with the owner's real business hours.
+
+## How should users contact a human?
+
+Replace this answer with the owner's real escalation path.
+

package/src/templates/skills/agentkit-knowledge/templates/policies.md

@@ -0,0 +1,14 @@
+# Policies
+
+## Cancellation
+
+Replace this with the real cancellation policy.
+
+## Privacy
+
+Replace this with the real privacy policy.
+
+## Escalation
+
+Replace this with the real human handoff policy.
+

package/src/templates/skills/agentkit-knowledge/templates/prices.csv

@@ -0,0 +1,3 @@
+item,price,notes
+Example service,100,Replace with real prices before using in production
+

package/src/templates/skills/agentkit-prompts/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: agentkit-prompts
+description: Use when writing or revising AgentKit prompt files, especially prompts/instructions.md, including agent role, behavior, boundaries, escalation rules, tool-use policy, Knowledge policy, and user-facing tone.
+---
+
+# AgentKit Prompts
+
+Use this when editing `prompts/instructions.md`.
+
+## Prompt Checklist
+
+Include only behavior the runtime should apply on every conversation:
+
+- agent role and audience;
+- domain-specific goals;
+- what information to collect;
+- when to use tools;
+- when to search Knowledge;
+- how to interpret scheduling language such as today, tomorrow, and next Friday;
+- what the agent must not claim;
+- escalation and safety boundaries;
+- response style.
+
+AgentKit injects the current timestamp, local date, weekday, and timezone dynamically at runtime. Do not hardcode today's date in `prompts/instructions.md`; set `timeZone` in `agentkit.config.ts` when a scheduling agent needs a specific business/user timezone.
+
+Keep operational secrets, provider details, and implementation notes out of prompts.
+
+## Tool And Knowledge Policy
+
+- Use tools for actions, live data, authorization-sensitive records, payments, orders, booking, and writes.
+- Use Knowledge for committed reference facts such as FAQs, prices, services, policies, procedures, and CSV tables.
+- Do not expose raw tool output, retrieval JSON, chunk IDs, scores, secrets, logs, or internal labels.
+
+## Templates
+
+- `templates/knowledge-grounded-faq.instructions.md`
+- `../agentkit-build-agent/templates/support-agent.instructions.md`
+- `../agentkit-build-agent/templates/appointment-intake.instructions.md`
+
+## Verification
+
+```sh
+npm run chat -- --message "hello"
+npm run eval
+```
+
+If the provider is still `test/fake`, say prompt behavior was not tested with a real model.

package/src/templates/skills/agentkit-prompts/templates/knowledge-grounded-faq.instructions.md

@@ -0,0 +1,11 @@
+You are a knowledge-grounded FAQ agent.
+
+Use the configured Knowledge search before answering business-specific factual questions about services, prices, policies, procedures, or support rules.
+
+Rules:
+- Answer from the retrieved source material when available.
+- If the answer is not in the available sources, say that you do not have enough information.
+- Do not expose raw retrieval JSON, scores, chunk IDs, or internal source metadata.
+- Do not use Knowledge for secrets, credentials, live customer records, payments, or authorization-sensitive data.
+- Use tools for live or customer-specific lookups.
+

package/src/templates/skills/agentkit-provider/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: agentkit-provider
+description: Use when switching an AgentKit capsule from the deterministic test/fake provider to a real Pi-backed provider such as OpenAI, Anthropic, or OpenRouter, or when verifying provider secrets and model behavior.
+---
+
+# AgentKit Provider
+
+Use this when `test/fake` is no longer enough.
+
+## Rule
+
+Do not choose a real provider automatically. Ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, or another supported provider.
+
+## Workflow
+
+1. Edit `agentkit.config.ts`.
+2. Add required secret names to `secrets`.
+3. Add names to `.env.schema`.
+4. Set local secret values in ignored `.env` through AgentKit commands.
+5. Run inspect, chat, and UI checks.
+
+## Config Examples
+
+OpenAI:
+
+```ts
+provider: { name: "openai", model: "gpt-4o-mini" },
+secrets: ["OPENAI_API_KEY"],
+```
+
+Anthropic:
+
+```ts
+provider: { name: "anthropic", model: "claude-3-5-haiku-latest" },
+secrets: ["ANTHROPIC_API_KEY"],
+```
+
+OpenRouter:
+
+```ts
+provider: { name: "openrouter", model: "gpt-4o-mini" },
+secrets: ["OPENROUTER_API_KEY"],
+```
+
+Prefer OpenRouter model ids or aliases known to the installed Pi SDK, such as `~google/gemini-flash-latest`. If a raw OpenRouter id is newer than Pi's registry, AgentKit passes it through to OpenRouter with conservative unknown-model metadata; OpenRouter can still reject invalid, inaccessible, or unsupported models.
+
+## Verification
+
+```sh
+npm run typecheck
+npm run agentkit -- inspect
+npm run chat -- --message "hello"
+npm run dev
+```
+
+On Windows PowerShell, if `npm.ps1` is blocked with `PSSecurityException`, use `npm.cmd run typecheck`, `npm.cmd run agentkit -- inspect`, and `npm.cmd run chat -- --message "hello"`.
+
+Open the printed `Chat:` URL and report it to the owner.
+
+Do not import provider SDKs in the capsule. AgentKit resolves providers internally through Pi-backed adapters.

package/src/templates/skills/agentkit-security/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: agentkit-security
+description: Use before or during AgentKit work involving secrets, external APIs, tools, evals from real data, public access, hosted deploys, or messaging channels.
+---
+
+# AgentKit Security
+
+Use this as a guardrail skill.
+
+## Never Commit
+
+```txt
+.env
+.agentkit/
+node_modules/
+```
+
+Secret values must not appear in:
+
+```txt
+agentkit.config.ts
+.env.schema
+AGENTS.md
+AGENTKIT.md
+CLAUDE.md
+README.md
+prompts/
+evals/
+docs/
+skills/
+```
+
+## Rules
+
+- `.env.schema` stores secret names only.
+- Ignored `.env` stores local development values only.
+- Hosted production uses managed secrets.
+- Tools receive only secrets listed in that tool's `secrets` field.
+- Prefer `ctx.secrets` over direct `process.env` reads in tools.
+- Add `permissions` for external capabilities.
+- Add timeouts to network tools.
+- Remove client PII before writing evals.
+- Keep `.agentkit/improve/` bundles out of commits and review generated regression evals before committing.
+- Guard replay/eval mode inside external write tools with `ctx.runtime.environment === "eval"`.
+- Treat hosted deploy URLs as addresses, not access control. Hosted chat, conversation reads, and trace reads require a deploy access token even if a config says `access.mode: "public"`.
+
+## Checks
+
+```sh
+git status --short
+npm run agentkit -- env list
+npm run agentkit -- inspect
+git diff --check
+```
+
+Expected: secret names may appear, secret values do not.

package/src/templates/skills/agentkit-tools/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: agentkit-tools
+description: Use when adding, changing, registering, or testing AgentKit TypeScript tools with defineTool, including external APIs, local actions, input/output schemas, tool secrets, permissions, timeouts, and eval-safe side effects.
+---
+
+# AgentKit Tools
+
+Use this when the agent needs code, an API, live data, a write, or an external action.
+
+## Workflow
+
+1. Create or edit `tools/<name>.ts`.
+2. Export a `defineTool` tool with `name`, `description`, `inputSchema`, and usually `outputSchema`.
+3. Add `secrets`, `permissions`, and `timeoutMs` when needed.
+4. Register the tool in `agentkit.config.ts`.
+5. Keep secret names in `.env.schema`; values stay in ignored `.env` or hosted managed secrets.
+6. Use `ctx.clock` for date-sensitive tool logic instead of calling `new Date()` directly.
+7. Add eval guards for destructive or external side effects.
+
+## Examples
+
+- `examples/lookup-order.tool.md`: simple lookup
+- `examples/database-write.tool.md`: write through `ctx.db`
+- `examples/eval-safe-external-action.tool.md`: safe eval branch for external side effects
+
+Use `skills/agentkit-database/SKILL.md` for database-backed tools.
+Use `skills/agentkit-security/SKILL.md` before adding external APIs or secrets.
+
+## Verification
+
+```sh
+npm run typecheck
+npm run agentkit -- tool <tool_name> --input '<json>'
+npm run agentkit -- inspect
+```
+
+Expected: input/output validation passes, tool calls persist, and no secret values appear in output or stored data.

package/src/templates/skills/agentkit-tools/examples/database-write.tool.md

@@ -0,0 +1,35 @@
+# Database Write Tool
+
+Copy the code into a real tool file and make sure `schema.sql` contains the target table.
+
+```ts
+import { defineTool } from "@andreprado/agentkit";
+
+export const saveNote = defineTool({
+  name: "save_note",
+  description: "Saves a note in the AgentKit-managed database.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      content: { type: "string" },
+    },
+    required: ["content"],
+    additionalProperties: false,
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      id: { type: "string" },
+      content: { type: "string" },
+    },
+    required: ["id", "content"],
+    additionalProperties: false,
+  },
+  async execute(input: { content: string }, ctx) {
+    const id = crypto.randomUUID();
+    await ctx.db.execute("INSERT INTO notes (id, content) VALUES (?, ?)", [id, input.content]);
+    return { id, content: input.content };
+  },
+});
+```
+

package/src/templates/skills/agentkit-tools/examples/eval-safe-external-action.tool.md

@@ -0,0 +1,37 @@
+# Eval-Safe External Action Tool
+
+Use this pattern for tools that send email, call customer systems, charge money, delete data, or perform other external side effects.
+
+```ts
+import { defineTool } from "@andreprado/agentkit";
+
+export const sendFollowupEmail = defineTool({
+  name: "send_followup_email",
+  description: "Sends a follow-up email after explicit confirmation.",
+  secrets: ["EMAIL_API_KEY"],
+  permissions: ["email:send"],
+  inputSchema: {
+    type: "object",
+    properties: {
+      email: { type: "string" },
+      confirmed: { type: "boolean" },
+    },
+    required: ["email", "confirmed"],
+    additionalProperties: false,
+  },
+  async execute(input: { email: string; confirmed: boolean }, ctx) {
+    if (!input.confirmed) {
+      return { sent: false, reason: "confirmation_required" };
+    }
+
+    if (ctx.runtime.environment === "eval") {
+      return { sent: false, evalFixture: true, email: input.email };
+    }
+
+    const apiKey = ctx.secrets.EMAIL_API_KEY;
+    // Call the real email provider with apiKey here.
+    return { sent: true, evalFixture: false, email: input.email };
+  },
+});
+```
+

package/src/templates/skills/agentkit-tools/examples/lookup-order.tool.md

@@ -0,0 +1,46 @@
+# Lookup Order Tool
+
+Copy the code into `tools/lookup-order.ts` and register `lookupOrder` in `agentkit.config.ts`.
+
+```ts
+import { defineTool } from "@andreprado/agentkit";
+
+const orders: Record<string, { status: string; eta: string }> = {
+  A100: { status: "preparing", eta: "today" },
+  B200: { status: "shipped", eta: "tomorrow" },
+};
+
+export const lookupOrder = defineTool({
+  name: "lookup_order",
+  description: "Looks up a demo support order by order id.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      orderId: { type: "string" },
+    },
+    required: ["orderId"],
+    additionalProperties: false,
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      orderId: { type: "string" },
+      found: { type: "boolean" },
+      status: { type: "string" },
+      eta: { type: "string" },
+    },
+    required: ["orderId", "found", "status", "eta"],
+    additionalProperties: false,
+  },
+  execute(input: { orderId: string }) {
+    const order = orders[input.orderId];
+    return {
+      orderId: input.orderId,
+      found: Boolean(order),
+      status: order?.status ?? "unknown",
+      eta: order?.eta ?? "unknown",
+    };
+  },
+});
+```
+

package/src/templates/skills/agentkit-troubleshooting/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: agentkit-troubleshooting
+description: Use when an AgentKit command, local chat, tool, eval, Knowledge sync, channel, or deploy fails and the coding agent needs to diagnose from CLI output and route to the right narrow skill or docs guide.
+---
+
+# AgentKit Troubleshooting
+
+Use this when something fails.
+
+## Workflow
+
+1. Read the exact error code and message.
+2. Run the narrow inspect command before guessing.
+3. Route to a task skill when the failure points to config, tools, database, provider, evals, deploy, Knowledge, or channels.
+4. Load `llms-full.txt` only when the narrow skill and guide do not explain the behavior.
+5. If the failure appears to be an AgentKit bug, missing docs, or unclear recovery path, create a local feedback draft after diagnosis.
+
+## First Commands
+
+```sh
+npm run agentkit -- inspect
+npm run agentkit -- skills status
+npm run typecheck
+npm run agentkit -- env list
+git status --short
+```
+
+For chat issues:
+
+```sh
+npm run chat -- --message "hello"
+```
+
+For tool issues:
+
+```sh
+npm run agentkit -- tool <tool_name> --input '<json>'
+```
+
+For deploy issues:
+
+```sh
+npm run agentkit -- deploy doctor
+```
+
+For AgentKit product feedback:
+
+```sh
+npm run agentkit -- feedback create --about last-run --kind bug --summary "short concrete summary"
+```
+
+For production behavior issues:
+
+```sh
+npm run agentkit -- improve collect --deploy --since 24h
+npm run agentkit -- improve evals .agentkit/improve/<run>
+npm run agentkit -- replay .agentkit/improve/<run> --against local
+```
+
+## Common Causes
+
+- missing dependencies: run `npm install`;
+- missing provider key: set ignored `.env` and confirm with `inspect`;
+- provider not chosen: stay on `test/fake` or ask the owner;
+- schema missing: run `db migrate` and check `schema.sql`;
+- tool validation failed: check `inputSchema` and `outputSchema`;
+- channel secret missing: set hosted managed secret, not source files;
+- production behavior drift: collect an improve bundle and convert it to regression evals before patching;
+- local AgentKit skills are stale: run `npm run agentkit -- skills sync`.
+
+## Feedback Rules
+
+- `feedback create` writes a local draft only; it does not send anything.
+- Review the draft before `feedback send`.
+- Sending requires `agentkit login --token agk_user_...`.
+- Do not paste `.env` values, provider keys, cookies, client PII, or full private transcripts into feedback.

package/src/templates/support.ts

@@ -63,6 +63,7 @@ node_modules/
         contents: `# Optional: add real provider keys after switching away from test/fake.
 OPENAI_API_KEY=
 ANTHROPIC_API_KEY=
+OPENROUTER_API_KEY=
 `,
       },
       {
@@ -110,7 +111,9 @@ export default defineAgent({
       },
       {
         path: "tools/lookup-order.ts",
-        contents: `const orders: Record<string, { status: string; eta: string }> = {
+        contents: `import type { AgentTool } from "@andreprado/agentkit";
+
+const orders: Record<string, { status: string; eta: string }> = {
   A100: { status: "preparing", eta: "today" },
   B200: { status: "shipped", eta: "tomorrow" },
 };
@@ -156,7 +159,7 @@ export const lookupOrder = {
       eta: order.eta,
     };
   },
-};
+} satisfies AgentTool;
 `,
       },
       {
@@ -168,13 +171,18 @@ Help users with clear answers. When order status is needed, use the lookup_order
       },
       {
         path: "evals/smoke.eval.ts",
-        contents: `export default {
+        contents: `import { defineEval } from "@andreprado/agentkit";
+
+export default defineEval({
   name: "smoke",
   input: "Say hello as a support agent.",
   expect: {
-    contains: "hello",
+    response: {
+      caseInsensitiveContains: "hello",
+      maxLength: 200,
+    },
   },
-};
+});
 `,
       },
       {
@@ -189,33 +197,48 @@ When the owner opens this folder in Codex, Claude Code, or another coding agent
 
 Start building immediately:
 
-- Read \`AGENTKIT.md\` and the full docs path from \`npm run agentkit -- docs full\`.
+- Start with \`skills/agentkit-capsule/SKILL.md\`, then use \`npm run agentkit -- docs llms\` as the docs router.
+- Create or update \`AGENT_SPEC.md\` from the owner's request with \`npm run agentkit -- spec init --brief "<owner request>"\`; the owner should not fill this file by hand before work starts.
 - Infer the first useful version from the owner's request.
 - Edit \`prompts/instructions.md\` for support behavior.
 - Edit \`agentkit.config.ts\` for provider, tools, secrets, access, and storage.
 - Add or replace TypeScript tools under \`tools/\` when the requested support agent needs actions or external data.
+- Add \`sync.ts\`, \`seed.sql\`, and ordered \`migrations/*.sql\` when the support agent depends on external catalogs or production-shaped data changes.
+- Do not wait for a wizard or recipe. AgentKit provides the scaffold and contract; you decide the implementation from the owner's brief.
 - Ask follow-up questions only when missing information blocks a safe local implementation.
 - State assumptions in the final response.
 
 ## Local Commands
 
-- \`npm install\`: install capsule dependencies.
+- \`npm install\`: restore capsule dependencies if this capsule used \`--no-install\`, install failed, or \`node_modules\` was deleted.
 - \`npm run chat -- --message "hello"\`: send one local chat message.
 - \`npm run agentkit -- tool lookup_order --input '{"orderId":"A100"}'\`: test the example tool directly.
 - \`npm run eval\`: run agent evals.
+- \`npm run agentkit -- spec check\`: verify the local agent implementation contract exists.
+- \`npm run agentkit -- eval from-conversation <conversation-id>\`: turn a real conversation into a regression eval.
+- \`npm run agentkit -- conversations trace <conversation-id>\`: inspect messages, runs, tool calls, inputs, outputs, rendered output, and final responses.
 - \`npm run dev\`: run the local Agent Capsule runtime.
 - \`npm run agentkit -- inspect\`: print machine-readable capsule state.
-- \`npm run agentkit -- env set <NAME> <VALUE>\`: write a local secret value to ignored \`.env\`.
+- \`printf %s "$VALUE" | npm run agentkit -- env set <NAME> --stdin\`: write a local secret value to ignored \`.env\` without putting it in shell history.
 - \`npm run agentkit -- env list\`: list local secret names without printing values.
-- \`npm run agentkit -- docs full\`: print the full AgentKit contract path.
+- \`npm run agentkit -- docs llms\`: print the lightweight AgentKit docs router.
+- \`npm run agentkit -- docs full\`: print the full AgentKit contract path only when a skill asks for it.
+
+## Testing With A UI
+
+- Local UI: run \`npm run dev\`, open the printed \`Chat:\` URL, and tell the owner the exact URL.
+- Hosted UI: after \`npm run agentkit -- deploy\`, run \`npm run agentkit -- chat-ui --deploy\`, open the printed \`Chat:\` URL, and tell the owner it is connected to the hosted deploy.
+- \`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 is tested, ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, or another supported provider. Do not choose for them.
 
 ## Hosted Deploy
 
 - Local scaffold, chat, eval, dev, inspect, tool, and build commands are token-free.
 - Hosted deploy requires an invited AgentKit Cloud alpha token. If no token is stored yet, ask the owner for one and run \`npm run agentkit -- login --token <token>\`.
-- Put production secret values into managed secrets with \`npm run agentkit -- secret set <NAME> <VALUE>\`, not into committed files.
+- Put production secret values into managed secrets with \`npm run agentkit -- secret set <NAME> --from-local-env\`, \`--from-env\`, or \`--stdin\`, not into committed files or shell history.
 - Deploy with \`npm run agentkit -- deploy\`, then check \`npm run agentkit -- deploy status\`.
-- Create client-facing deploy access tokens with \`npm run agentkit -- access token create <name>\` when a website or app needs to call the hosted agent.
+- Hosted deploy writes the local chat/UI deploy access token to \`.agentkit/chat-access-token.json\`. Create extra client-facing tokens with \`npm run agentkit -- access token create <name> --out <path>\` when a separate website or app needs its own credential.
+- Use \`npm run agentkit -- deploy --smoke "hello"\` or \`npm run agentkit -- deploy smoke --message "hello"\` for an official hosted chat smoke check.
 - Do not run operator/admin commands from a user capsule.
 
 ## Files
@@ -248,42 +271,71 @@ Example owner request:
 Turn the request into a working local capsule:
 
 - Update \`prompts/instructions.md\` with domain-specific behavior, boundaries, intake questions, and escalation rules.
+- Create or update \`AGENT_SPEC.md\` with \`npm run agentkit -- spec init --brief "<owner request>"\`. The owner gives the general idea; the coding agent turns it into the structured contract.
 - Update \`agentkit.config.ts\` when tools, secrets, provider, or access rules change.
 - Add, replace, or remove TypeScript tools under \`tools/\` for real actions or external data.
+- Use \`npm run agentkit -- sync init\` when the agent needs catalog sync, fixture seed data, or ordered migrations.
 - Keep the first version runnable with \`test/fake\` unless the owner explicitly asks for a real provider.
+- Do not use a wizard or recipe. Build the capsule directly from the scaffold, the AgentKit contract, and the owner's brief.
 - Make practical assumptions and list them in your final response.
 - Ask follow-up questions only when missing information blocks a safe local implementation.
 
 ## Local Commands
 
 \`\`\`sh
-npm install
 npm run typecheck
 npm run agentkit -- inspect
 npm run agentkit -- tool lookup_order --input '{"orderId":"A100"}'
 npm run eval
 \`\`\`
 
+\`test/fake\` proves the scaffold and deterministic tool paths. It does not prove natural conversation quality.
+
+\`agentkit new\` installs dependencies by default. Run \`npm install\` only if the capsule was created with \`--no-install\`, install failed, or \`node_modules\` was deleted.
+
 Set local development secrets without opening code:
 
 \`\`\`sh
-npm run agentkit -- env set OPENAI_API_KEY "<value>"
+printf %s "$OPENAI_API_KEY" | npm run agentkit -- env set OPENAI_API_KEY --stdin
 npm run agentkit -- inspect
 npm run chat -- --message "hello"
 \`\`\`
 
+## Testing With A UI
+
+Local UI:
+
+\`\`\`sh
+npm run dev
+\`\`\`
+
+Open the printed \`Chat:\` URL and tell the owner the exact URL.
+
+Hosted deploy UI:
+
+\`\`\`sh
+npm run agentkit -- deploy
+npm run agentkit -- chat-ui --deploy
+\`\`\`
+
+Open the printed \`Chat:\` URL and tell the owner this local UI is connected to the hosted deploy.
+
+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 they choose, update \`agentkit.config.ts\`, \`.env.schema\`, local secrets, hosted secrets if deploying, then rerun chat/UI checks.
+
 If you add a tool, also run a fake-provider tool smoke test:
 
 \`\`\`sh
 npm run agentkit -- tool tool_name --input '{}'
 \`\`\`
 
-For the full framework contract, read the path printed by:
+For the lightweight docs router, read the path printed by:
 
 \`\`\`sh
-npm run agentkit -- docs full
+npm run agentkit -- docs llms
 \`\`\`
 
+Read the full framework contract with \`npm run agentkit -- docs full\` only when a skill asks for it.
+
 ## Database Tools
 
 Tools that need agent-owned tables should use canonical \`ctx.db\` from the tool context. \`ctx.database\` and \`ctx.storage.sql\` are aliases. Do not import local database drivers or Node-only APIs in a tool.
@@ -305,9 +357,10 @@ This capsule is deploy-ready by default.
 1. Keep tools edge-safe and use \`ctx.db\` instead of importing database drivers.
 2. Run \`npm run agentkit -- build\` only when you want to validate the artifact locally.
 3. If the owner has not logged in yet, ask for an invited AgentKit Cloud alpha token and run \`npm run agentkit -- login --token <token>\`.
-4. Put production secrets into managed secrets with \`npm run agentkit -- secret set <NAME> <VALUE>\`.
+4. Put production secrets into managed secrets with \`npm run agentkit -- secret set <NAME> --from-local-env\`, \`--from-env\`, or \`--stdin\`.
 5. Run \`npm run agentkit -- deploy\`.
-6. Create client-facing deploy access tokens with \`npm run agentkit -- access token create <name>\` when a website or app needs to call the hosted agent.
+6. Run \`npm run agentkit -- chat-ui --deploy\` to test the hosted agent through a local UI using the auto-created \`.agentkit/chat-access-token.json\`. Create extra client-facing deploy access tokens with \`npm run agentkit -- access token create <name> --out <path>\` when a separate website or app needs its own credential.
+7. Use \`npm run agentkit -- deploy --smoke "hello"\` during deploy or \`npm run agentkit -- deploy smoke --message "hello"\` afterward for an official hosted smoke check.
 
 AgentKit owns hosted infrastructure and production secrets. Do not put production secret values in this capsule. Do not run operator/admin commands from a user capsule.
 `,
@@ -321,8 +374,10 @@ Use AgentKit conventions when editing this support capsule.
 - The agent contract lives in \`agentkit.config.ts\`.
 - The example tool lives in \`tools/lookup-order.ts\`.
 - The default provider is \`test/fake\`, which can call tools from JSON messages during local tests.
+- Ask the owner which real provider to use before switching from \`test/fake\`; do not choose OpenRouter, OpenAI, or Anthropic automatically.
 - Keep required local secret names in \`.env.schema\` and values in ignored \`.env\`. AgentKit local commands load \`.env\` directly.
 - Treat the owner's natural-language request as the brief and start implementing inside this capsule.
+- Start with \`skills/agentkit-capsule/SKILL.md\` when the task is not obvious.
 `,
       },
       {
@@ -334,14 +389,18 @@ Generated by AgentKit as a support Agent Capsule.
 ## Setup
 
 \`\`\`sh
-npm install
 npm run chat -- --message "hello"
 npm run agentkit -- tool lookup_order --input '{"orderId":"A100"}'
 npm run eval
 npm run dev
 \`\`\`
 
+\`agentkit new\` installs dependencies by default. Run \`npm install\` only if this capsule was created with \`--no-install\`, install failed, or \`node_modules\` was deleted.
+
 The support template includes a local \`lookup_order\` TypeScript tool and uses \`test/fake\` by default.
+\`test/fake\` does not validate real conversation quality. The owner must choose OpenRouter, OpenAI, Anthropic, or another supported provider before real model behavior is tested.
+
+For UI testing, run \`npm run dev\` and open the printed \`Chat:\` URL. After hosted deploy, run \`npm run agentkit -- chat-ui --deploy\` and open its printed \`Chat:\` URL.
 `,
       },
     ];