@kindgi/cli 0.1.4-rc.3 → 0.1.4-rc.5

package/dist/providers/presets/openrouter.json

@@ -0,0 +1,61 @@
+{
+  "name": "openrouter",
+  "description": "Many vendors' models through OpenRouter, with one key (key: OPENROUTER_API_KEY).",
+  "adapterId": "@kindgi/adapter-model-openai-compat",
+  "adapterConfigValues": {
+    "baseURL": "https://openrouter.ai/api/v1"
+  },
+  "secret": "OPENROUTER_API_KEY",
+  "pricesCheckedAt": "2026-10-07",
+  "metadata": {
+    "id": "openrouter",
+    "region": "unspecified",
+    "description": "Models from several vendors through OpenRouter",
+    "models": [
+      {
+        "name": "anthropic/claude-sonnet-5.5",
+        "contextWindow": 1000000,
+        "maxOutputTokens": 128000,
+        "features": ["tool-use", "parallel-tool-use", "structured-output", "long-context"],
+        "cost": {
+          "promptUsdPer1kTokens": 0.002,
+          "completionUsdPer1kTokens": 0.01
+        },
+        "description": "Claude Sonnet 5.5: balanced performance and cost."
+      },
+      {
+        "name": "openai/gpt-6.1-sol",
+        "contextWindow": 1050000,
+        "maxOutputTokens": 128000,
+        "features": ["tool-use", "parallel-tool-use", "structured-output", "long-context"],
+        "cost": {
+          "promptUsdPer1kTokens": 0.002,
+          "completionUsdPer1kTokens": 0.01
+        },
+        "description": "GPT-6.1 Sol: balanced performance and cost."
+      },
+      {
+        "name": "google/gemini-3.8-flash",
+        "contextWindow": 1048576,
+        "maxOutputTokens": 65536,
+        "features": ["tool-use", "parallel-tool-use", "structured-output", "long-context"],
+        "cost": {
+          "promptUsdPer1kTokens": 0.00075,
+          "completionUsdPer1kTokens": 0.00375
+        },
+        "description": "Gemini 3.8 Flash: fast and inexpensive."
+      },
+      {
+        "name": "openai/gpt-6-luna",
+        "contextWindow": 1050000,
+        "maxOutputTokens": 128000,
+        "features": ["tool-use", "parallel-tool-use", "structured-output", "long-context"],
+        "cost": {
+          "promptUsdPer1kTokens": 0.0001,
+          "completionUsdPer1kTokens": 0.0005
+        },
+        "description": "GPT-6 Luna: fastest and cheapest — routing, classification, simple calls."
+      }
+    ]
+  }
+}

package/dist/sdk-skills/kindgi-authoring-agents/SKILL.md

@@ -12,8 +12,8 @@ description: >
   kindgi-authoring-guardrails.
 type: core
 library: "@kindgi/sdk"
-version: "0.4.2"
-sdk_version: "0.1.4-rc.3"
+version: "0.4.3"
+sdk_version: "0.1.4-rc.5"
 pack_languages: [node]
 sources:
   - packages/agents/src/types.ts
@@ -63,7 +63,7 @@ const defined = defineAgent({
   description:
     'Drafts appellate briefs from a case file. Cites precedents; escalates novel legal questions.',
   instructions:
-    'You are drafting a brief in {{ jurisdiction }}. The user provides the case facts; you produce a Section IV argument citing at least two precedents. Use `acme.verify-citation` on every cite before including it. Refuse to fabricate citations — always call the tool.',
+    'You are drafting a brief in {{ jurisdiction }}. The user provides the case facts; you produce a Section IV argument citing at least two precedents. Check every cite with the verify-citation tool before including it. Refuse to fabricate citations — always call the tool.',
   capabilities: [{ needs: [{ feature: 'tool-use' as const }] }],
   tools: [
     { id: 'acme.verify-citation', version: '^0.1.0' },
@@ -96,7 +96,11 @@ export default defined.value;
   `conversation.*`). Rendered with `strictVariables: true` — unresolved
   references fail loudly at invoke time. Frame instructions like a
   competent employee brief: what the agent does, what tools to prefer,
-  what to refuse, what quality bar to hit.
+  what to refuse, what quality bar to hit. Name a tool by what it does
+  ("the verify-citation tool"), never by its dotted id: the model sees
+  ids in its provider's form (`acme__verify-citation` for Anthropic and
+  OpenAI-compatible models), and `acme.verify-citation` in the
+  instructions can make it call a name it wasn't given.
 - **`capabilities`** — declares the resource kinds the agent needs at
   runtime. `{feature: 'tool-use'}` is standard for tool-calling
   agents. The router picks the concrete LLM provider at turn time.

package/dist/sdk-skills/kindgi-authoring-flows/SKILL.md

@@ -14,7 +14,7 @@ description: >
 type: core
 library: "@kindgi/sdk"
 version: "0.1.2"
-sdk_version: "0.1.4-rc.3"
+sdk_version: "0.1.4-rc.5"
 pack_languages: [node]
 sources:
   - packages/flow/src/types.ts

package/dist/sdk-skills/kindgi-authoring-guardrails/SKILL.md

@@ -16,7 +16,7 @@ description: >
 type: core
 library: "@kindgi/sdk"
 version: "0.3.6"
-sdk_version: "0.1.4-rc.3"
+sdk_version: "0.1.4-rc.5"
 pack_languages: [node]
 sources:
   - packages/guardrails/src/types.ts

package/dist/sdk-skills/kindgi-authoring-mcp-servers/SKILL.md

@@ -18,7 +18,7 @@ description: >
 type: core
 library: "@kindgi/sdk"
 version: "0.3.0"
-sdk_version: "0.1.4-rc.3"
+sdk_version: "0.1.4-rc.5"
 pack_languages: [node, python]
 ---
 

package/dist/sdk-skills/kindgi-authoring-providers/SKILL.md

@@ -22,8 +22,8 @@ description: >
   kindgi-getting-started.
 type: core
 library: "@kindgi/sdk"
-version: "0.9.3"
-sdk_version: "0.1.4-rc.3"
+version: "0.9.5"
+sdk_version: "0.1.4-rc.5"
 pack_languages: [node, python]
 sources:
   - packages/adapters/model-anthropic/src/provider.ts
@@ -241,7 +241,14 @@ capability requirement (see "How the router picks…" below).
 
 Nothing to switch off: `dev-echo` is a fallback, so the new provider
 answers every agent it satisfies. A turn that still lands on dev-echo
-carries a `fallback-provider` warning — see mistake 9.
+carries the `fallback-provider` and `dev-echo-not-a-model` warnings — see
+mistake 9.
+
+**The other one-key presets** work the same way, with their own key:
+`--preset=openai` (`OPENAI_API_KEY`), `--preset=gemini-api` (`GEMINI_API_KEY`,
+a Google AI Studio key; `gemini` is Vertex AI), `--preset=groq`
+(`GROQ_API_KEY`) and `--preset=openrouter` (`OPENROUTER_API_KEY`).
+`kindgi providers presets` lists them with their models.
 
 ## Path B — Hosted via OpenAI-compat
 
@@ -305,15 +312,23 @@ kindgi secrets set GROQ_API_KEY --env=local --scope=tenant
 
 **Steps 3–5** same as Path A.
 
-## Path C — Local via in-process ONNX
+## Path C — Local via in-process ONNX (runtime from source only)
+
+> ⚠️ **Not in the runtime image, so not under `kindgi dev`.** The adapter
+> runs ONNX through `onnxruntime-node`, which ships glibc binaries only,
+> and the Kindgi runtime image is Alpine (musl): the adapter can't load
+> there (`Error loading shared library ld-linux-…`). `kindgi dev` runs
+> that image, so this path fails under it. It works only when the
+> runtime itself runs from source on macOS or a glibc Linux. **For a
+> local model under `kindgi dev`, use Ollama** ([Local via Ollama](#local-via-ollama-via-path-b)).
 
 > ⚠️ **Dev-only.** The in-process ONNX adapter writes weights to
 > `~/.cache/huggingface/hub/` — a per-machine cache with no production
 > recipe (no volume-mount recipe, no image-bake pattern, no offline
-> mode, no SHA pinning). Good for local dev, smoke tests, and CI
-> runners that keep the same disk between runs. **Do not ship packs
-> that rely on this adapter to production.** Use hosted providers
-> (Path A) or Ollama (Path B) instead.
+> mode, no SHA pinning). Good for smoke tests and CI runners that run
+> the runtime from source and keep the same disk between runs. **Do not
+> ship packs that rely on this adapter to production.** Use hosted
+> providers (Path A) or Ollama (Path B) instead.
 
 No API key. No network. Bundled with the framework — the adapter ships
 `smollm2-360m` by default (~273 MB weights, cached at
@@ -385,7 +400,8 @@ production. Skip only for scripted teardown where the model is already
 cached (`~/.cache/huggingface/hub/models--HuggingFaceTB--SmolLM2-360M-Instruct/`).
 
 `prepare` is idempotent: subsequent invocations are cache hits and
-return almost instantly, so put it in every `kindgi dev` boot script.
+return almost instantly, so put it in the script that boots your
+from-source runtime.
 
 Multi-model providers: prepare each model separately.
 ```sh
@@ -687,8 +703,9 @@ defineAgent({
    does nothing. Pin the model with a `models: { allow: [...] }`
    requirement instead.
 
-9. **Replies still come from dev-echo** (`Tool responded: …`; the turn's
-   result has a `fallback-provider` warning). dev-echo is a fallback: it
+9. **Replies still come from dev-echo** (`⚠ dev-echo isn't a real model: …`
+   then `Tool responded: …`; the turn's result has the `fallback-provider`
+   and `dev-echo-not-a-model` warnings). dev-echo is a fallback: it
    answers only when no registered provider satisfies the agent. So your
    provider doesn't — check its models' `features` against the agent's
    `capabilities.needs` (mistake 2), a `models` / `providers` allow-list

package/dist/sdk-skills/kindgi-authoring-tools/SKILL.md

@@ -13,7 +13,7 @@ description: >
 type: core
 library: "@kindgi/sdk"
 version: "0.4.4"
-sdk_version: "0.1.4-rc.3"
+sdk_version: "0.1.4-rc.5"
 pack_languages: [node]
 sources:
   - packages/tools/src/types.ts

package/dist/sdk-skills/kindgi-framework-feedback/SKILL.md

@@ -15,7 +15,7 @@ description: >
 type: core
 library: "@kindgi/sdk"
 version: "0.4.0"
-sdk_version: "0.1.4-rc.3"
+sdk_version: "0.1.4-rc.5"
 pack_languages: [node, python]
 ---
 

package/dist/sdk-skills/kindgi-getting-started/SKILL.md

@@ -15,7 +15,7 @@ description: >
 type: core
 library: "@kindgi/sdk"
 version: "0.3.8"
-sdk_version: "0.1.4-rc.3"
+sdk_version: "0.1.4-rc.5"
 pack_languages: [node]
 ---
 

package/dist/sdk-skills/kindgi-python-authoring-agents/SKILL.md

@@ -15,8 +15,8 @@ description: >
   model by kindgi-authoring-providers.
 type: core
 library: "kindgi (Python)"
-version: "0.1.0"
-sdk_version: "0.1.4-rc.3"
+version: "0.1.3"
+sdk_version: "0.1.4-rc.5"
 pack_languages: [python]
 sources:
   - sdks/python/src/kindgi/pack/define.py
@@ -25,9 +25,11 @@ sources:
 
 # Authoring Kindgi agents in Python
 
-> **Running `kindgi`:** a Python pack has no Node project, so the
-> `kindgi` CLI is the one on `PATH`. Python commands run in the pack's
-> environment: `uv run …` (or `.venv/bin/python …`).
+> **Running `kindgi`:** the CLI is `kindgi-cli` from PyPI, pinned in the
+> pack's dev group, so every `kindgi <command>` below runs as
+> `uv run kindgi <command>` (Poetry: `poetry run kindgi <command>`). Python
+> commands run in the pack's environment the same way: `uv run …` (or
+> `.venv/bin/python …`).
 
 An **agent** is a versioned, model-driven orchestrator: instructions (a
 prompt template), the tools it may call, the capabilities its model
@@ -75,7 +77,7 @@ brief_writer = Agent(
     instructions=(
         "You are drafting a brief in {{ jurisdiction }}. The user provides the case "
         "facts; you produce a Section IV argument citing at least two precedents. "
-        "Call acme.verify-citation on every cite before using it. Never invent one."
+        "Check every cite with the verify-citation tool before using it. Never invent one."
     ),
     capabilities=[{"needs": [{"feature": "tool-use"}]}],
     tools=[verify_citation, fetch_precedent],      # Tool objects — or {"id", "version"} refs
@@ -109,7 +111,11 @@ brief_writer = Agent(
   `parameters` or the runtime's own variables (`today`, `now`,
   `agent.*`, `conversation.*`), rendered strictly: an unknown variable
   fails the turn. Write it as a brief for a capable colleague: what to
-  do, which tools to prefer, what to refuse, the quality bar.
+  do, which tools to prefer, what to refuse, the quality bar. Name a
+  tool by what it does ("the verify-citation tool"), never by its dotted
+  id: the model sees ids in its provider's form (`acme__verify-citation`
+  for Anthropic and OpenAI-compatible models), and `acme.verify-citation`
+  in the instructions can make it call a name it wasn't given.
 - **`capabilities`** — what the model must support, e.g.
   `[{"needs": [{"feature": "tool-use"}]}]`. The turn routes its first
   capability to pick a provider and model; none declared fails the turn.
@@ -159,8 +165,9 @@ brief_writer = Agent(
 Agents run on a registered model provider; the router picks one whose
 models satisfy `capabilities`. `kindgi dev` gives a new pack `dev-echo`,
 a **fallback** that answers only while no other provider fits — it
-calls the first tool and replies "Tool responded: …", and the turn
-carries a `fallback-provider` warning. Register a real model and it
+calls the first tool and replies "⚠ dev-echo isn't a real model: …"
+then "Tool responded: …", and the turn carries the `fallback-provider` and
+`dev-echo-not-a-model` warnings. Register a real model and it
 takes over: see `kindgi-authoring-providers`
 (`kindgi providers register --preset=anthropic`).
 

package/dist/sdk-skills/kindgi-python-authoring-flows/SKILL.md

@@ -16,8 +16,8 @@ description: >
   kindgi-python-authoring-agents.
 type: core
 library: "kindgi (Python)"
-version: "0.1.1"
-sdk_version: "0.1.4-rc.3"
+version: "0.1.2"
+sdk_version: "0.1.4-rc.5"
 pack_languages: [python]
 sources:
   - sdks/python/src/kindgi/pack/define.py
@@ -27,9 +27,11 @@ sources:
 
 # Authoring Kindgi flows in Python
 
-> **Running `kindgi`:** a Python pack has no Node project, so the
-> `kindgi` CLI is the one on `PATH`. Python commands run in the pack's
-> environment: `uv run …` (or `.venv/bin/python …`).
+> **Running `kindgi`:** the CLI is `kindgi-cli` from PyPI, pinned in the
+> pack's dev group, so every `kindgi <command>` below runs as
+> `uv run kindgi <command>` (Poetry: `poetry run kindgi <command>`). Python
+> commands run in the pack's environment the same way: `uv run …` (or
+> `.venv/bin/python …`).
 
 A **flow** is a versioned, durable graph of steps: tools (your code) and
 agents (a model's judgment), joined by edges that can carry conditions.

package/dist/sdk-skills/kindgi-python-authoring-guardrails/SKILL.md

@@ -14,8 +14,8 @@ description: >
   kindgi-python-authoring-tools.
 type: core
 library: "kindgi (Python)"
-version: "0.1.1"
-sdk_version: "0.1.4-rc.3"
+version: "0.1.3"
+sdk_version: "0.1.4-rc.5"
 pack_languages: [python]
 sources:
   - sdks/python/src/kindgi/pack/define.py
@@ -25,9 +25,11 @@ sources:
 
 # Authoring Kindgi guardrails in Python
 
-> **Running `kindgi`:** a Python pack has no Node project, so the
-> `kindgi` CLI is the one on `PATH`. Python commands run in the pack's
-> environment: `uv run …` (or `.venv/bin/python …`).
+> **Running `kindgi`:** the CLI is `kindgi-cli` from PyPI, pinned in the
+> pack's dev group, so every `kindgi <command>` below runs as
+> `uv run kindgi <command>` (Poetry: `poetry run kindgi <command>`). Python
+> commands run in the pack's environment the same way: `uv run …` (or
+> `.venv/bin/python …`).
 
 A **guardrail** is a rule an agent's turn must satisfy: a **check** (a
 function over the turn's trace) plus an **action** (what happens when it
@@ -49,7 +51,7 @@ from kindgi import CheckResult, RunTrace, guardrail
 
 
 class Config(BaseModel):
-    min_lookups: int = Field(1, alias="minLookups", ge=0)
+    min_lookups: int = Field(default=1, alias="minLookups", ge=0)
 
 
 @guardrail(

package/dist/sdk-skills/kindgi-python-authoring-tools/SKILL.md

@@ -14,8 +14,8 @@ description: >
   kindgi-python-getting-started.
 type: core
 library: "kindgi (Python)"
-version: "0.1.1"
-sdk_version: "0.1.4-rc.3"
+version: "0.1.2"
+sdk_version: "0.1.4-rc.5"
 pack_languages: [python]
 sources:
   - sdks/python/src/kindgi/pack/define.py
@@ -25,9 +25,11 @@ sources:
 
 # Authoring Kindgi tools in Python
 
-> **Running `kindgi`:** a Python pack has no Node project, so the
-> `kindgi` CLI is the one on `PATH`. Python commands run in the pack's
-> environment: `uv run …` (or `.venv/bin/python …`).
+> **Running `kindgi`:** the CLI is `kindgi-cli` from PyPI, pinned in the
+> pack's dev group, so every `kindgi <command>` below runs as
+> `uv run kindgi <command>` (Poetry: `poetry run kindgi <command>`). Python
+> commands run in the pack's environment the same way: `uv run …` (or
+> `.venv/bin/python …`).
 
 A **tool** is a unit of work an agent (or a flow step) calls: typed
 input, typed output, your code in between. In a Python pack it is a

package/dist/sdk-skills/kindgi-python-getting-started/SKILL.md

@@ -14,8 +14,8 @@ description: >
   kindgi-python-authoring-agents; models by kindgi-authoring-providers.
 type: core
 library: "kindgi (Python)"
-version: "0.1.5"
-sdk_version: "0.1.4-rc.3"
+version: "0.1.7"
+sdk_version: "0.1.4-rc.5"
 pack_languages: [python]
 sources:
   - sdks/python/README.md
@@ -25,9 +25,11 @@ sources:
 
 # Getting started with Kindgi in Python
 
-> **Running `kindgi`:** a Python pack has no Node project, so the
-> `kindgi` CLI (a Node 22.12+ program) is the one on `PATH`. Python
-> commands run in the pack's environment: `uv run …`.
+> **Running `kindgi`:** the CLI is `kindgi-cli` from PyPI (the Kindgi CLI
+> with its own Node, so no Node install), pinned in the pack's dev group.
+> Every `kindgi <command>` below runs as `uv run kindgi <command>` (Poetry:
+> `poetry run kindgi <command>`). Python commands run in the pack's
+> environment the same way: `uv run …`.
 
 ## What a pack is
 
@@ -52,11 +54,11 @@ primitive; `test_*.py`, `*_test.py` and `conftest.py` are skipped.
 ## Scaffold a new pack
 
 ```sh
-kindgi init my-pack --template=python
+uvx --from "kindgi-cli>=0.1,<0.2" kindgi init my-pack --template=python
 cd my-pack
-uv sync            # .venv with the kindgi package
+uv sync            # .venv with the kindgi package and the kindgi CLI
 uv run pytest
-kindgi dev         # boots Kindgi locally and runs this pack, reloading on save
+uv run kindgi dev  # boots Kindgi locally and runs this pack, reloading on save
 ```
 
 `kindgi dev` needs Postgres: it starts one in Docker unless
@@ -70,9 +72,10 @@ kindgi dev         # boots Kindgi locally and runs this pack, reloading on save
 In the app's directory (where its `pyproject.toml` is):
 
 ```sh
-kindgi init            # --pack-id=<id> if the app's name doesn't make one
+uv add --dev "kindgi-cli>=0.1,<0.2"   # the CLI (Poetry: poetry add --group dev …)
+uv run kindgi init     # --pack-id=<id> if the app's name doesn't make one
 uv sync                # or what it prints for Poetry / pip
-kindgi dev
+uv run kindgi dev
 ```
 
 `kindgi init` edits the app's `pyproject.toml` in place — your layout and
@@ -116,17 +119,20 @@ The `[tool.kindgi]` keys are the ones `kindgi.config.ts` takes —
 With `kindgi dev` running, from another terminal in the pack directory:
 
 ```sh
-kindgi runs start --agent=my-pack.echo-agent --input='{"userMessage":"Ada"}'
+uv run kindgi runs start --agent=my-pack.echo-agent --input='{"userMessage":"Ada"}'
 ```
 
 The answer comes from `dev-echo`, a **fallback** provider a new pack
-gets: no model, no key — it calls the first tool and replies "Tool
-responded: …", and the turn carries a `fallback-provider` warning. For
-a real model, put the key in `.env` and register a provider:
+gets: no model, no key — it calls the first tool and replies "⚠
+dev-echo isn't a real model: …" then "Tool responded: …", and the turn
+carries the `fallback-provider` and `dev-echo-not-a-model` warnings. For a
+real model, put an LLM provider's key in `.env` and register its preset
+(Anthropic below; `kindgi providers presets` lists OpenAI, Gemini, Groq and
+OpenRouter too):
 
 ```sh
-kindgi secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt
-kindgi providers register --preset=anthropic
+uv run kindgi secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt
+uv run kindgi providers register --preset=anthropic
 ```
 
 It takes over at the next turn. That registration is in this project's dev

package/dist/templates/minimal/AGENTS.md

@@ -7,9 +7,12 @@ field-level docs. Iterate with `kindgi dev`; `kindgi --help` lists
 the full CLI.
 
 Agents answer through a model provider. `kindgi dev` gives a new pack
-`dev-echo`, a fallback that calls the first tool and replies
-"Tool responded: …" while no other provider fits. For Claude,
-put the key in `.env` and declare `{ preset: 'anthropic' }` in
+`dev-echo`, a fallback that isn't a model: it calls the first tool and
+replies "Tool responded: …" after a warning line, while no other provider
+fits. For a real model, put one LLM provider's key in `.env`
+(`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY` or
+`OPENROUTER_API_KEY`) and declare its preset (`{ preset: 'anthropic' }`,
+`'openai'`, `'gemini-api'`, `'groq'` or `'openrouter'`) in
 `kindgi.config.ts`'s `providers`: `kindgi dev` then registers it on every
 boot, in every worktree. Other providers and per-agent model choice:
 `.claude/skills/kindgi-authoring-providers/SKILL.md`.

package/dist/templates/minimal/README.md.tmpl

@@ -48,9 +48,11 @@ kindgi runs start --agent=demo.echo-agent --input='{"userMessage":"hi"}'
 
 ## Use a real model
 
-`kindgi dev` gives a new pack `dev-echo`, a fallback provider that calls the
-first tool and replies "Tool responded: …" — it answers only while no other
-provider fits. To use Claude, with `kindgi dev` running, from another terminal:
+`kindgi dev` gives a new pack `dev-echo`, a fallback provider that isn't a
+model: it calls the first tool and replies "Tool responded: …", after a
+warning line that says so. It answers only while no other provider fits. To
+use a real model, set one LLM provider's key and register its preset, with
+`kindgi dev` running, from another terminal. For Claude:
 
 ```sh
 kindgi secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt; writes .env.local
@@ -58,8 +60,12 @@ kindgi providers register --preset=anthropic                      # Opus 5.5, So
 ```
 
 Claude takes over from dev-echo on the next turn; nothing to restart.
-`--models=claude-haiku-4-5` registers one model only; `kindgi providers
-presets` lists the presets (Gemini on Vertex AI too). Picking a model per
+`--models=claude-haiku-4-5` registers one model only. OpenAI
+(`OPENAI_API_KEY`, `--preset=openai`), Gemini (`GEMINI_API_KEY`,
+`--preset=gemini-api`), Groq (`GROQ_API_KEY`, `--preset=groq`) and
+OpenRouter, many vendors' models with one key (`OPENROUTER_API_KEY`,
+`--preset=openrouter`), work the same way; `kindgi providers presets` lists
+the presets (Gemini on Vertex AI too). Picking a model per
 agent, and other providers: `.claude/skills/kindgi-authoring-providers/SKILL.md`.
 
 ## Note on `@kindgi/sdk` versioning

package/dist/templates/python/AGENTS.md

@@ -11,10 +11,13 @@ starts with `_`. The config is `[tool.kindgi]` in `pyproject.toml`.
 - `uv run pytest` runs the tests; a `Tool` or `Guardrail` is still callable.
 - `uv run python -m kindgi.pack index --pack-dir .` shows what Kindgi sees.
 - Agents answer through a model provider. `kindgi dev` gives a new pack
-  `dev-echo`, a fallback that calls the first tool and replies
-  "Tool responded: …" while no other provider fits. For Claude,
-  put the key in `.env` and add a `[[tool.kindgi.providers]]` table with
-  `preset = "anthropic"` to `pyproject.toml`: `kindgi dev` then registers it
+  `dev-echo`, a fallback that isn't a model: it calls the first tool and
+  replies "Tool responded: …" after a warning line, while no other provider
+  fits. For a real model, put one LLM provider's key in `.env`
+  (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY` or
+  `OPENROUTER_API_KEY`) and add a `[[tool.kindgi.providers]]` table with its
+  preset (`preset = "anthropic"`, `"openai"`, `"gemini-api"`, `"groq"` or
+  `"openrouter"`) to `pyproject.toml`: `kindgi dev` then registers it
   on every boot, in every worktree. Other providers and per-agent model
   choice: `.claude/skills/kindgi-authoring-providers/SKILL.md`.
 

package/dist/templates/python/README.md.tmpl

@@ -35,9 +35,11 @@ kindgi runs start --agent={{PACK_ID}}.echo-agent --input='{"userMessage":"hi"}'
 
 ## Use a real model
 
-`kindgi dev` gives a new pack `dev-echo`, a fallback provider that calls the
-first tool and replies "Tool responded: …" — it answers only while no other
-provider fits. To use Claude, with `kindgi dev` running, from another terminal:
+`kindgi dev` gives a new pack `dev-echo`, a fallback provider that isn't a
+model: it calls the first tool and replies "Tool responded: …", after a
+warning line that says so. It answers only while no other provider fits. To
+use a real model, set one LLM provider's key and register its preset, with
+`kindgi dev` running, from another terminal. For Claude:
 
 ```sh
 kindgi secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt; writes .env.local
@@ -45,8 +47,12 @@ kindgi providers register --preset=anthropic                      # Opus 5.5, So
 ```
 
 Claude takes over from dev-echo on the next turn; nothing to restart.
-`--models=claude-haiku-4-5` registers one model only; `kindgi providers
-presets` lists the presets (Gemini on Vertex AI too). Picking a model per
+`--models=claude-haiku-4-5` registers one model only. OpenAI
+(`OPENAI_API_KEY`, `--preset=openai`), Gemini (`GEMINI_API_KEY`,
+`--preset=gemini-api`), Groq (`GROQ_API_KEY`, `--preset=groq`) and
+OpenRouter, many vendors' models with one key (`OPENROUTER_API_KEY`,
+`--preset=openrouter`), work the same way; `kindgi providers presets` lists
+the presets (Gemini on Vertex AI too). Picking a model per
 agent, and other providers: `.claude/skills/kindgi-authoring-providers/SKILL.md`.
 
 ## Build

package/dist/templates/python/agents/echo_agent.py.tmpl

@@ -12,8 +12,8 @@ echo_agent = Agent(
     name="Echo Agent",
     description="Uses the pack's echo and greet tools; the response-not-empty guardrail guards the output.",
     instructions=(
-        "For each user message: if the user sends a name, invoke `{{PACK_ID}}.greet` with it. "
-        "Otherwise invoke `{{PACK_ID}}.echo` with the message text. Quote the tool result verbatim."
+        "For each user message: if the user sends a name, greet them with the greet tool. "
+        "Otherwise echo their message with the echo tool. Quote the tool result verbatim."
     ),
     capabilities=[{"needs": [{"feature": "tool-use"}]}],
     tools=[echo, greet],

package/dist/templates/sample/AGENTS.md

@@ -7,9 +7,12 @@ field-level docs. Iterate with `kindgi dev`; `kindgi --help` lists
 the full CLI.
 
 Agents answer through a model provider. `kindgi dev` gives a new pack
-`dev-echo`, a fallback that calls the first tool and replies
-"Tool responded: …" while no other provider fits. For Claude,
-put the key in `.env` and declare `{ preset: 'anthropic' }` in
+`dev-echo`, a fallback that isn't a model: it calls the first tool and
+replies "Tool responded: …" after a warning line, while no other provider
+fits. For a real model, put one LLM provider's key in `.env`
+(`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY` or
+`OPENROUTER_API_KEY`) and declare its preset (`{ preset: 'anthropic' }`,
+`'openai'`, `'gemini-api'`, `'groq'` or `'openrouter'`) in
 `kindgi.config.ts`'s `providers`: `kindgi dev` then registers it on every
 boot, in every worktree. Other providers and per-agent model choice:
 `.claude/skills/kindgi-authoring-providers/SKILL.md`.

package/dist/templates/sample/README.md.tmpl

@@ -40,9 +40,11 @@ re-registers on every file save.
 
 ## Use a real model
 
-`kindgi dev` gives a new pack `dev-echo`, a fallback provider that calls the
-first tool and replies "Tool responded: …" — it answers only while no other
-provider fits. To use Claude, with `kindgi dev` running, from another terminal:
+`kindgi dev` gives a new pack `dev-echo`, a fallback provider that isn't a
+model: it calls the first tool and replies "Tool responded: …", after a
+warning line that says so. It answers only while no other provider fits. To
+use a real model, set one LLM provider's key and register its preset, with
+`kindgi dev` running, from another terminal. For Claude:
 
 ```sh
 kindgi secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt; writes .env.local
@@ -50,8 +52,12 @@ kindgi providers register --preset=anthropic                      # Opus 5.5, So
 ```
 
 Claude takes over from dev-echo on the next turn; nothing to restart.
-`--models=claude-haiku-4-5` registers one model only; `kindgi providers
-presets` lists the presets (Gemini on Vertex AI too). Picking a model per
+`--models=claude-haiku-4-5` registers one model only. OpenAI
+(`OPENAI_API_KEY`, `--preset=openai`), Gemini (`GEMINI_API_KEY`,
+`--preset=gemini-api`), Groq (`GROQ_API_KEY`, `--preset=groq`) and
+OpenRouter, many vendors' models with one key (`OPENROUTER_API_KEY`,
+`--preset=openrouter`), work the same way; `kindgi providers presets` lists
+the presets (Gemini on Vertex AI too). Picking a model per
 agent, and other providers: `.claude/skills/kindgi-authoring-providers/SKILL.md`.
 
 ## The four primitives (one file each)

package/dist/templates/sample/agents/echo-agent/index.ts.tmpl

@@ -12,7 +12,7 @@ const defined = defineAgent({
   description:
     'Uses the pack\'s echo + greet tools; the response-not-empty guardrail guards the output.',
   instructions:
-    'For each user message: if the user sends a name, invoke `{{PACK_ID}}.greet` with it. Otherwise invoke `{{PACK_ID}}.echo` with the message text. Quote the tool result verbatim in your reply.',
+    'For each user message: if the user sends a name, greet them with the greet tool. Otherwise echo their message with the echo tool. Quote the tool result verbatim in your reply.',
   capabilities: [{ needs: [{ feature: 'tool-use' as const }] }],
   tools: [
     { id: '{{PACK_ID}}.echo', version: '{{PACK_VERSION}}' },