@kindgi/cli 0.1.5-rc.0 → 0.1.6-rc.0

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

@@ -15,7 +15,7 @@ description: >
 type: core
 library: "kindgi-pack (Java)"
 version: "0.1.0"
-sdk_version: "0.1.5-rc.0"
+sdk_version: "0.1.6-rc.0"
 pack_languages: [java]
 sources:
   - sdks/java/kindgi-pack/README.md

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

@@ -15,7 +15,7 @@ description: >
 type: core
 library: "kindgi-pack (Java)"
 version: "0.1.0"
-sdk_version: "0.1.5-rc.0"
+sdk_version: "0.1.6-rc.0"
 pack_languages: [java]
 sources:
   - sdks/java/kindgi-pack/README.md
@@ -161,8 +161,16 @@ final class Citator {
 
 - `ctx.tenantId()`: the tenant the call is for. Key per-tenant state by it.
 - `ctx.runId()`: the run (an agent turn or a flow step) the call belongs to.
-- `ctx.requestId()`: this call, such as the model's tool-call id. Useful for
-  logs and idempotency keys.
+- `ctx.requestId()`: this call, such as the model's tool-call id. For logs:
+  a model's call id is only unique within one of its answers, so don't
+  dedupe on it.
+- `ctx.idempotencyKey()`: the same every time this call runs (resumed,
+  retried, or run again after a crash), different for every other call. A
+  step can run more than once, so a tool that writes passes it to the system
+  it writes to (an `Idempotency-Key` header, a client reference, a unique
+  column) or looks for it there first: a refund never goes out twice. A
+  UUID; `null` outside a run and from a runtime before 0.1.6. Docs:
+  https://docs.kindgi.com/v0.1/guides/tools/write-a-tool/#make-a-side-effect-happen-once
 - `ctx.projectId()`, `ctx.orgId()`: the run's project, and its org (`null`
   when it has none). The runtime sets them from the run, never from the
   input. To check an id the input names, compare it with these.
@@ -181,20 +189,28 @@ A secret that belongs to the tenant, such as an API key a customer gives
 you, is declared with `set("needsSpec", …)` and read from `ctx.secrets()`, as
 above. The runtime resolves every declared secret on every call, for the
 call's tenant, in its env (`KINDGI_ENV`; under `kindgi dev`, `local`: the
-pack's `.env` and `.env.local`). It checks each against its schema, and fails
-the call, naming the secret, when one is missing or doesn't match. Every
-declared secret is required.
+pack's `.env` and `.env.local`, then Kindgi's own `.kindgi/secrets.env`, where
+`./kindgiw secrets set` writes). It checks each against its schema, and fails
+the call, naming the secret, when one is missing or doesn't match. A
+declared secret is required, unless its schema names null
+(`"type": ["string", "null"]`): an optional one the env doesn't have, or has
+empty, is absent from `ctx.secrets`, and the call goes on (runtime 0.1.6 or
+later; an older runtime requires it).
 
 Everything else comes from the process environment: `System.getenv("CITATOR_URL")`.
 Under `kindgi dev`, the pack service gets the pack's `.env` and `.env.local`,
 and restarts when they change. Nothing else from your shell reaches it
 except `PATH`, `HOME` and `TMPDIR`; `MAVEN_ARGS` and `MAVEN_OPTS` reach Maven
-only. Put a secret there by hand, or with
-`./kindgiw secrets set NAME --env=local --scope=tenant` (a no-echo prompt),
-and keep the env files out of git. A deployed service names the variables
-it needs in `kindgi.config.json`: `"env": {"required": ["DATABASE_URL"],
-"optional": ["SENTRY_DSN"]}`. Without a required one it isn't ready.
-`KINDGI_*` names are Kindgi's own and never reach pack code.
+only. Put a setting there by hand, and keep the env files out of git. A
+secret stored with `./kindgiw secrets set NAME --env=local --scope=tenant` (a
+no-echo prompt) never reaches the process environment: declare it and read it
+from `ctx.secrets()`. A model provider's key reaches no tool at all: a tool
+that calls a model declares a key of its own. A deployed service names the
+variables it needs in `kindgi.config.json`: `"env": {"required": ["DATABASE_URL"],
+"optional": ["SENTRY_DSN"]}`. Without a required one it isn't ready, and
+every variable it doesn't declare is dropped before your code loads
+(`kindgi dev` keeps them), so an undeclared one works locally and is unset
+once deployed. `KINDGI_*` names are Kindgi's own: a pack can't declare one.
 
 ## Errors and output
 
@@ -327,6 +343,13 @@ removed field, a narrower type), not on every save.
     `META-INF/services`. Declare it there, or the tool's input and schema
     won't see it.
 
+11. **Turning the dev sandbox off for a file the tool needs.** Under `kindgi dev`
+    the tool's code runs sandboxed: it can't read outside the app (the home
+    folder, `~/.aws`) or any `.env*` file, and gets `EPERM` there. A tool that
+    needs a path names it in `kindgi.config.json`: `"dev": {"sandbox": {"allowRead": ["~/.aws"]}}`.
+    Never set `KINDGI_DEV_SANDBOX=off` or `dev.sandbox: false` to get past it
+    (https://docs.kindgi.com/v0.1/guides/secrets/dev-sandbox/).
+
 ## When the framework itself is the problem
 
 If the bug is in Kindgi or kindgi-pack (a schema derived wrong, a misleading

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

@@ -17,7 +17,7 @@ description: >
 type: core
 library: "kindgi-pack (Java)"
 version: "0.1.0"
-sdk_version: "0.1.5-rc.0"
+sdk_version: "0.1.6-rc.0"
 pack_languages: [java]
 sources:
   - sdks/java/kindgi-pack/README.md
@@ -103,8 +103,10 @@ A tool there is a class in a `kindgi.tools` package under the app's own
 (`com.acme.app.kindgi.tools`), and calls the app's code directly. A class a
 tool uses must be on the runtime classpath (`compile` or `runtime` scope,
 not `test` or `provided`): the image copies the runtime dependencies only.
-`kindgi dev` reads the app's `.env` and `.env.local`: keys already there
-reach the tools as environment variables.
+`kindgi dev` reads the app's `.env` and `.env.local`: values already there
+reach the tools as environment variables. A secret stored with `kindgi
+secrets set` doesn't: a tool reads it from its context (`needsSpec.secrets`).
+Nor does a model provider's key, which no tool gets.
 
 ## Layout of the template
 
@@ -146,7 +148,7 @@ key and register its preset (Anthropic below; `./kindgiw providers presets`
 lists OpenAI, Gemini, Groq and OpenRouter too):
 
 ```sh
-./kindgiw secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt; writes .env.local
+./kindgiw secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt; writes .kindgi/secrets.env
 ./kindgiw providers register --preset=anthropic
 ```
 
@@ -240,7 +242,8 @@ image installs them: `"image": {"systemPackages": ["tesseract-ocr"]}`
 (names, or `name=version`). So are the variables the code reads, names only:
 `"env": {"required": ["DATABASE_URL"], "optional": ["SENTRY_DSN"]}`. A
 deployed pack service missing a required one isn't ready, and its `/readyz`
-names it.
+names it; one the pack doesn't declare is dropped before the code loads
+(`kindgi dev` keeps it).
 
 ## Two things need the human
 
@@ -248,6 +251,27 @@ names it.
   primitive (`<pack-id>.<name>`): pick it once.
 - **Model credentials.** Ask for the key; never invent or hard-code one.
 
+## Keys and tokens: hands off
+
+Never open, read, grep, `cat`, copy or print the files that hold keys and
+tokens, in any folder of the repository (not only the pack's), and never
+print their values (`env`, `printenv`, or code that echoes the process
+environment):
+
+- `.env`, `.env.local` and any other `.env.*`: the app's settings, and any key
+  put there by hand;
+- `.kindgi/secrets.env`: Kindgi's own secrets, where `./kindgiw secrets set` writes;
+- `.kindgi/dev/runtime.env`: the dev runtime's token and database URL;
+- a self-hosted deployment's `kindgi.env` or `pack.env`.
+
+A value you read lands in your context and in every later request to the
+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.
+
 ## Next
 
 - A tool: `kindgi-java-authoring-tools`.

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.5-rc.0"
+sdk_version: "0.1.6-rc.0"
 pack_languages: [python]
 sources:
   - sdks/python/src/kindgi/pack/define.py
@@ -169,6 +169,10 @@ brief_writer = Agent(
   fails the turn (`semantic-unavailable`). `{"source": "conversations",
   "scope": "same-user"}` recalls this agent's earlier conversations: the
   people's own words only, unless `"roles": ["user", "agent"]`.
+  `same-user` memory (facts, recall or `remember`) is the run's end user's:
+  pass `participantId` on every run. A run without one reads and keeps
+  none (its result warns `memory-needs-participant`), never the memory of
+  the user a key acts for, who may serve many people.
 - **`memory`** — `{"remember": {"types": ["acme.preference"], "scope":
   "same-user", "keepDays": 30}}` gives the turn the built-in tool
   `kindgi_remember` (name it exactly so in the instructions). The model

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.5-rc.0"
+sdk_version: "0.1.6-rc.0"
 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.5-rc.0"
+sdk_version: "0.1.6-rc.0"
 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.2"
-sdk_version: "0.1.5-rc.0"
+version: "0.1.3"
+sdk_version: "0.1.6-rc.0"
 pack_languages: [python]
 sources:
   - sdks/python/src/kindgi/pack/define.py
@@ -103,8 +103,16 @@ def verify_citation(citation: Citation, ctx: ToolContext) -> Verdict:
 - `ctx.tenant_id` — the tenant the call is for. Key any per-tenant
   state by it.
 - `ctx.run_id` — the run (an agent turn or a flow step) the call belongs to.
-- `ctx.request_id` — this call, e.g. the model's tool-call id; useful
-  for logs and idempotency keys.
+- `ctx.request_id` — this call, e.g. the model's tool-call id; for logs.
+  A model's call id is only unique within one of its answers: don't
+  dedupe on it.
+- `ctx.idempotency_key` — the same every time this call runs (resumed,
+  retried, or run again after a crash), different for every other call. A
+  step can run more than once, so a tool that writes passes it to the
+  system it writes to (an `Idempotency-Key` header, a client reference, a
+  unique column) or looks for it there first: a refund never goes out
+  twice. A UUID; `None` outside a run and from a runtime before 0.1.6.
+  Docs: https://docs.kindgi.com/v0.1/guides/tools/write-a-tool/#make-a-side-effect-happen-once
 - `ctx.project_id`, `ctx.org_id` — the run's project, and that project's
   org (`None` when it has none). The runtime sets them from the run, never
   from the input: to check an org or project id the input names, compare
@@ -121,6 +129,14 @@ def verify_citation(citation: Citation, ctx: ToolContext) -> Verdict:
   (`kindgi env set NAME <value> --scope=project:<id> --env=<env>`).
   Strings, and not secret. Empty from an older runtime.
 - `ctx.config` — **reserved, empty today**.
+- `ctx.log` — a logger bound to the call (its records carry the run's ids,
+  the tool's id and the trace id): `ctx.log.info("refund issued",
+  {"orderId": order_id, "amountCents": amount_cents})`, or the fields as
+  keywords. Values go in the fields, never in the message. Log ids,
+  amounts and outcomes, never what a person typed (a refund's reason, a
+  message, an address): the log is read by whoever operates the runtime.
+  `ToolContext.for_test(…)` logs nothing unless you pass it `log=`. Docs:
+  https://docs.kindgi.com/v0.1/guides/tools/write-a-tool/#log-from-a-tool
 
 ## Configuration and secrets
 
@@ -139,9 +155,13 @@ def verify_citation(citation: Citation, ctx: ToolContext) -> Verdict:
 
 The runtime resolves every declared secret on every call — for the
 call's tenant, in its env (`KINDGI_ENV`; in `kindgi dev`, `local`: the
-pack's `.env` and `.env.local`) — checks it against its schema, and
+pack's `.env` and `.env.local`, then Kindgi's own `.kindgi/secrets.env`, where
+`kindgi secrets set` writes) — checks it against its schema, and
 fails the call, naming the secret, when it is missing or doesn't match.
-Every declared secret is required. In a test, pass them:
+A declared secret is required, unless its schema names null
+(`{"type": ["string", "null"]}`): an optional one the env doesn't have, or
+has empty, is absent from `ctx.secrets` (read it with `.get`), and the call
+goes on (runtime 0.1.6 or later; an older runtime requires it). In a test, pass them:
 `ToolContext.for_test(secrets={"CITATOR_KEY": "…"})`.
 
 A value that differs per tenant, org or project but isn't secret (a base URL, a region, an account id) is an **env value**: declared in `needs_spec`, read from `ctx.env`:
@@ -175,10 +195,17 @@ Everything else comes from the process environment: `os.environ["CITATOR_URL"]`.
 The pack service runs with the pack's environment — in `kindgi dev`
 that is the pack's `.env` and `.env.local` (or `[tool.kindgi.dev]
 envFiles`), restarted when they change; nothing else from your shell
-reaches it except `PATH`, `HOME` and `TMPDIR`. Put a secret there by
-hand or with `kindgi secrets set NAME --env=local --scope=tenant` (a
-no-echo prompt), and keep the env files out of git. `KINDGI_*` names
-are Kindgi's own settings and never reach pack code.
+reaches it except `PATH`, `HOME` and `TMPDIR`. Put a setting there by
+hand, and keep the env files out of git. A secret stored with `kindgi
+secrets set NAME --env=local --scope=tenant` (a no-echo prompt) never
+reaches the process environment: declare it and read it from
+`ctx.secrets`. A model provider's key reaches no tool at all: a tool
+that calls a model declares a key of its own. Declare every name the
+code reads in `[tool.kindgi.env]` (`required`, `optional`): in an image
+the pack service drops every other variable before your code loads
+(`kindgi dev` keeps them), so an undeclared one works locally and is
+unset once deployed. `KINDGI_*` names are Kindgi's own settings: a pack
+can't declare one.
 
 ## Errors and output
 
@@ -334,6 +361,13 @@ removed field, a narrower type — not on every save.
     Poetry 1 app, `[tool.poetry.dependencies]`); test and build tools stay
     in dev groups.
 
+12. **Turning the dev sandbox off for a file the tool needs.** Under `kindgi dev`
+    the tool's code runs sandboxed: it can't read outside the app (the home
+    folder, `~/.aws`) or any `.env*` file, and gets `EPERM` there. A tool that
+    needs a path names it in `pyproject.toml`: `[tool.kindgi.dev.sandbox]` `allowRead = ["~/.aws"]`.
+    Never set `KINDGI_DEV_SANDBOX=off` or `dev.sandbox: false` to get past it
+    (https://docs.kindgi.com/v0.1/guides/secrets/dev-sandbox/).
+
 ## When the framework itself is the problem
 
 If the bug is in Kindgi or the `kindgi` package (a schema derived wrong,

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

@@ -15,7 +15,7 @@ description: >
 type: core
 library: "kindgi (Python)"
 version: "0.1.7"
-sdk_version: "0.1.5-rc.0"
+sdk_version: "0.1.6-rc.0"
 pack_languages: [python]
 sources:
   - sdks/python/README.md
@@ -92,8 +92,10 @@ The pack root is on `sys.path`, so tools import the app's own packages by
 name (`from acme.text import normalize`); inside `kindgi/`, import the pack's
 modules relatively. Don't add an `__init__.py` to `kindgi/` — the folder
 would then shadow the `kindgi` package. `kindgi dev` reads the app's `.env`
-/ `.env.local` — keys already there reach the tools as environment
-variables. A package a tool imports must be in the app's main dependencies,
+/ `.env.local` — values already there reach the tools as environment
+variables; a secret stored with `kindgi secrets set` doesn't (a tool reads
+it from `ctx.secrets`), and neither does a model provider's key, which no tool
+gets. A package a tool imports must be in the app's main dependencies,
 not a dev group: the deployed pack installs without dev dependencies (see
 `kindgi-python-authoring-tools`).
 
@@ -277,7 +279,8 @@ system-packages = ["tesseract-ocr", "poppler-utils"]   # names, or name=version
 
 The variables the code reads from `os.environ` (a database URL, a bucket)
 are declared too, names only. A deployed pack service missing a `required`
-one isn't ready, and its `/readyz` names it:
+one isn't ready, and its `/readyz` names it; one the pack doesn't declare is
+dropped before the code loads (`kindgi dev` keeps it):
 
 ```toml
 [tool.kindgi.env]
@@ -294,6 +297,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.
 
+## Keys and tokens: hands off
+
+Never open, read, grep, `cat`, copy or print the files that hold keys and
+tokens, in any folder of the repository (not only the pack's), and never
+print their values (`env`, `printenv`, or code that echoes the process
+environment):
+
+- `.env`, `.env.local` and any other `.env.*`: the app's settings, and any key
+  put there by hand;
+- `.kindgi/secrets.env`: Kindgi's own secrets, where `kindgi secrets set` writes;
+- `.kindgi/dev/runtime.env`: the dev runtime's token and database URL;
+- a self-hosted deployment's `kindgi.env` or `pack.env`.
+
+A value you read lands in your context and in every later request to the
+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.
+
 ## Next
 
 - A tool → `kindgi-python-authoring-tools`.

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

@@ -17,7 +17,7 @@ description: >
 type: core
 library: "kindgi-pack-scala"
 version: "0.1.0"
-sdk_version: "0.1.5-rc.0"
+sdk_version: "0.1.6-rc.0"
 pack_languages: [scala]
 sources:
   - sdks/scala/README.md
@@ -138,10 +138,10 @@ object BriefWriter {
 - **`set("parameters", List(Map("name" -> …, "type" -> …, "required" -> …)))`:**
   inputs the caller supplies per run. They fill `{{ … }}` in the
   instructions.
-- **`set("preferredProvider", "anthropic")`, `set("preferredModel", "claude-haiku-4-5")`:**
+- **`set("preferredProvider", "anthropic")`, `set("preferredModel", "claude-haiku-5-5")`:**
   soft hints. The router prefers them when they satisfy the capabilities.
   To *require* a model, put it in the capability:
-  `Map("needs" -> List(Map("feature" -> "tool-use"), Map("models" -> Map("allow" -> List("claude-haiku-4-5")))))`.
+  `Map("needs" -> List(Map("feature" -> "tool-use"), Map("models" -> Map("allow" -> List("claude-haiku-5-5")))))`.
 - **`set("conversationPolicy", …)`:** `historyLimit` caps the prior messages
   loaded, and `hitl` configures approval gates. Absent, the turn loads the
   full history with no gates. A tenant's `hitl` policy can tighten the gates

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

@@ -17,7 +17,7 @@ description: >
 type: core
 library: "kindgi-pack-scala"
 version: "0.1.0"
-sdk_version: "0.1.5-rc.0"
+sdk_version: "0.1.6-rc.0"
 pack_languages: [scala]
 sources:
   - sdks/scala/README.md

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

@@ -16,7 +16,7 @@ description: >
 type: core
 library: "kindgi-pack-scala"
 version: "0.1.0"
-sdk_version: "0.1.5-rc.0"
+sdk_version: "0.1.6-rc.0"
 pack_languages: [scala]
 sources:
   - sdks/scala/README.md

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

@@ -16,7 +16,7 @@ description: >
 type: core
 library: "kindgi-pack-scala"
 version: "0.1.0"
-sdk_version: "0.1.5-rc.0"
+sdk_version: "0.1.6-rc.0"
 pack_languages: [scala]
 sources:
   - sdks/scala/README.md
@@ -147,8 +147,16 @@ object Citator {
 
 - `ctx.tenantId`: the tenant the call is for. Key per-tenant state by it.
 - `ctx.runId`: the run (an agent turn or a flow step) the call belongs to.
-- `ctx.requestId`: this call, such as the model's tool-call id. Useful for
-  logs and idempotency keys.
+- `ctx.requestId`: this call, such as the model's tool-call id. For logs: a
+  model's call id is only unique within one of its answers, so don't dedupe
+  on it.
+- `ctx.idempotencyKey`: the same every time this call runs (resumed,
+  retried, or run again after a crash), different for every other call. A
+  step can run more than once, so a tool that writes passes it to the system
+  it writes to (`Option(ctx.idempotencyKey).foreach(k => request.header("Idempotency-Key", k))`)
+  or looks for it there first: a refund never goes out twice. A UUID; `null`
+  outside a run and from a runtime before 0.1.6. Docs:
+  https://docs.kindgi.com/v0.1/guides/tools/write-a-tool/#make-a-side-effect-happen-once
 - `ctx.projectId`, `ctx.orgId`: the run's project, and its org (`null` when
   it has none). The runtime sets them from the run, never from the input.
   To check an id the input names, compare it with these.
@@ -167,20 +175,28 @@ A secret that belongs to the tenant, such as an API key a customer gives
 you, is declared with `set("needsSpec", …)` and read from `ctx.secrets`, as
 above. The runtime resolves every declared secret on every call, for the
 call's tenant, in its env (`KINDGI_ENV`; under `kindgi dev`, `local`: the
-pack's `.env` and `.env.local`). It checks each against its schema, and fails
-the call, naming the secret, when one is missing or doesn't match. Every
-declared secret is required.
+pack's `.env` and `.env.local`, then Kindgi's own `.kindgi/secrets.env`, where
+`./kindgiw secrets set` writes). It checks each against its schema, and fails
+the call, naming the secret, when one is missing or doesn't match. A
+declared secret is required, unless its schema names null
+(`"type": ["string", "null"]`): an optional one the env doesn't have, or has
+empty, is absent from `ctx.secrets`, and the call goes on (runtime 0.1.6 or
+later; an older runtime requires it).
 
 Everything else comes from the process environment: `sys.env("CITATOR_URL")`.
 Under `kindgi dev`, the pack service gets the pack's `.env` and `.env.local`,
 and restarts when they change. Nothing else from your shell reaches it
-except `PATH`, `HOME` and `TMPDIR`; `SBT_OPTS` reaches sbt only. Put a secret
-there by hand, or with `./kindgiw secrets set NAME --env=local --scope=tenant`
-(a no-echo prompt), and keep the env files out of git. A deployed service
-names the variables it needs in `kindgi.config.json`:
+except `PATH`, `HOME` and `TMPDIR`; `SBT_OPTS` reaches sbt only. Put a setting
+there by hand, and keep the env files out of git. A secret stored with
+`./kindgiw secrets set NAME --env=local --scope=tenant` (a no-echo prompt)
+never reaches the process environment: declare it and read it from
+`ctx.secrets`. A model provider's key reaches no tool at all: a tool that calls
+a model declares a key of its own. A deployed service names the variables it needs in `kindgi.config.json`:
 `"env": {"required": ["DATABASE_URL"], "optional": ["SENTRY_DSN"]}`. Without
-a required one it isn't ready. `KINDGI_*` names are Kindgi's own and never
-reach pack code.
+a required one it isn't ready, and every variable it doesn't declare is
+dropped before your code loads (`kindgi dev` keeps them), so an undeclared
+one works locally and is unset once deployed. `KINDGI_*` names are Kindgi's
+own: a pack can't declare one.
 
 ## Errors and output
 
@@ -294,6 +310,13 @@ changes (a removed field, a narrower type), not on every save.
     `jackson-databind` minor version.** It refuses to load: depend on the
     matching one.
 
+12. **Turning the dev sandbox off for a file the tool needs.** Under `kindgi dev`
+    the tool's code runs sandboxed: it can't read outside the app (the home
+    folder, `~/.aws`) or any `.env*` file, and gets `EPERM` there. A tool that
+    needs a path names it in `kindgi.config.json`: `"dev": {"sandbox": {"allowRead": ["~/.aws"]}}`.
+    Never set `KINDGI_DEV_SANDBOX=off` or `dev.sandbox: false` to get past it
+    (https://docs.kindgi.com/v0.1/guides/secrets/dev-sandbox/).
+
 ## When the framework itself is the problem
 
 If the bug is in Kindgi, kindgi-pack or the Scala layer (a schema derived

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

@@ -17,7 +17,7 @@ description: >
 type: core
 library: "kindgi-pack-scala"
 version: "0.1.0"
-sdk_version: "0.1.5-rc.0"
+sdk_version: "0.1.6-rc.0"
 pack_languages: [scala]
 sources:
   - sdks/scala/README.md
@@ -115,8 +115,10 @@ A tool there is a `val` of an object in a `kindgi.tools` package under the
 app's own (`com.acme.app.kindgi.tools`), and calls the app's code directly. A
 library a tool uses must be on the runtime classpath (not `% Test` or
 `% Provided`): the image ships the runtime classpath only. `kindgi dev` reads
-the app's `.env` and `.env.local`: keys already there reach the tools as
-environment variables.
+the app's `.env` and `.env.local`: values already there reach the tools as
+environment variables. A secret stored with `kindgi secrets set` doesn't: a
+tool reads it from its context (`needsSpec.secrets`). Nor does a model
+provider's key, which no tool gets.
 
 ## Layout of the template
 
@@ -158,7 +160,7 @@ key and register its preset (Anthropic below; `./kindgiw providers presets`
 lists OpenAI, Gemini, Groq and OpenRouter too):
 
 ```sh
-./kindgiw secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt; writes .env.local
+./kindgiw secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt; writes .kindgi/secrets.env
 ./kindgiw providers register --preset=anthropic
 ```
 
@@ -256,7 +258,8 @@ image installs them: `"image": {"systemPackages": ["tesseract-ocr"]}`
 (names, or `name=version`). So are the variables the code reads, names only:
 `"env": {"required": ["DATABASE_URL"], "optional": ["SENTRY_DSN"]}`. A
 deployed pack service missing a required one isn't ready, and its `/readyz`
-names it.
+names it; one the pack doesn't declare is dropped before the code loads
+(`kindgi dev` keeps it).
 
 ## Known limits
 
@@ -279,6 +282,27 @@ names it.
   primitive (`<pack-id>.<name>`): pick it once.
 - **Model credentials.** Ask for the key; never invent or hard-code one.
 
+## Keys and tokens: hands off
+
+Never open, read, grep, `cat`, copy or print the files that hold keys and
+tokens, in any folder of the repository (not only the pack's), and never
+print their values (`env`, `printenv`, or code that echoes the process
+environment):
+
+- `.env`, `.env.local` and any other `.env.*`: the app's settings, and any key
+  put there by hand;
+- `.kindgi/secrets.env`: Kindgi's own secrets, where `./kindgiw secrets set` writes;
+- `.kindgi/dev/runtime.env`: the dev runtime's token and database URL;
+- a self-hosted deployment's `kindgi.env` or `pack.env`.
+
+A value you read lands in your context and in every later request to the
+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.
+
 ## Next
 
 - A tool: `kindgi-scala-authoring-tools`.

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

@@ -52,7 +52,7 @@ 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
+kindgi secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt; writes .kindgi/secrets.env
 kindgi providers register --preset=anthropic                      # Opus 5.5, Sonnet 5.5, Haiku 4.5
 ```
 

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

@@ -55,7 +55,7 @@ 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
+{{KINDGI}} secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt; writes .kindgi/secrets.env
 {{KINDGI}} providers register --preset=anthropic                      # Opus 5.5, Sonnet 5.5 (default), Haiku 5.5, Haiku 4.5
 ```
 

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

@@ -42,7 +42,7 @@ 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
+{{KINDGI}} secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt; writes .kindgi/secrets.env
 {{KINDGI}} providers register --preset=anthropic                      # Opus 5.5, Sonnet 5.5 (default), Haiku 5.5, Haiku 4.5
 ```
 

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

@@ -47,7 +47,7 @@ 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
+{{KINDGI}} secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt; writes .kindgi/secrets.env
 {{KINDGI}} providers register --preset=anthropic                      # Opus 5.5, Sonnet 5.5 (default), Haiku 5.5, Haiku 4.5
 ```
 

package/dist/templates/sample/tools/fetch-httpbin/index.ts.tmpl

@@ -16,7 +16,8 @@
 //
 // The runtime resolves the secret on every call from its secrets
 // store, in the env the ref names — under `kindgi dev`, env `local`
-// is your `.env` / `.env.local`. A secret it can't find fails the
+// is your `.env` / `.env.local`, then Kindgi's own `.kindgi/secrets.env`
+// (where `kindgi secrets set` writes). A secret it can't find fails the
 // call with `secret-unavailable`, naming it.
 
 import { defineTool } from '@kindgi/sdk/define';

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

@@ -58,7 +58,7 @@ use a real model, set one LLM provider's key and register its preset, with
 `kindgi dev` running, from another terminal. For Claude:
 
 ```sh
-./kindgiw secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt; writes .env.local
+./kindgiw secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt; writes .kindgi/secrets.env
 ./kindgiw providers register --preset=anthropic                      # Opus 5.5, Sonnet 5.5, Haiku 4.5
 ```