@andreprado/agentkit 0.1.0-alpha.10

package/docs/guides/agentkit-skills-architecture.md

@@ -0,0 +1,471 @@
+# AgentKit Skills Architecture
+
+## Recommendation
+
+Ship AgentKit skills as the default interface for the user's coding agent, while keeping the docs as the canonical source of truth.
+
+The current docs remain authoritative:
+
+```txt
+docs/llms.txt          short router
+docs/llms-full.txt     complete operating contract
+docs/guides/*.md       task guides
+```
+
+Skills should become the context-efficient working surface:
+
+```txt
+skills/agentkit-capsule/SKILL.md
+skills/agentkit-tools/SKILL.md
+skills/agentkit-deploy/SKILL.md
+...
+```
+
+The default agent path should be:
+
+```txt
+AGENTS.md
+  -> skills/agentkit-capsule/SKILL.md
+    -> one task skill
+      -> one reference, example, or template only when needed
+```
+
+Do not make `llms-full.txt` part of the default handoff. It is the full contract and should be loaded only for ambiguous framework behavior, internals work, or broad audits.
+
+## Problem
+
+`docs/llms-full.txt` is useful but too large for ordinary agent work. Loading it by default spends context on deploy, channels, backend contracts, evals, and storage details even when the owner only asked for a prompt change or one tool.
+
+The generated capsule files and `agentkit handoff` currently tell coding agents to read the full docs path. That is correct for completeness, but not for context economy.
+
+Skills solve this because they use progressive disclosure:
+
+- metadata is always discoverable;
+- `SKILL.md` loads only when the task matches;
+- examples, templates, scripts, and references load only when selected by the skill.
+
+## Product Contract
+
+AgentKit should ship skills out of the box for agents that support repo-local skills.
+
+Generated capsules should include:
+
+```txt
+skills/
+  agentkit-capsule/
+    SKILL.md
+    references/
+      docs-router.md
+```
+
+Template-specific and task-specific skills can live either:
+
+- inside the generated capsule, for maximum out-of-the-box usability; or
+- inside the installed AgentKit package, copied into the capsule by `agentkit new`.
+
+The generated capsule must still include `AGENTS.md`, `AGENTKIT.md`, `CLAUDE.md`, and `README.md` for agents or tools that do not support skills.
+
+## Skill Design Rules
+
+Each `SKILL.md` should be short and procedural. Target 300-800 words.
+
+Every skill should include:
+
+- when to use it;
+- files to inspect;
+- files it may edit;
+- exact commands;
+- safety rules;
+- verification;
+- links to optional references, examples, templates, or assets.
+
+Each skill should avoid:
+
+- duplicating whole guides;
+- copying large code examples into `SKILL.md`;
+- requiring `llms-full.txt` by default;
+- mixing user-capsule workflows with AgentKit maintainer/operator workflows.
+
+Use bundled resources this way:
+
+```txt
+references/   deeper task notes loaded only when needed
+examples/     source examples the agent may inspect
+templates/    starter files the agent may copy and adapt
+scripts/      deterministic helpers for fragile/repeated tasks
+assets/       files used as output resources
+```
+
+## Core Skills To Ship
+
+### agentkit-capsule
+
+The always-first router for work inside an Agent Capsule.
+
+Use when the agent detects `agentkit.config.ts` or the owner asks to build/change an AgentKit agent.
+
+Responsibilities:
+
+- establish the capsule root as the runtime boundary;
+- read `AGENTS.md` or `AGENTKIT.md`;
+- route to one task skill;
+- prefer `agentkit docs llms` over `agentkit docs full`;
+- load `llms-full.txt` only when the task needs the complete contract;
+- run the baseline checks before completion.
+
+Default verification:
+
+```sh
+npm run typecheck
+npm run agentkit -- inspect
+npm run chat -- --message "hello"
+```
+
+### agentkit-build-agent
+
+Use when the owner gives a natural-language brief for a new or changed agent.
+
+Responsibilities:
+
+- translate the brief into prompt, tools, schema, evals, and assumptions;
+- keep the first useful version runnable with `test/fake` unless the owner chooses a real provider;
+- create domain-specific local behavior without waiting for a wizard;
+- add evals for the expected first behavior.
+
+Likely templates:
+
+```txt
+templates/support-agent.instructions.md
+templates/appointment-intake.instructions.md
+templates/sales-qualifier.instructions.md
+templates/internal-operations.instructions.md
+```
+
+### agentkit-prompts
+
+Use when editing `prompts/instructions.md` or designing the agent's behavior.
+
+Responsibilities:
+
+- define role, boundaries, escalation rules, tone, and tool-use policy;
+- prevent false claims about actions not performed;
+- describe when to use Knowledge versus tools;
+- keep user-facing behavior specific to the owner's domain.
+
+Likely templates:
+
+```txt
+templates/knowledge-grounded-faq.instructions.md
+templates/appointment-intake.instructions.md
+templates/support-agent.instructions.md
+```
+
+### agentkit-tools
+
+Use when adding or changing TypeScript tools.
+
+Responsibilities:
+
+- create `defineTool` tools with input/output schemas;
+- register tools in `agentkit.config.ts`;
+- declare tool secrets and permissions;
+- add timeouts;
+- test tools directly;
+- keep eval runs deterministic and non-destructive.
+
+Likely examples:
+
+```txt
+examples/lookup-order.tool.ts
+examples/external-api-lookup.tool.ts
+examples/eval-safe-send-email.tool.ts
+```
+
+Primary reference: `docs/guides/add-tool.md`.
+
+### agentkit-database
+
+Use when adding agent-owned tables or database-backed tools.
+
+Responsibilities:
+
+- edit `schema.sql`;
+- keep schema changes idempotent;
+- use `ctx.db` in tools;
+- avoid local database driver imports;
+- run local migration/seed/shell checks;
+- preserve deploy-compatible `storage.driver: "agentkit"`.
+
+Likely templates:
+
+```txt
+templates/appointments.schema.sql
+templates/leads.schema.sql
+templates/tickets.schema.sql
+templates/notes.schema.sql
+```
+
+Primary reference: `docs/guides/add-tool.md` database section and `docs/guides/prepare-deploy.md`.
+
+### agentkit-knowledge
+
+Use when the agent should answer from committed source files such as FAQs, prices, policies, CSVs, and procedures.
+
+Responsibilities:
+
+- create `knowledge/` sources;
+- configure `knowledge.sources`;
+- choose lexical search by default;
+- configure embeddings only when needed;
+- verify with `knowledge sync` and `knowledge search`;
+- keep secrets and live customer data out of Knowledge.
+
+Likely templates:
+
+```txt
+templates/faq.md
+templates/prices.csv
+templates/policies.md
+```
+
+Primary reference: `docs/guides/add-knowledge.md`.
+
+### agentkit-provider
+
+Use when switching from `test/fake` to a real provider.
+
+Responsibilities:
+
+- ask the owner which provider to use;
+- update `agentkit.config.ts`;
+- update `.env.schema`;
+- set local secrets through AgentKit commands;
+- verify with chat, inspect, and UI;
+- never import provider SDKs into the capsule.
+
+Primary reference: `docs/guides/use-provider.md`.
+
+### agentkit-evals
+
+Use when adding or running evals.
+
+Responsibilities:
+
+- create `evals/*.eval.ts`;
+- use deterministic assertions;
+- verify persisted tool calls;
+- avoid real PII and secrets;
+- guard external side effects with `ctx.runtime.environment === "eval"`;
+- run `npm run eval`.
+
+Likely templates:
+
+```txt
+templates/smoke.eval.ts
+templates/tool-call.eval.ts
+templates/no-leak.eval.ts
+templates/knowledge-answer.eval.ts
+```
+
+Primary reference: `docs/guides/run-evals.md`.
+
+### agentkit-deploy
+
+Use when preparing or running hosted deploy.
+
+Responsibilities:
+
+- run readiness checks;
+- keep hosting target selection inside AgentKit;
+- use managed secrets, not committed `.env`;
+- run `deploy doctor`;
+- run `deploy --smoke`;
+- run hosted UI checks;
+- report production handoff details when deploy is ready.
+
+Primary reference: `docs/guides/prepare-deploy.md`.
+
+### agentkit-security
+
+Use before or during any work involving secrets, external APIs, tools, evals from conversations, public access, channels, or hosted deploys.
+
+Responsibilities:
+
+- prevent `.env`, `.agentkit/`, and secret values from being committed;
+- enforce secret-name-only config;
+- confirm tool secrets and permissions;
+- check access mode assumptions;
+- require redaction for client data.
+
+Primary reference: `docs/guides/security-rules.md`.
+
+### agentkit-channels
+
+Use when adding, connecting, testing, or debugging website, Telegram, or WhatsApp channels.
+
+Responsibilities:
+
+- add channel config helpers;
+- deploy before hosted channel creation;
+- manage provider secret names;
+- verify setup/status/test/delivery logs;
+- separate channels from tools;
+- debug webhook and delivery errors without leaking provider payloads.
+
+Likely references:
+
+```txt
+references/telegram.md
+references/whatsapp-zapster.md
+references/channel-debugging.md
+```
+
+Primary references:
+
+- `docs/guides/add-channel.md`
+- `docs/guides/connect-telegram.md`
+- `docs/guides/connect-whatsapp-zapster.md`
+- `docs/guides/debug-channel.md`
+- `docs/guides/channel-security.md`
+
+### agentkit-troubleshooting
+
+Use when AgentKit commands fail or the agent is unsure which task skill applies.
+
+Responsibilities:
+
+- start from the error code;
+- run `inspect`;
+- check config, secrets, package install, provider, storage, and channel state;
+- route to a more specific skill;
+- load `llms-full.txt` only when narrower references cannot explain the behavior.
+
+Primary reference: `docs/llms-full.txt` troubleshooting section.
+
+## Maintainer-Only Skills
+
+Do not ship these into user capsules by default:
+
+- control-plane deploy;
+- operator dashboard;
+- account grant/revoke;
+- backend contract implementation;
+- Cloudflare/Turso/R2 provisioning internals;
+- package publishing.
+
+Those workflows belong in maintainer skills inside the AgentKit repository, not in generated user capsules.
+
+Suggested maintainer skills:
+
+```txt
+skills/agentkit-maintainer-control-plane/
+skills/agentkit-maintainer-channels/
+skills/agentkit-maintainer-release/
+```
+
+## Generated Capsule Shape
+
+V1 generated capsules should contain:
+
+```txt
+AGENTS.md
+AGENTKIT.md
+CLAUDE.md
+README.md
+skills/
+  agentkit-capsule/
+    SKILL.md
+    references/
+      docs-router.md
+  agentkit-build-agent/
+    SKILL.md
+    templates/
+      support-agent.instructions.md
+      appointment-intake.instructions.md
+  agentkit-prompts/
+    SKILL.md
+    templates/
+      support-agent.instructions.md
+      knowledge-grounded-faq.instructions.md
+  agentkit-tools/
+    SKILL.md
+    examples/
+      lookup-order.tool.ts
+      database-write.tool.ts
+      eval-safe-external-action.tool.ts
+  agentkit-database/
+    SKILL.md
+    templates/
+      appointments.schema.sql
+      leads.schema.sql
+  agentkit-evals/
+    SKILL.md
+    templates/
+      smoke.eval.ts
+      tool-call.eval.ts
+  agentkit-deploy/
+    SKILL.md
+  agentkit-security/
+    SKILL.md
+```
+
+Channel, Knowledge, provider, and troubleshooting skills are copied into every generated capsule. Since skills are context-lazy, the main tradeoff is filesystem size, not context usage.
+
+## Handoff Changes
+
+Change generated `AGENTS.md` and `AGENTKIT.md` from:
+
+```txt
+Read AGENTKIT.md and the full docs path from npm run agentkit -- docs full.
+```
+
+To:
+
+```txt
+Start with skills/agentkit-capsule/SKILL.md.
+Use npm run agentkit -- docs llms as the docs router.
+Read npm run agentkit -- docs full only when a skill tells you the complete contract is needed.
+```
+
+Change `agentkit handoff codex|claude` so it points to:
+
+```txt
+Read these files first:
+- AGENTKIT.md
+- skills/agentkit-capsule/SKILL.md
+- the path printed by npm run agentkit -- docs llms
+```
+
+It should not include the concrete `llms-full.txt` path by default. It may mention that `llms-full.txt` exists for complete-contract checks.
+
+## CLI Packaging
+
+Keep the first version simple:
+
+```sh
+agentkit new <name> --template blank
+```
+
+The generated capsule receives the default skill pack automatically. Add `agentkit skills list/install` later only if users need to refresh or extend skill packs in existing capsules.
+
+## Acceptance Criteria
+
+The skills architecture is working when:
+
+- a new capsule contains a `skills/` directory;
+- `AGENTS.md` points to `skills/agentkit-capsule/SKILL.md`;
+- `agentkit handoff codex` points to the skill router and `docs llms`, not `llms-full.txt`;
+- ordinary prompt/tool/database tasks do not require loading `llms-full.txt`;
+- each skill has focused verification commands;
+- examples and templates live beside skills and are loaded only when needed;
+- docs remain canonical and tests still verify packaged docs sync;
+- user capsules do not include maintainer/operator skills by default.
+
+## Rollout Plan
+
+1. Add the default skill pack under `packages/agentkit/src/templates/skills` or another package-owned source directory.
+2. Update `blank`, `support`, and `dentista` templates to copy the skill pack.
+3. Update generated `AGENTS.md`, `AGENTKIT.md`, and `CLAUDE.md` to prefer skills and `docs llms`.
+4. Update `agentkit handoff` to prefer the skill router.
+5. Add tests that generated capsules contain the default skills and no longer nudge default handoff to `llms-full.txt`.
+6. Keep `agentkit docs full` available for complete-contract audits.

package/docs/guides/channel-security.md

@@ -0,0 +1,81 @@
+# Channel Security
+
+## Goal
+
+Keep channel webhooks, delivery logs, provider sends, and managed secrets safe by default.
+
+## When To Use It
+
+Use this before adding a channel provider, changing webhook validation, adding delivery logging, or enabling real-provider smoke tests.
+
+## Commands
+
+```sh
+agentkit inspect
+agentkit channels status <name>
+agentkit channels deliveries show <delivery-id>
+bun test packages/agentkit/src/runtime/channels/adapters.test.ts
+bun test packages/agentkit/src/runtime/deploy.test.ts
+```
+
+Real-provider gates are opt-in:
+
+```sh
+AGENTKIT_RUN_TELEGRAM_CHANNEL_TESTS=1 bun test
+AGENTKIT_RUN_ZAPSTER_CHANNEL_TESTS=1 bun test
+```
+
+Telegram smoke also requires `TELEGRAM_BOT_TOKEN`, `TELEGRAM_WEBHOOK_SECRET`, and `AGENTKIT_TELEGRAM_WEBHOOK_URL`.
+
+Zapster smoke also requires `ZAPSTER_API_KEY`, `AGENTKIT_ZAPSTER_SEND_URL`, and `AGENTKIT_ZAPSTER_TO`.
+
+## Files Created Or Edited
+
+- `agentkit.config.ts`: secret names only.
+- Managed hosted secrets: production secret values, no readback.
+- Delivery records: hashes, statuses, provider event IDs, redacted metadata.
+
+## Safety Rules
+
+- Public webhook URLs are not permission grants.
+- Validate provider authenticity when the provider supports it.
+- Do not store channel plumbing in the user's Turso database.
+- Do not store raw webhook bodies in delivery records; store a SHA-256 hash.
+- Redact bearer tokens, bot tokens, signing secrets, provider API tokens, and phone numbers.
+- Inject only channel-declared secrets into adapter code.
+- Prefer acknowledging Telegram/WhatsApp over retry storms when a channel-level limit is exceeded.
+
+## Minimal Working Example
+
+```ts
+telegramChannel({
+  name: "support-telegram",
+  secrets: ["TELEGRAM_BOT_TOKEN", "TELEGRAM_WEBHOOK_SECRET"],
+});
+```
+
+The config contains secret names only. Hosted responses report:
+
+```txt
+TELEGRAM_BOT_TOKEN: set
+TELEGRAM_WEBHOOK_SECRET: missing
+```
+
+## Verification
+
+```sh
+bun test packages/agentkit/src/runtime/channels/adapters.test.ts
+bun test packages/agentkit/src/runtime/deploy.test.ts
+npm run typecheck
+```
+
+## Troubleshooting
+
+Secret value appears in output:
+Stop and add a regression test before changing behavior. Delivery APIs must never return secret values.
+
+Phone number appears in delivery logs:
+Redact it to a stable partial form such as `5511******9999`.
+
+Webhook accepts invalid signatures or origin headers:
+Fix `verifyWebhook` for the adapter before enabling provider setup docs.