@kindgi/cli 0.1.7-rc.0 → 0.1.8-rc.0

package/dist/templates/drupal/AGENTS.md

@@ -10,12 +10,12 @@ Agents answer through a model provider. `kindgi dev` gives a new pack
 `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`.
+(`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: the `kindgi-authoring-providers` skill.
 
 ## This pack: a Drupal site
 
@@ -46,17 +46,42 @@ README.md explains the whole design; keep it true when you change the pack.
 - **The client secret is a secret** (`DRUPAL_CLIENT_SECRET`, set with
   `kindgi secrets set`): never write it in a file, a test or the chat.
 
-## For Claude Code sessions
+## Skills
 
-When you diagnose a framework bug (something in Kindgi itself, not in
-this pack's code), append an entry to `FEEDBACK.md` at the pack root
-via `kindgi feedback write` — see
-`.claude/skills/kindgi-framework-feedback/SKILL.md`. Mark items fixed
-by adding a `> **Fixed:** <note>` line right after their header; the
-file is a plain markdown list you edit directly.
+`.claude/skills/` and `.agents/skills/` hold the same Kindgi skills: getting
+started, tools, guardrails, agents and flows, model providers, MCP servers,
+framework feedback, and guiding the person in using what you built
+(`kindgi-using`). Claude Code loads `.claude/skills/` on its own; Codex and
+Gemini CLI look in `.agents/skills/`; any other coding agent can read
+either. `kindgi skills sync` refreshes both.
+
+When you diagnose a framework bug (something in Kindgi itself, not in this
+pack's code), append an entry to `FEEDBACK.md` at the pack root via
+`kindgi feedback write` — see the `kindgi-framework-feedback` skill. Mark
+items fixed by adding a `> **Fixed:** <note>` line right after their
+header; the file is a plain markdown list you edit directly.
 
 When the person asks how to use what you built (where something is in
 Kindgi's console, what an agent did, what it cost, who has access), answer
 from `kindgi`'s read-only commands and give the console link beside it —
-see `.claude/skills/kindgi-using/SKILL.md`. Deciding approvals, erasing,
-adding people and rating answers stay with the person.
+see the `kindgi-using` skill. Deciding approvals, erasing, adding people
+and rating answers stay with the person.
+
+## Commands for the person's own terminal
+
+Two commands are always the person's to run, in their own terminal, since
+they ask for a secret: `kindgi secrets set` and `kindgi auth registry`.
+Others need what a coding agent's sandbox often blocks: `kindgi dev` and any
+dev server (they keep running), and `kindgi build` or anything else that
+needs Docker. When your sandbox blocks a command (a process it can't start,
+`spawn EPERM`; Docker's socket denied; `localhost` refused; a folder it
+keeps read-only, as Codex's keeps `.agents/`, which `kindgi skills sync`
+writes), don't work around it: don't turn your sandbox off, and don't start
+the command in the background. Give the person the exact command, the folder
+to run it in and what they'll see, then wait for them. Once they say
+`kindgi dev` is running, starting it yourself exits 3 and says where theirs
+runs: use that one.
+
+A tool's own `EPERM` while it runs under `kindgi dev` is something else:
+Kindgi's dev sandbox, which the tools skill covers. Never turn that one off
+either.

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

@@ -218,8 +218,7 @@ calls the first tool. For Claude, with `kindgi dev` running:
 {{KINDGI}} providers register --preset=anthropic
 ```
 
-`.claude/skills/kindgi-authoring-providers/SKILL.md` has the other
-providers.
+The `kindgi-authoring-providers` skill has the other providers.
 
 Ask the content agent something:
 
@@ -286,7 +285,7 @@ starts a run:
 ```sh
 composer require drupal/webhooks:^3.0@rc && drush en webhooks
 {{KINDGI}} webhooks register --flow={{PACK_ID}}.content-review --flow-version={{PACK_VERSION}} \
-  --preset=drupal-webhooks --generate-secret --secret=DRUPAL_WEBHOOK_SECRET --env=local \
+  --preset=drupal-webhooks --generate-secret --secret=DRUPAL_WEBHOOK_SECRET \
   --label="Drupal articles"
 ```
 

package/dist/templates/drupal/kindgi.config.ts.tmpl

@@ -13,28 +13,32 @@ const config = {
     flows: 'flows/**/*.ts',
   },
   // ---------------------------------------------------------------
-  // Environments — one entry per deploy target. `kindgi build`
-  // reads `.build`, `.registry`, `.signingKey`, `.tenantId` for the
-  // chosen env; `kindgi deploy` reads `.endpoint`.
+  // Environments: one entry per place you deploy to, picked with
+  // `--env <name>` (default `staging`). `kindgi build` reads `build`,
+  // `registry`, `signingKey` and `tenantId`; `kindgi deploy` reads
+  // `endpoint`. Local `kindgi dev` doesn't read this block.
   //
-  // Fill these in when you're ready to push a build. Local
-  // `kindgi dev` does NOT read this block.
+  // Your API key goes only to the address you signed in to
+  // (`kindgi auth login --url <url>`), so an `endpoint` here must be
+  // that address. Builds are signed with a key of yours: make it with
+  // `kindgi key create <id>`, and let the runtime trust it with
+  // `kindgi key trust <id>` (once).
   // ---------------------------------------------------------------
   environments: {
-    staging: {
-      endpoint: 'https://api.staging.example.com',
-      build: 'http://localhost:8787', // your Kindgi build server
-      registry: 'ghcr.io/your-org',
-      signingKey: '~/.kindgi/keys/staging.pem',
-      tenantId: 'tenant-your-org-staging',
-    },
-    production: {
-      endpoint: 'https://api.example.com',
-      build: 'https://build.example.com',
-      registry: 'ghcr.io/your-org',
-      signingKey: '~/.kindgi/keys/production.pem',
-      tenantId: 'tenant-your-org-production',
-    },
+    // Kindgi Cloud: `kindgi deploy --env=prod` builds there and deploys.
+    // prod: {
+    //   build: 'hosted',
+    //   signingKey: '~/.kindgi/keys/<id>.pem',
+    // },
+    //
+    // A runtime of your own:
+    // production: {
+    //   endpoint: 'https://kindgi.your-company.example', // the address you signed in to
+    //   build: 'https://build.your-company.example', // your Kindgi build server
+    //   registry: 'ghcr.io/your-org',
+    //   signingKey: '~/.kindgi/keys/<id>.pem',
+    //   tenantId: '<your tenant id>',
+    // },
   },
 } as const;
 

package/dist/templates/java/AGENTS.md

@@ -26,12 +26,41 @@ The config is `kindgi.config.json`.
   `"openrouter"`) to `kindgi.config.json`: `kindgi dev` then registers it on
   every boot, in every worktree.
 
+## Skills
+
+`.claude/skills/` and `.agents/skills/` hold the same Kindgi skills for Java
+packs: getting started, tools, guardrails, agents and flows in Java
+(`kindgi-java-*`), model providers, MCP servers, framework feedback, and
+guiding the person in using what you built (`kindgi-using`). Claude Code
+loads `.claude/skills/` on its own; Codex and Gemini CLI look in
+`.agents/skills/`; any other coding agent can read either.
+`kindgi skills sync` refreshes both.
+
 When you diagnose a framework bug (something in Kindgi itself, not in this
 pack's code), append an entry to `FEEDBACK.md` at the pack root with
 `kindgi feedback write`.
 
 When the person asks how to use what you built (where something is in
 Kindgi's console, what an agent did, what it cost, who has access), answer
-from `kindgi`'s read-only commands and give the console link beside it: see
-`.claude/skills/kindgi-using/SKILL.md`. Deciding approvals, erasing, adding
-people and rating answers stay with the person.
+from `kindgi`'s read-only commands and give the console link beside it:
+see the `kindgi-using` skill. Deciding approvals, erasing, adding people
+and rating answers stay with the person.
+
+## Commands for the person's own terminal
+
+Two commands are always the person's to run, in their own terminal, since
+they ask for a secret: `./kindgiw secrets set` and
+`./kindgiw auth registry`. Others need what a coding agent's sandbox often
+blocks: `./kindgiw dev` and any dev server (they keep running), and
+`./kindgiw build` or anything else that needs Docker. When your sandbox
+blocks a command (a process it can't start, `spawn EPERM`; Docker's socket
+denied; `localhost` refused; a folder it keeps read-only, as Codex's keeps
+`.agents/`, which `./kindgiw skills sync` writes), don't work around it:
+don't turn your sandbox off, and don't start the command in the background.
+Give the person the exact command, the folder to run it in and what they'll
+see, then wait for them. Once they say `./kindgiw dev` is running, starting
+it yourself exits 3 and says where theirs runs: use that one.
+
+A tool's own `EPERM` while it runs under `./kindgiw dev` is something else:
+Kindgi's dev sandbox, which the tools skill covers. Never turn that one off
+either.

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

@@ -6,7 +6,7 @@ Two tools (`echo`, `greet`), one guardrail (`response-not-empty`), one agent
 that uses both tools and the guardrail, and one flow that runs the echo tool.
 
 Java and Scala support is in preview: tested and supported, but the API may
-still change in 0.1.6 without the usual deprecation period.
+still change in a later release without the usual deprecation period.
 
 ## Layout
 

package/dist/templates/minimal/AGENTS.md

@@ -10,24 +10,49 @@ Agents answer through a model provider. `kindgi dev` gives a new pack
 `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`.
-
-## For Claude Code sessions
-
-When you diagnose a framework bug (something in Kindgi itself, not in
-this pack's code), append an entry to `FEEDBACK.md` at the pack root
-via `kindgi feedback write` — see
-`.claude/skills/kindgi-framework-feedback/SKILL.md`. Mark items fixed
-by adding a `> **Fixed:** <note>` line right after their header; the
-file is a plain markdown list you edit directly.
+(`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: the `kindgi-authoring-providers` skill.
+
+## Skills
+
+`.claude/skills/` and `.agents/skills/` hold the same Kindgi skills: getting
+started, tools, guardrails, agents and flows, model providers, MCP servers,
+framework feedback, and guiding the person in using what you built
+(`kindgi-using`). Claude Code loads `.claude/skills/` on its own; Codex and
+Gemini CLI look in `.agents/skills/`; any other coding agent can read
+either. `kindgi skills sync` refreshes both.
+
+When you diagnose a framework bug (something in Kindgi itself, not in this
+pack's code), append an entry to `FEEDBACK.md` at the pack root via
+`kindgi feedback write` — see the `kindgi-framework-feedback` skill. Mark
+items fixed by adding a `> **Fixed:** <note>` line right after their
+header; the file is a plain markdown list you edit directly.
 
 When the person asks how to use what you built (where something is in
 Kindgi's console, what an agent did, what it cost, who has access), answer
 from `kindgi`'s read-only commands and give the console link beside it —
-see `.claude/skills/kindgi-using/SKILL.md`. Deciding approvals, erasing,
-adding people and rating answers stay with the person.
+see the `kindgi-using` skill. Deciding approvals, erasing, adding people
+and rating answers stay with the person.
+
+## Commands for the person's own terminal
+
+Two commands are always the person's to run, in their own terminal, since
+they ask for a secret: `kindgi secrets set` and `kindgi auth registry`.
+Others need what a coding agent's sandbox often blocks: `kindgi dev` and any
+dev server (they keep running), and `kindgi build` or anything else that
+needs Docker. When your sandbox blocks a command (a process it can't start,
+`spawn EPERM`; Docker's socket denied; `localhost` refused; a folder it
+keeps read-only, as Codex's keeps `.agents/`, which `kindgi skills sync`
+writes), don't work around it: don't turn your sandbox off, and don't start
+the command in the background. Give the person the exact command, the folder
+to run it in and what they'll see, then wait for them. Once they say
+`kindgi dev` is running, starting it yourself exits 3 and says where theirs
+runs: use that one.
+
+A tool's own `EPERM` while it runs under `kindgi dev` is something else:
+Kindgi's dev sandbox, which the tools skill covers. Never turn that one off
+either.

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

@@ -14,6 +14,7 @@ Author your first via `defineTool` / `defineAgent` / `defineCheck` /
 ├── package.json           # depends on @kindgi/sdk + zod
 ├── tsconfig.json
 ├── .claude/skills/        # SDK skills — Claude Code auto-loads per task
+├── .agents/skills/        # the same skills, where Codex and Gemini CLI look
 ├── tools/                 # place `<name>/index.ts` per tool
 ├── agents/                # place `<name>/index.ts` per agent
 ├── guardrails/            # place `<name>/index.ts` per check
@@ -22,15 +23,15 @@ Author your first via `defineTool` / `defineAgent` / `defineCheck` /
 
 ## AI coding assistants
 
-`.claude/skills/` is auto-populated at `kindgi init` with per-primitive
-guides: `kindgi-authoring-tools`, `kindgi-authoring-agents`,
-`kindgi-authoring-guardrails`, `kindgi-getting-started` — plus
-`kindgi-authoring-providers` (a real model), `kindgi-authoring-mcp-servers`,
-`kindgi-framework-feedback` and `kindgi-using` (guiding you in using what
-you built). Claude Code
-loads them on-demand based on what you're editing — no configuration
-needed. Read them directly if you want the mental model without an
-assistant in the loop.
+`.claude/skills/` and `.agents/skills/` are auto-populated at `kindgi init`
+with the same per-primitive guides: `kindgi-authoring-tools`,
+`kindgi-authoring-agents`, `kindgi-authoring-guardrails`,
+`kindgi-getting-started` — plus `kindgi-authoring-providers` (a real model),
+`kindgi-authoring-mcp-servers`, `kindgi-framework-feedback` and
+`kindgi-using` (guiding you in using what you built). Claude Code loads
+`.claude/skills/` on demand, based on what you're editing; Codex and Gemini
+CLI look in `.agents/skills/`. No configuration needed. Read them directly
+if you want the mental model without an assistant in the loop.
 
 ## Run
 
@@ -67,4 +68,4 @@ Claude takes over from dev-echo on the next turn; nothing to restart.
 OpenRouter, a hosted service your prompts pass through (`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`.
+agent, and other providers: the `kindgi-authoring-providers` skill.

package/dist/templates/minimal/kindgi.config.ts.tmpl

@@ -13,31 +13,32 @@ const config = {
     flows: 'flows/**/*.ts',
   },
   // ---------------------------------------------------------------
-  // Environments — one entry per deploy target (staging / production
-  // / preview / custom). Each names the build server endpoint, the
-  // signing key path (Ed25519 PEM, never leaves the developer's
-  // machine), the target registry (build server pushes here on your
-  // behalf), and the tenantId the Kindgi runtime scopes the
-  // deployment to. Consumed by `kindgi build` + `kindgi deploy`.
+  // Environments: one entry per place you deploy to, picked with
+  // `--env <name>` (default `staging`). `kindgi build` reads `build`,
+  // `registry`, `signingKey` and `tenantId`; `kindgi deploy` reads
+  // `endpoint`. Local `kindgi dev` doesn't read this block.
   //
-  // Fill these in when you're ready to push a build off the laptop.
-  // Local `kindgi dev` does NOT read this block.
+  // Your API key goes only to the address you signed in to
+  // (`kindgi auth login --url <url>`), so an `endpoint` here must be
+  // that address. Builds are signed with a key of yours: make it with
+  // `kindgi key create <id>`, and let the runtime trust it with
+  // `kindgi key trust <id>` (once).
   // ---------------------------------------------------------------
   environments: {
-    staging: {
-      endpoint: 'https://api.staging.example.com',
-      build: 'http://localhost:8787', // your Kindgi build server
-      registry: 'ghcr.io/your-org',
-      signingKey: '~/.kindgi/keys/staging.pem',
-      tenantId: 'tenant-your-org-staging',
-    },
-    production: {
-      endpoint: 'https://api.example.com',
-      build: 'https://build.example.com',
-      registry: 'ghcr.io/your-org',
-      signingKey: '~/.kindgi/keys/production.pem',
-      tenantId: 'tenant-your-org-production',
-    },
+    // Kindgi Cloud: `kindgi deploy --env=prod` builds there and deploys.
+    // prod: {
+    //   build: 'hosted',
+    //   signingKey: '~/.kindgi/keys/<id>.pem',
+    // },
+    //
+    // A runtime of your own:
+    // production: {
+    //   endpoint: 'https://kindgi.your-company.example', // the address you signed in to
+    //   build: 'https://build.your-company.example', // your Kindgi build server
+    //   registry: 'ghcr.io/your-org',
+    //   signingKey: '~/.kindgi/keys/<id>.pem',
+    //   tenantId: '<your tenant id>',
+    // },
   },
 } as const;
 

package/dist/templates/python/AGENTS.md

@@ -19,17 +19,37 @@ starts with `_`. The config is `[tool.kindgi]` in `pyproject.toml`.
   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`.
+  choice: the `kindgi-authoring-providers` skill.
 
 ## Skills
 
-`.claude/skills/` holds Kindgi's skills for Python packs: getting started,
-tools, guardrails and agents in Python (`kindgi-python-*`), model providers,
-MCP servers, framework feedback, and guiding the person in using what you
-built (`kindgi-using`). Claude Code loads them on its own; other coding
-agents can read them. `kindgi skills sync` refreshes them.
+`.claude/skills/` and `.agents/skills/` hold the same Kindgi skills for
+Python packs: getting started, tools, guardrails and agents in Python
+(`kindgi-python-*`), model providers, MCP servers, framework feedback, and
+guiding the person in using what you built (`kindgi-using`). Claude Code
+loads `.claude/skills/` on its own; Codex and Gemini CLI look in
+`.agents/skills/`; any other coding agent can read either.
+`kindgi skills sync` refreshes both.
 
 When you diagnose a framework bug (something in Kindgi itself, not in this
 pack's code), append an entry to `FEEDBACK.md` at the pack root via
-`kindgi feedback write` — see
-`.claude/skills/kindgi-framework-feedback/SKILL.md`.
+`kindgi feedback write` — see the `kindgi-framework-feedback` skill.
+
+## Commands for the person's own terminal
+
+Two commands are always the person's to run, in their own terminal, since
+they ask for a secret: `kindgi secrets set` and `kindgi auth registry`.
+Others need what a coding agent's sandbox often blocks: `kindgi dev` and any
+dev server (they keep running), and `kindgi build` or anything else that
+needs Docker. When your sandbox blocks a command (a process it can't start,
+`spawn EPERM`; Docker's socket denied; `localhost` refused; a folder it
+keeps read-only, as Codex's keeps `.agents/`, which `kindgi skills sync`
+writes), don't work around it: don't turn your sandbox off, and don't start
+the command in the background. Give the person the exact command, the folder
+to run it in and what they'll see, then wait for them. Once they say
+`kindgi dev` is running, starting it yourself exits 3 and says where theirs
+runs: use that one.
+
+A tool's own `EPERM` while it runs under `kindgi dev` is something else:
+Kindgi's dev sandbox, which the tools skill covers. Never turn that one off
+either.

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

@@ -53,7 +53,7 @@ Claude takes over from dev-echo on the next turn; nothing to restart.
 OpenRouter, a hosted service your prompts pass through (`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`.
+agent, and other providers: the `kindgi-authoring-providers` skill.
 
 ## Build
 

package/dist/templates/python/pyproject.toml.tmpl

@@ -30,12 +30,16 @@ description = "A sample Kindgi pack in Python — two tools, one guardrail, one
 # python = ["uv", "run", "python"]   # default: .venv/bin/python, else python3
 # envFiles = [".env", ".env.local"]
 
-# One block per deploy target; `kindgi build --env=<name>` reads it.
-# [tool.kindgi.environments.staging]
-# endpoint = "https://api.staging.example.com"
-# build = "http://localhost:4001"
-# tenantId = "tenant-your-org-staging"
-# signingKey = "~/.kindgi/keys/staging.pem"
+# One block per place you deploy to; `kindgi build --env=<name>` reads it.
+# Your API key goes only to the address you signed in to
+# (`kindgi auth login --url <url>`), so an `endpoint` must be that address.
+# Builds are signed with a key of yours: make it with `kindgi key create <id>`,
+# and let the runtime trust it with `kindgi key trust <id>` (once).
+# [tool.kindgi.environments.production]
+# endpoint = "https://kindgi.your-company.example"   # the address you signed in to
+# build = "https://build.your-company.example"       # your Kindgi build server
+# tenantId = "<your tenant id>"
+# signingKey = "~/.kindgi/keys/<id>.pem"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

package/dist/templates/sample/AGENTS.md

@@ -10,24 +10,49 @@ Agents answer through a model provider. `kindgi dev` gives a new pack
 `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`.
-
-## For Claude Code sessions
-
-When you diagnose a framework bug (something in Kindgi itself, not in
-this pack's code), append an entry to `FEEDBACK.md` at the pack root
-via `kindgi feedback write` — see
-`.claude/skills/kindgi-framework-feedback/SKILL.md`. Mark items fixed
-by adding a `> **Fixed:** <note>` line right after their header; the
-file is a plain markdown list you edit directly.
+(`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: the `kindgi-authoring-providers` skill.
+
+## Skills
+
+`.claude/skills/` and `.agents/skills/` hold the same Kindgi skills: getting
+started, tools, guardrails, agents and flows, model providers, MCP servers,
+framework feedback, and guiding the person in using what you built
+(`kindgi-using`). Claude Code loads `.claude/skills/` on its own; Codex and
+Gemini CLI look in `.agents/skills/`; any other coding agent can read
+either. `kindgi skills sync` refreshes both.
+
+When you diagnose a framework bug (something in Kindgi itself, not in this
+pack's code), append an entry to `FEEDBACK.md` at the pack root via
+`kindgi feedback write` — see the `kindgi-framework-feedback` skill. Mark
+items fixed by adding a `> **Fixed:** <note>` line right after their
+header; the file is a plain markdown list you edit directly.
 
 When the person asks how to use what you built (where something is in
 Kindgi's console, what an agent did, what it cost, who has access), answer
 from `kindgi`'s read-only commands and give the console link beside it —
-see `.claude/skills/kindgi-using/SKILL.md`. Deciding approvals, erasing,
-adding people and rating answers stay with the person.
+see the `kindgi-using` skill. Deciding approvals, erasing, adding people
+and rating answers stay with the person.
+
+## Commands for the person's own terminal
+
+Two commands are always the person's to run, in their own terminal, since
+they ask for a secret: `kindgi secrets set` and `kindgi auth registry`.
+Others need what a coding agent's sandbox often blocks: `kindgi dev` and any
+dev server (they keep running), and `kindgi build` or anything else that
+needs Docker. When your sandbox blocks a command (a process it can't start,
+`spawn EPERM`; Docker's socket denied; `localhost` refused; a folder it
+keeps read-only, as Codex's keeps `.agents/`, which `kindgi skills sync`
+writes), don't work around it: don't turn your sandbox off, and don't start
+the command in the background. Give the person the exact command, the folder
+to run it in and what they'll see, then wait for them. Once they say
+`kindgi dev` is running, starting it yourself exits 3 and says where theirs
+runs: use that one.
+
+A tool's own `EPERM` while it runs under `kindgi dev` is something else:
+Kindgi's dev sandbox, which the tools skill covers. Never turn that one off
+either.

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

@@ -58,7 +58,7 @@ Claude takes over from dev-echo on the next turn; nothing to restart.
 OpenRouter, a hosted service your prompts pass through (`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`.
+agent, and other providers: the `kindgi-authoring-providers` skill.
 
 ## The four primitives (one file each)
 

package/dist/templates/sample/kindgi.config.ts.tmpl

@@ -13,28 +13,32 @@ const config = {
     flows: 'flows/**/*.ts',
   },
   // ---------------------------------------------------------------
-  // Environments — one entry per deploy target. `kindgi build`
-  // reads `.build`, `.registry`, `.signingKey`, `.tenantId` for the
-  // chosen env; `kindgi deploy` reads `.endpoint`.
+  // Environments: one entry per place you deploy to, picked with
+  // `--env <name>` (default `staging`). `kindgi build` reads `build`,
+  // `registry`, `signingKey` and `tenantId`; `kindgi deploy` reads
+  // `endpoint`. Local `kindgi dev` doesn't read this block.
   //
-  // Fill these in when you're ready to push a build. Local
-  // `kindgi dev` does NOT read this block.
+  // Your API key goes only to the address you signed in to
+  // (`kindgi auth login --url <url>`), so an `endpoint` here must be
+  // that address. Builds are signed with a key of yours: make it with
+  // `kindgi key create <id>`, and let the runtime trust it with
+  // `kindgi key trust <id>` (once).
   // ---------------------------------------------------------------
   environments: {
-    staging: {
-      endpoint: 'https://api.staging.example.com',
-      build: 'http://localhost:8787', // your Kindgi build server
-      registry: 'ghcr.io/your-org',
-      signingKey: '~/.kindgi/keys/staging.pem',
-      tenantId: 'tenant-your-org-staging',
-    },
-    production: {
-      endpoint: 'https://api.example.com',
-      build: 'https://build.example.com',
-      registry: 'ghcr.io/your-org',
-      signingKey: '~/.kindgi/keys/production.pem',
-      tenantId: 'tenant-your-org-production',
-    },
+    // Kindgi Cloud: `kindgi deploy --env=prod` builds there and deploys.
+    // prod: {
+    //   build: 'hosted',
+    //   signingKey: '~/.kindgi/keys/<id>.pem',
+    // },
+    //
+    // A runtime of your own:
+    // production: {
+    //   endpoint: 'https://kindgi.your-company.example', // the address you signed in to
+    //   build: 'https://build.your-company.example', // your Kindgi build server
+    //   registry: 'ghcr.io/your-org',
+    //   signingKey: '~/.kindgi/keys/<id>.pem',
+    //   tenantId: '<your tenant id>',
+    // },
   },
 } as const;