@kindgi/cli 0.1.7 → 0.1.8

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

@@ -15,8 +15,8 @@ description: >
   kindgi-java-authoring-tools, Java agents by kindgi-java-authoring-agents.
 type: core
 library: "kindgi-pack (Java)"
-version: "0.1.0"
-sdk_version: "0.1.7"
+version: "0.1.2"
+sdk_version: "0.1.8"
 pack_languages: [java]
 sources:
   - sdks/java/kindgi-pack/README.md
@@ -32,7 +32,7 @@ sources:
 > `./mvnw`.
 >
 > Java support is in preview: tested and supported, but the API may still
-> change in 0.1.6 without the usual deprecation period.
+> change in a later release without the usual deprecation period.
 
 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. It
@@ -252,6 +252,12 @@ public final class TriageTicket {
   `outputSchema`). `convergence` decides the result: `all-succeed`,
   `any-succeed` (the first success wins), or `settle-all` (wait for every
   branch and report each).
+  Every branch gets the fanout's whole input: the output of the step
+  before it (the run input after `$start`). A record refuses
+  properties it doesn't name, so when a branch tool takes only some of
+  them, its input record says `@JsonIgnoreProperties(ignoreUnknown = true)`
+  (`com.fasterxml.jackson.annotation`). Without it, the branch fails with
+  `input-validation-failed`.
 - **A sub-flow** (`"kind": "subgraph"`) is part of the flow schema, but a run
   refuses it today (`flow-unbound`). Inline the steps instead.
 

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

@@ -14,8 +14,8 @@ description: >
   by kindgi-java-authoring-tools.
 type: core
 library: "kindgi-pack (Java)"
-version: "0.1.0"
-sdk_version: "0.1.7"
+version: "0.1.1"
+sdk_version: "0.1.8"
 pack_languages: [java]
 sources:
   - sdks/java/kindgi-pack/README.md
@@ -31,7 +31,7 @@ sources:
 > `./mvnw`.
 >
 > Java support is in preview: tested and supported, but the API may still
-> change in 0.1.6 without the usual deprecation period.
+> change in a later release without the usual deprecation period.
 
 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

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

@@ -14,8 +14,8 @@ description: >
   by kindgi-java-getting-started.
 type: core
 library: "kindgi-pack (Java)"
-version: "0.1.0"
-sdk_version: "0.1.7"
+version: "0.1.2"
+sdk_version: "0.1.8"
 pack_languages: [java]
 sources:
   - sdks/java/kindgi-pack/README.md
@@ -31,7 +31,7 @@ sources:
 > Windows). Maven runs as `./mvnw` (or the app's own `mvn`).
 >
 > Java support is in preview: tested and supported, but the API may still
-> change in 0.1.6 without the usual deprecation period.
+> change in a later release without the usual deprecation period.
 
 A **tool** is a unit of work an agent (or a flow step) calls: typed input,
 typed output, your code in between. In a Java pack it is a
@@ -181,7 +181,12 @@ final class Citator {
   `onCancel(action)`.
 - `ctx.secrets()`: the secrets the tool declares (below). Printing the
   context shows their names, never their values.
-- `ctx.env()`, `ctx.config()`: **reserved, empty today**.
+- `ctx.env()`: the env values the tool declares (`set("needsSpec",
+  Map.of("env", …))`), resolved for the call: its project's value, else its
+  org's, else the tenant's (`kindgi env set NAME <value>
+  --scope=project:<id> --env=<env>`), with a declared `default` filled in.
+  Strings, and not secret.
+- `ctx.config()`: **reserved, empty today**.
 
 ## Configuration and secrets
 

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

@@ -16,8 +16,8 @@ description: >
   kindgi-authoring-providers.
 type: core
 library: "kindgi-pack (Java)"
-version: "0.1.0"
-sdk_version: "0.1.7"
+version: "0.1.2"
+sdk_version: "0.1.8"
 pack_languages: [java]
 sources:
   - sdks/java/kindgi-pack/README.md
@@ -34,7 +34,7 @@ sources:
 > `./kindgiw <command>`, and `./kindgiw upgrade` moves the pin.
 >
 > **Preview:** Java and Scala support is tested and supported, but its API
-> may still change in 0.1.6 without the usual deprecation period.
+> may still change in a later release without the usual deprecation period.
 
 ## What a pack is
 
@@ -127,7 +127,8 @@ my-pack/
 │   ├── agents/EchoAgent.java                # Agent.define(...)
 │   └── flows/EchoFlow.java                  # Flow.define(...)
 ├── src/test/java/mypack/ToolsTest.java      # the tools, called directly
-└── .claude/skills/                          # these skills (`./kindgiw skills sync` refreshes them)
+├── .claude/skills/                          # these skills (`./kindgiw skills sync` refreshes them)
+└── .agents/skills/                          # the same skills, where Codex and Gemini CLI look
 ```
 
 The package comes from the pack's id (`my-pack` becomes `mypack`).
@@ -256,6 +257,27 @@ names it; one the pack doesn't declare is dropped before the code loads
   primitive (`<pack-id>.<name>`): pick it once.
 - **Model credentials.** Ask for the key; never invent or hard-code one.
 
+## 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`, which asks for the value without echoing it;
+- `./kindgiw auth registry`, which logs Docker in to the runtime image's registry.
+
+Others need what a coding agent's sandbox often blocks: `./kindgiw dev` and any
+dev server of the app (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 (see the tools skill). Never turn that one off either.
+
 ## Keys and tokens: hands off
 
 Never open, read, grep, `cat`, copy or print the files that hold keys and
@@ -274,8 +296,11 @@ model provider. To see which secrets exist, run
 `./kindgiw secrets list --env=local --scope=tenant` (names only). To store one,
 ask the person to run `./kindgiw secrets set NAME --env=local --scope=tenant`
 themselves: it prompts without echoing. Never put a value on a command line.
-`kindgi init` adds these files to the deny rules in `.claude/settings.json`;
-in a monorepo, also to the repository root's, under the pack's path.
+`kindgi init` adds these files to the deny rules in `.claude/settings.json`
+(Claude Code); in a monorepo, also to the repository root's, under the pack's
+path. It adds them to `.cursorignore`, `.geminiignore` or `.aiderignore` too
+when the project has one. Nothing `kindgi init` writes binds Codex. Whichever
+agent you are, keep to the rule above yourself.
 
 ## Next
 
@@ -289,8 +314,8 @@ in a monorepo, also to the repository root's, under the pack's path.
 
 ## Keeping skills up to date
 
-`./kindgiw skills sync` refreshes `.claude/skills/` from the CLI's copy
-(local edits are kept unless `--force`). `kindgi dev` says when they are out
+`./kindgiw skills sync` refreshes `.claude/skills/` and `.agents/skills/`
+from the CLI's copy (local edits are kept unless `--force`). `kindgi dev` says when they are out
 of date.
 
 ## When the framework itself is the problem

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

@@ -16,7 +16,7 @@ description: >
 type: core
 library: "kindgi (Python)"
 version: "0.1.5"
-sdk_version: "0.1.7"
+sdk_version: "0.1.8"
 pack_languages: [python]
 sources:
   - sdks/python/src/kindgi/pack/define.py

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

@@ -17,7 +17,7 @@ description: >
 type: core
 library: "kindgi (Python)"
 version: "0.1.2"
-sdk_version: "0.1.7"
+sdk_version: "0.1.8"
 pack_languages: [python]
 sources:
   - sdks/python/src/kindgi/pack/define.py

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

@@ -15,7 +15,7 @@ description: >
 type: core
 library: "kindgi (Python)"
 version: "0.1.4"
-sdk_version: "0.1.7"
+sdk_version: "0.1.8"
 pack_languages: [python]
 sources:
   - sdks/python/src/kindgi/pack/define.py

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.3"
-sdk_version: "0.1.7"
+version: "0.1.4"
+sdk_version: "0.1.8"
 pack_languages: [python]
 sources:
   - sdks/python/src/kindgi/pack/define.py
@@ -279,6 +279,10 @@ lookup_case = http_tool(
 - Also `timeout_ms=` (default 30000), `parse_json=` (default `True`),
   `success_status=(200, 299)`, `effects=`, `version=`, and
   `mutating=False` for a request that changes nothing (a GET, usually).
+- `timeout_ms` covers the whole call, reading the response included, and
+  so does a run's cancel. A response body over 10 MiB, counted after it's
+  decompressed, fails the call. So point the tool at an endpoint that
+  pages or filters, not one that returns everything.
 
 The spec is checked where it's declared, against the same schema as
 TypeScript's. Calling the tool in Python raises: it runs in Kindgi, so

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.7"
-sdk_version: "0.1.7"
+version: "0.1.8"
+sdk_version: "0.1.8"
 pack_languages: [python]
 sources:
   - sdks/python/README.md
@@ -115,7 +115,8 @@ my-pack/
 ├── flows/echo_flow.py                 # Flow(...)
 ├── tests/test_tools.py                # the tools and the check, called directly
 ├── README.md
-└── .claude/skills/                    # these skills (`kindgi skills sync` refreshes them)
+├── .claude/skills/                    # these skills (`kindgi skills sync` refreshes them)
+└── .agents/skills/                    # the same skills, where Codex and Gemini CLI look
 ```
 
 The `[tool.kindgi]` keys are the ones `kindgi.config.ts` takes —
@@ -302,6 +303,27 @@ build before anything uploads, with the range to use.
   every primitive (`<pack-id>.<name>`); pick it once.
 - **Model credentials.** Ask for the key; never invent or hard-code one.
 
+## 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`, which asks for the value without echoing it;
+- `kindgi auth registry`, which logs Docker in to the runtime image's registry.
+
+Others need what a coding agent's sandbox often blocks: `kindgi dev` and any dev
+server of the app (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 (see the tools skill). Never turn that one off either.
+
 ## Keys and tokens: hands off
 
 Never open, read, grep, `cat`, copy or print the files that hold keys and
@@ -320,8 +342,11 @@ model provider. To see which secrets exist, run
 `kindgi secrets list --env=local --scope=tenant` (names only). To store one,
 ask the person to run `kindgi secrets set NAME --env=local --scope=tenant`
 themselves: it prompts without echoing. Never put a value on a command line.
-`kindgi init` adds these files to the deny rules in `.claude/settings.json`;
-in a monorepo, also to the repository root's, under the pack's path.
+`kindgi init` adds these files to the deny rules in `.claude/settings.json`
+(Claude Code); in a monorepo, also to the repository root's, under the pack's
+path. It adds them to `.cursorignore`, `.geminiignore` or `.aiderignore` too
+when the project has one. Nothing `kindgi init` writes binds Codex. Whichever
+agent you are, keep to the rule above yourself.
 
 ## Next
 
@@ -335,9 +360,9 @@ in a monorepo, also to the repository root's, under the pack's path.
 
 ## Keeping skills up to date
 
-`kindgi skills sync` refreshes `.claude/skills/` from the CLI's copy
-(local edits are kept unless `--force`); `kindgi dev` says when they are
-out of date.
+`kindgi skills sync` refreshes `.claude/skills/` and `.agents/skills/` from
+the CLI's copy (local edits are kept unless `--force`); `kindgi dev` says
+when they are out of date.
 
 ## When the framework itself is the problem
 

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

@@ -16,8 +16,8 @@ description: >
   kindgi-authoring-providers.
 type: core
 library: "kindgi-pack-scala"
-version: "0.1.0"
-sdk_version: "0.1.7"
+version: "0.1.1"
+sdk_version: "0.1.8"
 pack_languages: [scala]
 sources:
   - sdks/scala/README.md
@@ -33,7 +33,7 @@ sources:
 > `kindgi <command>` below runs as `./kindgiw <command>`.
 >
 > Scala support is in preview: tested and supported, but the API may still
-> change in 0.1.6 without the usual deprecation period.
+> change in a later release without the usual deprecation period.
 
 An **agent** is a versioned, model-driven orchestrator. It's made of:
 - instructions (a prompt template);

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

@@ -16,8 +16,8 @@ description: >
   kindgi-scala-authoring-agents.
 type: core
 library: "kindgi-pack-scala"
-version: "0.1.0"
-sdk_version: "0.1.7"
+version: "0.1.2"
+sdk_version: "0.1.8"
 pack_languages: [scala]
 sources:
   - sdks/scala/README.md
@@ -32,7 +32,7 @@ sources:
 > `kindgi <command>` below runs as `./kindgiw <command>`.
 >
 > Scala support is in preview: tested and supported, but the API may still
-> change in 0.1.6 without the usual deprecation period.
+> change in a later release without the usual deprecation period.
 
 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. It
@@ -228,6 +228,12 @@ object TriageTicket {
   `outputSchema`). `convergence` decides the result: `all-succeed`,
   `any-succeed` (the first success wins), or `settle-all` (wait for every
   branch and report each).
+  Every branch gets the fanout's whole input: the output of the step
+  before it (the run input after `$start`). A case class refuses
+  properties it doesn't name, so when a branch tool takes only some of
+  them, its input case class says `@JsonIgnoreProperties(ignoreUnknown = true)`
+  (`com.fasterxml.jackson.annotation`). Without it, the branch fails with
+  `input-validation-failed`.
 - **A sub-flow** (`"kind" -> "subgraph"`) is part of the flow schema, but a
   run refuses it today (`flow-unbound`). Inline the steps instead.
 

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

@@ -15,8 +15,8 @@ description: >
   tools by kindgi-scala-authoring-tools.
 type: core
 library: "kindgi-pack-scala"
-version: "0.1.0"
-sdk_version: "0.1.7"
+version: "0.1.1"
+sdk_version: "0.1.8"
 pack_languages: [scala]
 sources:
   - sdks/scala/README.md
@@ -31,7 +31,7 @@ sources:
 > `kindgi <command>` below runs as `./kindgiw <command>`.
 >
 > Scala support is in preview: tested and supported, but the API may still
-> change in 0.1.6 without the usual deprecation period.
+> change in a later release without the usual deprecation period.
 
 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

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

@@ -15,8 +15,8 @@ description: >
   kindgi-scala-getting-started.
 type: core
 library: "kindgi-pack-scala"
-version: "0.1.0"
-sdk_version: "0.1.7"
+version: "0.1.2"
+sdk_version: "0.1.8"
 pack_languages: [scala]
 sources:
   - sdks/scala/README.md
@@ -32,7 +32,7 @@ sources:
 > your `PATH`.
 >
 > Scala support is in preview: tested and supported, but the API may still
-> change in 0.1.6 without the usual deprecation period.
+> change in a later release without the usual deprecation period.
 
 A **tool** is a unit of work an agent (or a flow step) calls: typed input,
 typed output, your code in between. In a Scala pack it is a `val` of type
@@ -167,7 +167,12 @@ object Citator {
   `ctx.cancellation.onCancel(() => …)`.
 - `ctx.secrets`: the secrets the tool declares (below), as a Java map.
   Printing the context shows their names, never their values.
-- `ctx.env`, `ctx.config`: **reserved, empty today**.
+- `ctx.env`: the env values the tool declares (`set("needsSpec",
+  Map("env" -> …))`), resolved for the call, as a Java map: its project's
+  value, else its org's, else the tenant's (`kindgi env set NAME <value>
+  --scope=project:<id> --env=<env>`), with a declared `default` filled in.
+  Strings, and not secret.
+- `ctx.config`: **reserved, empty today**.
 
 ## Configuration and secrets
 

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

@@ -16,8 +16,8 @@ description: >
   kindgi-authoring-providers.
 type: core
 library: "kindgi-pack-scala"
-version: "0.1.0"
-sdk_version: "0.1.7"
+version: "0.1.2"
+sdk_version: "0.1.8"
 pack_languages: [scala]
 sources:
   - sdks/scala/README.md
@@ -33,7 +33,7 @@ sources:
 > moves the pin, and kindgi-pack-scala's version in `build.sbt` with it.
 >
 > **Preview:** Java and Scala support is tested and supported, but its API
-> may still change in 0.1.6 without the usual deprecation period.
+> may still change in a later release without the usual deprecation period.
 
 ## What a pack is
 
@@ -139,7 +139,8 @@ my-pack/
 │   ├── agents/EchoAgent.scala               # Agent(...)
 │   └── flows/EchoFlow.scala                 # Flow(...)
 ├── src/test/scala/mypack/ToolsSuite.scala   # the tools, called directly (munit)
-└── .claude/skills/                          # these skills (`./kindgiw skills sync` refreshes them)
+├── .claude/skills/                          # these skills (`./kindgiw skills sync` refreshes them)
+└── .agents/skills/                          # the same skills, where Codex and Gemini CLI look
 ```
 
 The package comes from the pack's id, with Java's and Scala's keywords
@@ -287,6 +288,27 @@ names it; one the pack doesn't declare is dropped before the code loads
   primitive (`<pack-id>.<name>`): pick it once.
 - **Model credentials.** Ask for the key; never invent or hard-code one.
 
+## 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`, which asks for the value without echoing it;
+- `./kindgiw auth registry`, which logs Docker in to the runtime image's registry.
+
+Others need what a coding agent's sandbox often blocks: `./kindgiw dev` and any
+dev server of the app (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 (see the tools skill). Never turn that one off either.
+
 ## Keys and tokens: hands off
 
 Never open, read, grep, `cat`, copy or print the files that hold keys and
@@ -305,8 +327,11 @@ model provider. To see which secrets exist, run
 `./kindgiw secrets list --env=local --scope=tenant` (names only). To store one,
 ask the person to run `./kindgiw secrets set NAME --env=local --scope=tenant`
 themselves: it prompts without echoing. Never put a value on a command line.
-`kindgi init` adds these files to the deny rules in `.claude/settings.json`;
-in a monorepo, also to the repository root's, under the pack's path.
+`kindgi init` adds these files to the deny rules in `.claude/settings.json`
+(Claude Code); in a monorepo, also to the repository root's, under the pack's
+path. It adds them to `.cursorignore`, `.geminiignore` or `.aiderignore` too
+when the project has one. Nothing `kindgi init` writes binds Codex. Whichever
+agent you are, keep to the rule above yourself.
 
 ## Next
 
@@ -320,8 +345,8 @@ in a monorepo, also to the repository root's, under the pack's path.
 
 ## Keeping skills up to date
 
-`./kindgiw skills sync` refreshes `.claude/skills/` from the CLI's copy
-(local edits are kept unless `--force`). `kindgi dev` says when they are out
+`./kindgiw skills sync` refreshes `.claude/skills/` and `.agents/skills/`
+from the CLI's copy (local edits are kept unless `--force`). `kindgi dev` says when they are out
 of date.
 
 ## When the framework itself is the problem

package/dist/sdk-skills/kindgi-using/SKILL.md

@@ -15,7 +15,7 @@ description: >
 type: core
 library: "@kindgi/sdk"
 version: "0.1.0"
-sdk_version: "0.1.7"
+sdk_version: "0.1.8"
 pack_languages: [node, python, java, scala]
 ---
 

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;