@kindgi/cli 0.1.8 → 0.1.9-rc.1

package/dist/project-ref.js

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { UsageError } from './errors.js';
+/** A project id, as `kindgi deploy --project` tells one from a slug. */
+export const PROJECT_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Every project of the tenant, following `nextCursor` to the last page.
+ * `client`: the runtime to read them from; default, the CLI's own.
+ */
+export async function listAllProjects(ctx, client = ctx.client()) {
+    const rows = [];
+    let cursor;
+    for (;;) {
+        const page = await client.projects.list(cursor !== undefined ? { cursor } : {});
+        rows.push(...(page.data ?? []));
+        if (page.hasMore !== true)
+            break;
+        const next = page.nextCursor;
+        if (typeof next !== 'string' || next === '')
+            break;
+        cursor = next;
+    }
+    return rows;
+}
+/**
+ * A project id-or-slug against a listing: an id goes as it is; a slug is
+ * matched, and a slug that names several projects (a slug is unique within an
+ * org, so two orgs may share one) is ambiguous.
+ */
+export function resolveAgainst(rows, ref) {
+    if (PROJECT_ID_RE.test(ref))
+        return { kind: 'ok', id: ref };
+    const matches = rows.filter((r) => r.slug === ref);
+    if (matches.length === 0)
+        return { kind: 'none' };
+    if (matches.length > 1)
+        return { kind: 'ambiguous', matches };
+    const only = matches[0];
+    return only === undefined ? { kind: 'none' } : { kind: 'ok', id: only.id };
+}
+/**
+ * Each id-or-slug as a project id, listing the projects only when one is a
+ * slug. A slug that names none or several is refused (`UsageError`).
+ * `client`: the runtime to read the projects from; default, the CLI's own.
+ */
+export async function resolveProjectRefs(ctx, refs, client) {
+    const needsList = refs.some((r) => !PROJECT_ID_RE.test(r));
+    const rows = needsList ? await listAllProjects(ctx, client) : [];
+    return refs.map((ref) => idOf(rows, ref));
+}
+/** One id-or-slug as a project id, as `resolveProjectRefs` resolves each. */
+export async function resolveProjectRef(ctx, ref) {
+    return idOf(PROJECT_ID_RE.test(ref) ? [] : await listAllProjects(ctx), ref);
+}
+/** The id `ref` names in `rows`, or a `UsageError` for a slug that names none or several. */
+function idOf(rows, ref) {
+    const resolved = resolveAgainst(rows, ref);
+    if (resolved.kind === 'none') {
+        throw new UsageError(`No project of this tenant has the slug "${ref}". \`kindgi projects list\` shows them; pass a project id instead.`);
+    }
+    if (resolved.kind === 'ambiguous') {
+        const named = resolved.matches
+            .map((m) => `${m.id} (${m.name ?? '?'}${m.orgId === undefined ? '' : `, org ${m.orgId}`})`)
+            .join(', ');
+        throw new UsageError(`"${ref}" is the slug of ${resolved.matches.length} projects, in different orgs: ${named}. Pass the project id instead.`);
+    }
+    return resolved.id;
+}
+//# sourceMappingURL=project-ref.js.map

package/dist/project-ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-ref.js","sourceRoot":"","sources":["../src/project-ref.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAUjC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,wEAAwE;AACxE,MAAM,CAAC,MAAM,aAAa,GAAG,iEAAiE,CAAC;AAU/F;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,GAAmB,EACnB,SAAuB,GAAG,CAAC,MAAM,EAAE;IAEnC,MAAM,IAAI,GAAiB,EAAE,CAAC;IAC9B,IAAI,MAA0B,CAAC;IAC/B,SAAS,CAAC;QACR,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAChF,IAAI,CAAC,IAAI,CAAC,GAAI,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAA2B,CAAC,CAAC;QAC3D,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI;YAAE,MAAM;QACjC,MAAM,IAAI,GAAI,IAA0C,CAAC,UAAU,CAAC;QACpE,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,EAAE;YAAE,MAAM;QACnD,MAAM,GAAG,IAAI,CAAC;IAChB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAOD;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAA2B,EAAE,GAAW;IACrE,IAAI,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC;IAC5D,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC;IACnD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAClD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;IAC9D,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACxB,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC;AAC7E,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,GAAmB,EACnB,IAAuB,EACvB,MAAqB;IAErB,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D,MAAM,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,MAAM,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACjE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;AAC5C,CAAC;AAED,6EAA6E;AAC7E,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,GAAmB,EAAE,GAAW;IACtE,OAAO,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,eAAe,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;AAC9E,CAAC;AAED,6FAA6F;AAC7F,SAAS,IAAI,CAAC,IAA2B,EAAE,GAAW;IACpD,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC3C,IAAI,QAAQ,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC7B,MAAM,IAAI,UAAU,CAClB,2CAA2C,GAAG,oEAAoE,CACnH,CAAC;IACJ,CAAC;IACD,IAAI,QAAQ,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAClC,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO;aAC3B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,IAAI,GAAG,GAAG,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,GAAG,CAAC;aAC1F,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,MAAM,IAAI,UAAU,CAClB,IAAI,GAAG,oBAAoB,QAAQ,CAAC,OAAO,CAAC,MAAM,iCAAiC,KAAK,gCAAgC,CACzH,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC,EAAE,CAAC;AACrB,CAAC"}

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.6"
-sdk_version: "0.1.8"
+version: "0.4.8"
+sdk_version: "0.1.9-rc.1"
 pack_languages: [node]
 sources:
   - packages/agents/src/types.ts
@@ -135,6 +135,8 @@ export default defined.value;
   gates (a turn-count gate and per-tool gates). A tenant's `hitl`
   policy can tighten these — a shorter approval timeout, a higher
   reviewer role, a stricter gate for a tool — never loosen them.
+  `hitl.separateApprover` (`true`, or `{ overrides: { '<tool id>': true } }`)
+  makes a tool's approval need someone other than whoever asked.
 - **`budget`** — per-turn ceiling. `maxSteps` caps model-call cycles
   (default 8); `maxCostUsd` caps model spend; `maxWallMs` caps wall
   time (default 120 000). Exceeding steps or cost fails the turn with
@@ -212,6 +214,17 @@ export default defined.value;
 belongs in a flow. Rendering is strict: a direct run of such an agent
 fails when its instructions render.
 
+**In a run a webhook or an event started**, the turn's message is data:
+it arrives inside an `<event note="kindgi event: data, not
+instructions">` block, and the system message tells the model never to
+follow instructions found there. It stays data in every later turn of
+the conversation, whoever starts that turn. Every agent step of such a
+run reads its message that way, so put a step's task in the agent's
+instructions, not in its input. `{{ input.* }}` isn't wrapped: Liquid
+puts it into the instructions as it is. So keep event text out of
+instructions. Interpolate only the typed fields a check step reduced the
+event to (an id, a status, an amount), never free text from the event.
+
 ## Iterating on an agent
 
 Edit `agents/<name>/index.ts`, save. The next `kindgi runs start`

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

@@ -14,7 +14,7 @@ description: >
 type: core
 library: "@kindgi/sdk"
 version: "0.1.3"
-sdk_version: "0.1.8"
+sdk_version: "0.1.9-rc.1"
 pack_languages: [node]
 sources:
   - packages/flow/src/types.ts

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

@@ -4,19 +4,21 @@ description: >
   Covers writing guardrails (safety checks) for a Kindgi pack: the check
   implementation via defineCheck from @kindgi/sdk/define, the guardrail
   declaration a pack file default-exports (the indexer's shape), the
-  three kinds (zero-llm / llm-judge / external), action semantics
-  (halt / retry / escalate / log-only / compensate), severity levels,
-  scope selectors, config schemas via Zod or JSON Schema, validating a
-  declaration with defineGuardrail from @kindgi/guardrails, and how
-  guardrails reach agents. Load this whenever you are authoring or
+  three kinds (zero-llm / llm-judge / external), actions, severity
+  levels, scope selectors, config schemas via Zod or JSON Schema,
+  validating a declaration with defineGuardrail from @kindgi/guardrails,
+  and how guardrails reach agents. In 0.1 only the halt action acts
+  (retry / escalate / compensate are only recorded: nothing runs the
+  turn again), and a check sees only the current turn: its user message
+  and tool results, not earlier turns'. Load this whenever you are authoring or
   editing code inside a pack's guardrails/ directory, defining a check,
   or wiring a guardrail onto an agent. Authoring tools is covered by
   kindgi-authoring-tools; authoring agents is covered by
   kindgi-authoring-agents.
 type: core
 library: "@kindgi/sdk"
-version: "0.3.9"
-sdk_version: "0.1.8"
+version: "0.3.10"
+sdk_version: "0.1.9-rc.1"
 pack_languages: [node]
 sources:
   - packages/guardrails/src/types.ts
@@ -42,6 +44,41 @@ lives at `guardrails/<name>/index.ts`. For an agent turn, the runtime
 evaluates every guardrail the agent lists once, on the final response,
 before the response is stored.
 
+## What a guardrail can do in 0.1
+
+Read this before you plan a guardrail. Three limits decide what can be
+built:
+
+- **Only `halt` acts.** A failed `halt` guardrail fails the turn with
+  `guardrail-violation`, and the response is not stored. `retry`,
+  `escalate` and `compensate` are recorded on the turn's violations, as
+  `log-only` is, and the turn completes: nothing runs the turn again,
+  escalates or calls a compensating tool. So "block the reply and make the
+  agent try again" can't be a guardrail. Use `halt`: the error names the
+  guardrail and the check's reason, and the message is sent again (by the
+  person, or by your app when it gets `guardrail-violation`).
+- **A check sees one turn.** The trace holds the current turn only: its
+  user message (`trace.userInput`), its tool calls and their results
+  (`trace.toolCalls`, `trace.toolResults`) and its response
+  (`trace.output`). Earlier turns' messages, tool results and responses
+  aren't in it. A check that every figure in the response comes from a
+  tool result or the user's message therefore blocks a response that
+  repeats a figure seen only in an earlier turn.
+- **A check's in-memory state doesn't last.** The check runs in the pack
+  service's process, so anything it keeps at module level (say, a record
+  per `trace.conversationId`) is lost when that process is replaced: under
+  `kindgi dev`, on every reload after a save and on a restart; in a
+  deployment, whenever an instance stops. With more than one instance,
+  each keeps its own copy, and one conversation's turns can land on
+  different instances. Don't keep a conversation's history this way.
+
+What works today for a check on figures: tell the agent, in its
+instructions, to call its tools again in every response that quotes a
+figure, so the figure is in that turn's tool results. It depends on the
+model following the instruction, and it doesn't cover figures the user
+typed in an earlier turn: `trace.userInput` is only the current turn's
+message, so a response that repeats them is still blocked.
+
 ## Mental model: guardrail vs check
 
 - **Check** — the implementation. `defineCheck({ id, kind, configSchema?,

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

@@ -17,8 +17,8 @@ description: >
   `kindgi secrets set` flow.
 type: core
 library: "@kindgi/sdk"
-version: "0.3.3"
-sdk_version: "0.1.8"
+version: "0.3.4"
+sdk_version: "0.1.9-rc.1"
 pack_languages: [node, python, java, scala]
 ---
 
@@ -114,6 +114,15 @@ kindgi secrets set MY_DB_URL --env=local --scope=tenant
 For pipelines/CI: `pbpaste | kindgi secrets set … --from-stdin`, or
 `--from-file=<path>` on a mode-0600 file. Never pass the value on argv.
 
+**When the CLI is signed in to a hosted runtime:** the launcher reads only
+the pack's env files, and `--env=local` is the env of the `kindgi dev`
+runtime that writes them. Run the command in the pack while `kindgi dev`
+runs there: the CLI talks to that runtime, unless `--url` or
+`KINDGI_API_URL` names another. Or the user adds the line to `.env.local`
+by hand. With no `kindgi dev`, the value would go to the hosted runtime,
+where the launcher never reads it; a runtime that keeps its values under
+one env refuses it (`env-not-served`).
+
 **Step 2 — wire the MCP server:**
 
 ```sh

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

@@ -17,14 +17,15 @@ description: >
   router picks the (provider, model) tuple per invocation. Load this
   when the user asks to "register a provider", "use Claude / GPT /
   Groq / Llama / Gemini", "wire Anthropic", "use Vertex", "use Bedrock", "set up an API key for the agent",
+  "give the pack on Kindgi Cloud its model key",
   or when an agent has been authored but the pack has no provider
   registered yet. Authoring agents themselves is covered by
   kindgi-authoring-agents; getting-started is covered by
   kindgi-getting-started.
 type: core
 library: "@kindgi/sdk"
-version: "0.9.15"
-sdk_version: "0.1.8"
+version: "0.9.16"
+sdk_version: "0.1.9-rc.1"
 pack_languages: [node, python, java, scala]
 sources:
   - packages/adapters/model-anthropic/src/provider.ts
@@ -111,6 +112,40 @@ the agent's capability, and the turn's result then carries a
 `fallback-provider` warning. `dev-echo` is one; a cheap local model can be
 yours.
 
+## On Kindgi Cloud: the key and its provider go under `prod`
+
+A pack deployed with `kindgi deploy --hosted` runs on your workspace's
+runtime on Kindgi Cloud, and that runtime serves the `prod` environment,
+before and after you go live. The examples below use `--env=local`, for
+`kindgi dev`. For Kindgi Cloud, name `prod` instead:
+
+```sh
+kindgi secrets set ANTHROPIC_API_KEY --env=prod --scope=tenant   # a no-echo prompt
+kindgi providers register --preset=anthropic --env=prod
+kindgi deploy --hosted --env=prod
+```
+
+- The runtime reads a provider's key in the environment its
+  `secret_ref.envName` names, at tenant scope. Keep the key and the
+  provider both on `prod`. A provider registered without `--env` reads
+  `local`, not the `prod` key: `register` refuses when the pack's own env
+  files lack the key (its message names `--env`), and otherwise the first
+  turn can't find the key (mistake 1). By hand, `provider.json` has
+  `"secret_ref": { "envName": "prod", … }`.
+- `kindgi secrets set` has no default environment: name `--env` every time.
+- The deployment `kindgi deploy` sends names no environment. Its
+  `--env=prod` picks the pack's own `prod` settings, such as its signing
+  key.
+- OpenAI, the Gemini API, Groq and OpenRouter take the same two lines,
+  with their preset and key: `openai` and `OPENAI_API_KEY`, `gemini-api`
+  and `GEMINI_API_KEY`, `groq` and `GROQ_API_KEY`, `openrouter` and
+  `OPENROUTER_API_KEY`. Bedrock, Vertex AI and Azure OpenAI don't fit
+  them: see Amazon Bedrock and Path D below, and `kindgi providers
+  presets` for `azure-openai`'s settings.
+
+The whole flow, from signing the CLI in to going live:
+https://docs.kindgi.com/v0.1/hosted/deploy-your-agent/#your-model-key-and-its-provider
+
 ## Path A — Hosted, native Anthropic
 
 Best fidelity to Anthropic's API (prompt caching, latest models, tool
@@ -123,10 +158,10 @@ then parse, check against the schema and repair, on every provider.
 **Step 1 — set the key:**
 ```sh
 kindgi secrets set ANTHROPIC_API_KEY --env=local --scope=tenant
-# Prompts interactively (echo disabled). Paste the key, press enter.
+# Prompts twice, echo disabled: paste the key, then again to confirm.
 ```
-Writes to `.kindgi/secrets.env` at the pack root via the dotenv secret
-binding — or add `ANTHROPIC_API_KEY=…` to that file yourself; `kindgi dev`
+Under `kindgi dev`, this writes to `.kindgi/secrets.env` at the pack root
+via the dotenv secret binding — or add `ANTHROPIC_API_KEY=…` to that file yourself; `kindgi dev`
 also reads the app's `.env` / `.env.local`. If the pack lives inside an app
 whose env file already has the key, it works as it is; `kindgi secrets copy`
 gives Kindgi its own copy and never edits the app's files (the app may use
@@ -135,6 +170,9 @@ the key itself: leave removing it to the person). Keep env files gitignored. For
 or read from a mode-0600 file with `--from-file <path>`. Never pass a
 credential on argv.
 
+For a pack on Kindgi Cloud, `--env=prod` instead: the key goes to your
+workspace's runtime, not to a file (On Kindgi Cloud, above).
+
 **Step 2 — register it, from the preset:**
 ```sh
 kindgi providers register --preset=anthropic                          # Opus 5.5, Sonnet 5.5 (default), Haiku 5.5, Haiku 4.5
@@ -198,7 +236,8 @@ In a Java or Scala pack's `kindgi.config.json`, the same keys:
   if its region or models differ, a ⚠ line names the
   `kindgi providers unregister` that lets the config's version apply.
 - A runtime `kindgi dev` doesn't run (staging, production) still gets its
-  providers with `kindgi providers register`.
+  providers with `kindgi providers register` (on Kindgi Cloud, with
+  `--env=prod`).
 
 **Step 2 (by hand) — write `provider.json`** at the pack root. One connection,
 two models — matches how the Anthropic SDK actually works (the API
@@ -746,13 +785,17 @@ defineAgent({
    `@kindgi/adapter-model-in-process`; `kindgi providers presets` shows
    the id each preset uses.
 
-1. **`envName` mismatch between the setter (`kindgi secrets set` or `env set`) and `provider.json`.**
-   Both writers use `--env=<name>` (default `local`): `local` is the
-   project's env files (`.env`, `.env.local`), any other name is
-   `.env.<envName>`. If your `provider.json` has
-   `"secret_ref": {"envName": "production", ...}`, the SecretBinding
-   refuses to cross-resolve — you get `secret-not-found` at agent-turn
-   time. Match them.
+1. **`envName` mismatch between the key and the provider's `secret_ref`.**
+   The runtime reads a provider's key in the environment its
+   `secret_ref.envName` names, at tenant scope. The SecretBinding refuses
+   to cross-resolve, so a key held under another environment gives
+   `secret-not-found` at agent-turn time. Where each one lands:
+   `kindgi secrets set` needs `--env=<name>`; `kindgi providers register
+   --preset` writes `--env`'s name, or `local` without it; a `--spec` file
+   names its own (`"secret_ref": {"envName": "production", ...}`). Under
+   `kindgi dev`, `local` is the project's env files (`.env`, `.env.local`)
+   and `.kindgi/secrets.env`; any other name is `.env.<envName>`. Match
+   them. On Kindgi Cloud, both are `prod`.
 
 2. **Missing `features` on the model.** Agent declares
    `capabilities: [{needs: [{feature: 'tool-use'}]}]`; at least one
@@ -844,6 +887,10 @@ kindgi runs start \
   --input='{"userMessage": "test"}'
 ```
 
+On Kindgi Cloud there's no `kindgi dev`: set the key and register the
+provider with `--env=prod` (steps 1 and 2), deploy with
+`kindgi deploy --hosted --env=prod`, then run the agent.
+
 If the run completes with `status: "completed"`, the whole chain works
 end-to-end. If it fails with `secret-not-found`, check point (1). If it
 fails with "no provider satisfies capability", check point (2). If it

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

@@ -12,8 +12,8 @@ description: >
   authoring agents is covered by kindgi-authoring-agents.
 type: core
 library: "@kindgi/sdk"
-version: "0.4.9"
-sdk_version: "0.1.8"
+version: "0.4.10"
+sdk_version: "0.1.9-rc.1"
 pack_languages: [node]
 sources:
   - packages/tools/src/types.ts
@@ -225,6 +225,23 @@ A tool that writes also says what it writes, in `effects`, beside `mutating: tru
 
 The kinds are `reads`, `writes`, `deletes`, `network`, `spawns-run`, `emits-event`, `external-side-effect` and `sensitive-data-egress` (`EFFECT_KINDS` in `@kindgi/tools`); `defineTool` refuses any other. `resource` is free text naming what the tool touches. A read-only tool keeps `effects: []`.
 
+## A person's yes when no one is watching: `needsApprovalWhenUnattended`
+
+`needsApprovalWhenUnattended: true` declares that a person must say yes to every call of the tool in a run no person started: one a schedule, a webhook, an event or a service account's key started. In such a run:
+
+- **An agent's call waits** for a person's yes, whatever the agent's `conversationPolicy.hitl.tools` says. The agent's rules can't lift it: agents are reused, and the tool's author knows what it does.
+- **A flow's tool step that calls it is refused.** Put the tool behind an agent step instead, whose call waits.
+
+In a run a person started (signed in, or with their own API key), the agent's rules decide, as for any tool. Absent means `false`. Declare it on a tool that moves money or changes something people rely on:
+
+```ts
+  effects: [{ kind: 'writes', resource: 'acme:refunds' }],
+  mutating: true,
+  needsApprovalWhenUnattended: true,
+```
+
+Docs: https://docs.kindgi.com/v0.1/guides/approvals/ask-before-a-tool-runs/#when-no-person-started-the-run
+
 A step can run more than once (resumed after an approval, retried after a failure, run again after a crash), so a tool that writes uses `ctx.idempotencyKey`: the same every time this call runs, different for every other call. Pass it to the system you write to (an `Idempotency-Key` header, a client reference, a unique column) or look for it there first, and a refund never goes out twice. Not `ctx.requestId`: a model's call id is only unique within one of its answers. The key is absent 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
 
 ## Tool id convention

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

@@ -12,10 +12,13 @@ description: >
   from authoring skills (which help you build packs) and from
   getting-started (which onboards new packs); this skill turns your
   diagnostic output into durable input for framework improvement.
+  Also load to send entries to Kindgi (only after the person says yes
+  to the preview), to check what became of sent ones at the start of a
+  session, or to take one back.
 type: core
 library: "@kindgi/sdk"
-version: "0.4.3"
-sdk_version: "0.1.8"
+version: "0.4.4"
+sdk_version: "0.1.9-rc.1"
 pack_languages: [node, python, java, scala]
 ---
 
@@ -102,6 +105,80 @@ The entry lands as a new `## <title>` section appended to
 `FEEDBACK.md`, stamped with a fresh `id: YYYY-MM-DD.N`. The file is
 created with a header if it doesn't yet exist.
 
+## Sending it to Kindgi: only with the person's yes
+
+`FEEDBACK.md` stays in the pack until the person decides to send it.
+`kindgi feedback submit` sends entries to Kindgi's private intake on
+access.kindgi.com. Only Kindgi's maintainers read reports there. They're
+kept 90 days, and the person can take one back at any time.
+
+**Never send on your own.** Every time:
+
+1. **Preview.** Run `kindgi feedback submit --preview`, or name entries by
+   id or hash: `kindgi feedback submit 2026-09-25.3 --preview`. With none
+   named it takes every entry not sent yet and not marked fixed. It prints
+   exactly what would be sent, after redaction, and its `digest`. Nothing
+   is sent.
+2. **Show the person.** Show them each entry's title and body as they'll
+   go, and the environment sent with them: the OS, Node and CLI versions,
+   the pack's language, and `kindgi doctor`'s checks as id and status
+   only. Point out anything redaction missed, like a customer's name or an
+   internal host name. If something shouldn't go, edit the entry in
+   `FEEDBACK.md` and preview again.
+3. **Ask, then send.** Ask "Send this to Kindgi?" Only after a clear yes,
+   run the same command with `--yes=<digest>` in place of `--preview`. If
+   anything changed since the preview, it refuses: preview and ask again.
+
+If `submit` says "Kindgi may have received it" (the answer was lost, came
+too late, or couldn't be read), tell the person, and don't send again on
+your own: a second send makes a second report, and one that arrived can't
+be withdrawn from this machine. Let them decide.
+
+What redaction takes out before the preview:
+- the home directory alone becomes `~`, and paths in the pack become `./…`;
+- other absolute paths become `[path]`, a path under `~` too;
+- values from the pack's `.env*` files and `.kindgi/secrets.env` become
+  `[redacted]`;
+- private keys and token shapes become `[redacted]` (a Kindgi token keeps
+  its prefix and last four characters);
+- a URL keeps its host and path but loses its user info and query values;
+- email addresses become `[email]`.
+
+It can't catch everything in free text: the preview is the check.
+
+Once sent, each entry gets a line like
+`- **submitted:** 2026-09-25T15:02:11.000Z · **report:** fbr_…`. The
+report id isn't a secret, so `FEEDBACK.md` can still be committed. The key
+that takes a report back is kept in `~/.kindgi/feedback/keys.json` on this
+machine and is never printed. Don't read or copy that file.
+
+If `KINDGI_FEEDBACK_SUBMIT=off` is set, `submit` refuses. That's the
+person's or their team's choice, so don't work around it. `write`,
+`status` and `withdraw` still work.
+
+## Hearing back
+
+At the start of a session, when `FEEDBACK.md` has submitted entries, run
+`kindgi feedback status`. It asks about each report at most once a day,
+and never again once it's fixed, won't be fixed, or was withdrawn, or once
+the intake doesn't have it (past its 90 days) unless it's named. A fixed
+entry gets `> **Fixed:** in <version> (report fbr_…)` under its heading.
+Tell the person what changed:
+- **fixed**, with the version: suggest upgrading to it;
+- **known**, with the public issue when there is one;
+- **won't fix**, with the one-line reason.
+
+Name an entry or a report id (`kindgi feedback status 2026-09-25.3`) to
+ask about it now. A teammate's report id works too: it isn't a secret.
+
+## Taking one back
+
+When the person asks to withdraw a report, run
+`kindgi feedback withdraw <id|hash|reportId>`. The intake clears its text
+at once, and the entry's line gets `· **withdrawn:** <date>`. It needs the
+key on the machine that sent the report. A withdrawn entry isn't sent again
+unless the person names it in `submit`.
+
 ## Entry shape (what the CLI produces)
 
 ```md
@@ -202,7 +279,8 @@ directly for maintenance operations within one pack.
    write` once per bug. Each gets its own number, its own fix
    status, its own removal path.
 4. **Sensitive state in reproducers.** Reproducer sections sometimes
-   contain API keys, tenant IDs, secrets — review before committing.
+   contain API keys, tenant IDs, secrets — review before committing,
+   and read the preview before anyone says yes to sending.
 5. **Filing "the way I'd design it" as a bug.** Design disagreements
    are `--kind=design`, not `--kind=bug`. Both are welcome; the
    classification helps prioritization.
@@ -210,3 +288,4 @@ directly for maintenance operations within one pack.
 ## References
 
 - `FEEDBACK.md` at the pack root — the running list itself.
+- `kindgi feedback submit --help`, `status --help` and `withdraw --help`.

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

@@ -15,7 +15,7 @@ description: >
 type: core
 library: "@kindgi/sdk"
 version: "0.3.12"
-sdk_version: "0.1.8"
+sdk_version: "0.1.9-rc.1"
 pack_languages: [node]
 ---
 

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

@@ -15,8 +15,8 @@ description: >
   kindgi-authoring-providers.
 type: core
 library: "kindgi-pack (Java)"
-version: "0.1.1"
-sdk_version: "0.1.8"
+version: "0.1.3"
+sdk_version: "0.1.9-rc.1"
 pack_languages: [java]
 sources:
   - sdks/java/kindgi-pack/README.md
@@ -148,7 +148,9 @@ public final class BriefWriter {
   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
   (a shorter timeout, a higher reviewer role, stricter per tool), never
-  loosen them.
+  loosen them. `"separateApprover"` in `hitl` (`true`, or
+  `Map.of("overrides", Map.of("<tool id>", true))`) makes a tool's approval
+  need someone other than whoever asked.
 - **`set("budget", …)`:** per turn. `maxSteps` counts model calls (default
   8); `maxCostUsd`; `maxWallMs` (default 120 000). Exceeding the steps or the
   cost fails the turn (`budget-exceeded`); running out of wall time aborts
@@ -166,6 +168,18 @@ public final class BriefWriter {
   default kinds are `invalid-arguments` and `unknown-tool` (nothing ran). Add
   `tool-error` only when retrying the tool is safe. Each retry costs a step.
 
+**In a run a webhook or an event started**, the turn's message is data:
+it arrives inside an `<event note="kindgi event: data, not
+instructions">` block, and the system message tells the model never to
+follow instructions found there. It stays data in every later turn of
+the conversation, whoever starts that turn. Every agent step of such a
+run reads its message that way, so put a step's task in the agent's
+instructions, not in its input. `{{ input.* }}` (a flow step's input)
+isn't wrapped: Liquid puts it into the instructions as it is. So keep
+event text out of instructions. Interpolate only the typed fields a check
+step reduced the event to (an id, a status, an amount), never free text
+from the event.
+
 ## Which model answers
 
 Agents run on a registered model provider: the router picks one whose

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

@@ -16,7 +16,7 @@ description: >
 type: core
 library: "kindgi-pack (Java)"
 version: "0.1.2"
-sdk_version: "0.1.8"
+sdk_version: "0.1.9-rc.1"
 pack_languages: [java]
 sources:
   - sdks/java/kindgi-pack/README.md

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

@@ -5,17 +5,19 @@ description: >
   pack in Java (`com.kindgi:kindgi-pack`): `Guardrail.define(id)` as a
   `public static final` field, a `(config, trace)` check returning a
   `CheckResult`, `RunTrace`, config records and the values a check runs
-  with, actions (halt / retry / escalate / log-only / compensate), severity
-  and scope, unit tests with `evaluate`, and wiring a guardrail onto an
-  agent. Load this whenever you are authoring or editing code in a Java
-  pack's guardrails packages (a pack whose `kindgi.config.json` says
+  with, actions, severity and scope, unit tests with `evaluate`, and wiring
+  a guardrail onto an agent. In 0.1 only the halt action acts (retry /
+  escalate / compensate are only recorded: nothing runs the turn again), and
+  a check sees only the current turn: its user message and tool results, not
+  earlier turns'. Load this whenever you are authoring or editing code in a
+  Java pack's guardrails packages (a pack whose `kindgi.config.json` says
   `"language": "java"`), defining a check, or wiring a guardrail onto an
   agent. Java agents are covered by kindgi-java-authoring-agents, Java tools
   by kindgi-java-authoring-tools.
 type: core
 library: "kindgi-pack (Java)"
-version: "0.1.1"
-sdk_version: "0.1.8"
+version: "0.1.2"
+sdk_version: "0.1.9-rc.1"
 pack_languages: [java]
 sources:
   - sdks/java/kindgi-pack/README.md
@@ -43,6 +45,41 @@ stored.
 Ask what the rule should catch before writing one. The sample
 `response-not-empty` guardrail is a demonstration, not a template.
 
+## What a guardrail can do in 0.1
+
+Read this before you plan a guardrail. Three limits decide what can be
+built:
+
+- **Only `halt` acts.** A failed `halt` guardrail fails the turn with
+  `guardrail-violation`, and the answer is not stored. `retry`, `escalate`
+  and `compensate` are recorded on the turn's violations, as `log-only`
+  is, and the turn completes: nothing runs the turn again, escalates or
+  calls a compensating tool. So "block the reply and make the agent try
+  again" can't be a guardrail. Use `halt`: the error names the guardrail
+  and the check's reason, and the message is sent again (by the person, or
+  by your app when it gets `guardrail-violation`).
+- **A check sees one turn.** The trace holds the current turn only: its
+  user message (`trace.userInput()`), its tool calls and their results
+  (`toolCalls()`, `toolResults()`) and its answer (`output()`). Earlier
+  turns' messages, tool results and answers aren't in it. A check that
+  every figure in the answer comes from a tool result or the user's
+  message therefore blocks an answer that repeats a figure seen only in an
+  earlier turn.
+- **A check's in-memory state doesn't last.** The check runs in the pack
+  service's process, so anything it keeps in a `static` field (say, a map
+  of conversations) is lost when that process is replaced: under `kindgi
+  dev`, on every reload after a save and on a restart; in a deployment,
+  whenever an instance stops. With more than one instance, each keeps its
+  own copy, and one conversation's turns can land on different instances.
+  Don't keep a conversation's history this way.
+
+What works today for a check on figures: tell the agent, in its
+instructions, to call its tools again in every answer that quotes a
+figure, so the figure is in that turn's tool results. It depends on the
+model following the instruction, and it doesn't cover figures the user
+typed in an earlier turn: `trace.userInput()` is only the current turn's
+message, so an answer that repeats them is still blocked.
+
 ## A guardrail
 
 ```java