@kindgi/cli 0.2.0 → 0.3.0-rc.0

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

@@ -17,8 +17,8 @@ description: >
   session, or to take one back.
 type: core
 library: "@kindgi/sdk"
-version: "0.4.4"
-sdk_version: "0.2.0"
+version: "0.5.0"
+sdk_version: "0.3.0-rc.0"
 pack_languages: [node, python, java, scala]
 ---
 
@@ -105,185 +105,15 @@ 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
+## Your case: read this file
 
-`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
-## preferredProvider silently dropped by wire schema
-
-- **id:** 2026-09-25.3
-- **hash:** feedback-a3f2c1d0
-- **kind:** bug
-- **severity:** high
-- **date:** 2026-09-25T14:32:07.104Z
-- **sdk:** 0.1.2 · **cli:** 0.1.2 · **by:** claude-code
-
-### Summary
-One-line: what the report is about.
-
-### Observed
-What happened, with file:line pointers when possible.
-
-### Expected
-What should have happened.
-
-### Reproducer
-Exact commands, spec files, output.
-
-### Suggested fix
-Optional; leave blank if you don't have one.
-
----
-```
-
-## Editing FEEDBACK.md directly
-
-Entries are referenced locally by their `id` (e.g. `2026-09-25.3`)
-or by their title; across packs (or between peers) they are referenced
-by their `hash` (e.g. `feedback-a3f2c1d0`). When the pack author says
-something like:
-
-- **"Remove 2026-09-25.3"** / **"Remove the preferredProvider
-  entry"** → find the section whose `id` matches (or whose `##
-  <title>` matches), delete from the header down through the next
-  `---` separator (inclusive). Do NOT renumber other entries — ids
-  are historical identifiers, gaps are expected.
-- **"Mark 2026-09-25.3 fixed"** / **"That preferredProvider one
-  landed in commit abc123"** → find the section, insert a line
-  right after the header:
-  ```md
-  > **Fixed:** landed in commit abc123 (2026-09-25). <optional context>
-  ```
-- **"Note that 2026-09-25.5 is a duplicate of feedback-a3f2c1d0"** /
-  **"Merge these — same hash"** → find the section, insert:
-  ```md
-  > **Duplicate of:** feedback-a3f2c1d0 (<optional context>)
-  ```
-  Prefer the `hash` when the duplicate lives in another pack (peer /
-  framework side); prefer the `id` when it's a local duplicate.
-- **Restructuring / re-ordering** → use the Edit tool to move the
-  section; keep the header + `- **id:** …` + `- **hash:** …` lines
-  intact so both identifiers stay stable.
-
-Do NOT try to re-file the same item through `kindgi feedback write`
-— that would create a new entry with a new id (though the hash
-would match, which is exactly the p2p-dedup signal). Always edit
-directly for maintenance operations within one pack.
-
-## Fields to fill precisely
-
-- **`kind`** — honest classification.
-  - `bug` — the framework did the wrong thing (crashed, silently
-    dropped a field, contradicted its own docs).
-  - `friction` — the framework did the "right" thing but the UX cost
-    more time than the task warranted.
-  - `question` — you don't understand something and the docs don't
-    answer it.
-  - `design` — you observed something that works as designed but the
-    design might be wrong.
-
-- **`severity`** — honest impact.
-  - `blocker` — nothing useful can happen until this is fixed.
-  - `high` — a common workflow is broken; users will hit this.
-  - `medium` — real friction, but there's a documented workaround.
-  - `low` — cosmetic, tiny annoyance, or affects one obscure path.
-
-- **`authored_by`** — `claude-code` when the diagnostic came entirely
-  from an AI coding assistant; `human` when the pack author wrote
-  it; `mixed` when it's a combination.
-
-## Common mistakes
-
-1. **File-path-only entries** ("bug in router.ts").
-   Without a reproducer + expected behavior, the maintainer has to
-   reverse-engineer your session. File:line is necessary but not
-   sufficient.
-2. **Skipping "Suggested fix" when you have one.** If you diagnosed
-   the root cause, name it. "Add `preferredProvider` to `AgentSchema`
-   in `packages/api/src/openapi/schemas.ts:667`" is worth a dozen
-   back-and-forth clarifications.
-3. **Bundling multiple bugs into one entry.** Run `kindgi feedback
-   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,
-   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.
+| Your case | Read |
+|---|---|
+| Filling `kind`, `severity` and `authored_by`, and what an entry looks like | [fields-and-entry-shape.md](fields-and-entry-shape.md) |
+| Sending entries to Kindgi: never without the person's yes to the preview | [sending.md](sending.md) |
+| What became of sent reports, at the start of a session, or taking one back | [hearing-back.md](hearing-back.md) |
+| Removing, marking fixed, marking a duplicate or re-ordering entries in `FEEDBACK.md` | [editing-feedback-file.md](editing-feedback-file.md) |
+| Before you file: what makes a report hard to act on | [common-mistakes.md](common-mistakes.md) |
 
 ## References
 

package/dist/sdk-skills/kindgi-framework-feedback/common-mistakes.md

@@ -0,0 +1,19 @@
+# Common mistakes
+
+1. **File-path-only entries** ("bug in router.ts").
+   Without a reproducer + expected behavior, the maintainer has to
+   reverse-engineer your session. File:line is necessary but not
+   sufficient.
+2. **Skipping "Suggested fix" when you have one.** If you diagnosed
+   the root cause, name it. "Add `preferredProvider` to `AgentSchema`
+   in `packages/api/src/openapi/schemas.ts:667`" is worth a dozen
+   back-and-forth clarifications.
+3. **Bundling multiple bugs into one entry.** Run `kindgi feedback
+   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,
+   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.

package/dist/sdk-skills/kindgi-framework-feedback/editing-feedback-file.md

@@ -0,0 +1,33 @@
+# Editing FEEDBACK.md directly
+
+Entries are referenced locally by their `id` (e.g. `2026-09-25.3`)
+or by their title; across packs (or between peers) they are referenced
+by their `hash` (e.g. `feedback-a3f2c1d0`). When the pack author says
+something like:
+
+- **"Remove 2026-09-25.3"** / **"Remove the preferredProvider
+  entry"** → find the section whose `id` matches (or whose `##
+  <title>` matches), delete from the header down through the next
+  `---` separator (inclusive). Do NOT renumber other entries — ids
+  are historical identifiers, gaps are expected.
+- **"Mark 2026-09-25.3 fixed"** / **"That preferredProvider one
+  landed in commit abc123"** → find the section, insert a line
+  right after the header:
+  ```md
+  > **Fixed:** landed in commit abc123 (2026-09-25). <optional context>
+  ```
+- **"Note that 2026-09-25.5 is a duplicate of feedback-a3f2c1d0"** /
+  **"Merge these — same hash"** → find the section, insert:
+  ```md
+  > **Duplicate of:** feedback-a3f2c1d0 (<optional context>)
+  ```
+  Prefer the `hash` when the duplicate lives in another pack (peer /
+  framework side); prefer the `id` when it's a local duplicate.
+- **Restructuring / re-ordering** → use the Edit tool to move the
+  section; keep the header + `- **id:** …` + `- **hash:** …` lines
+  intact so both identifiers stay stable.
+
+Do NOT try to re-file the same item through `kindgi feedback write`
+— that would create a new entry with a new id (though the hash
+would match, which is exactly the p2p-dedup signal). Always edit
+directly for maintenance operations within one pack.

package/dist/sdk-skills/kindgi-framework-feedback/fields-and-entry-shape.md

@@ -0,0 +1,53 @@
+# An entry: the fields to fill, and its shape
+
+## Fields to fill precisely
+
+- **`kind`** — honest classification.
+  - `bug` — the framework did the wrong thing (crashed, silently
+    dropped a field, contradicted its own docs).
+  - `friction` — the framework did the "right" thing but the UX cost
+    more time than the task warranted.
+  - `question` — you don't understand something and the docs don't
+    answer it.
+  - `design` — you observed something that works as designed but the
+    design might be wrong.
+
+- **`severity`** — honest impact.
+  - `blocker` — nothing useful can happen until this is fixed.
+  - `high` — a common workflow is broken; users will hit this.
+  - `medium` — real friction, but there's a documented workaround.
+  - `low` — cosmetic, tiny annoyance, or affects one obscure path.
+
+- **`authored_by`** — `claude-code` when the diagnostic came entirely
+  from an AI coding assistant; `human` when the pack author wrote
+  it; `mixed` when it's a combination.
+
+## Entry shape (what the CLI produces)
+
+```md
+## preferredProvider silently dropped by wire schema
+
+- **id:** 2026-09-25.3
+- **hash:** feedback-a3f2c1d0
+- **kind:** bug
+- **severity:** high
+- **date:** 2026-09-25T14:32:07.104Z
+- **sdk:** 0.1.2 · **cli:** 0.1.2 · **by:** claude-code
+
+### Summary
+One-line: what the report is about.
+
+### Observed
+What happened, with file:line pointers when possible.
+
+### Expected
+What should have happened.
+
+### Reproducer
+Exact commands, spec files, output.
+
+### Suggested fix
+Optional; leave blank if you don't have one.
+
+---
+```

package/dist/sdk-skills/kindgi-framework-feedback/hearing-back.md

@@ -0,0 +1,24 @@
+# Hearing back, and taking one back
+
+## 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`.

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

@@ -0,0 +1,50 @@
+# 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.

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

@@ -16,8 +16,8 @@ description: >
   primitive.
 type: core
 library: "@kindgi/sdk"
-version: "0.3.16"
-sdk_version: "0.2.0"
+version: "0.3.19"
+sdk_version: "0.3.0-rc.0"
 pack_languages: [node]
 ---
 
@@ -287,10 +287,13 @@ const run = await kindgi.runs.start({
   (`GET /v1/runs/{runId}`); status and timing only: `kindgi.runs.progress(runId)`.
 - **The audit, step by step:** `kindgi.runs.journal(runId)`
   (`GET /v1/runs/{runId}/journal`).
-- **Where an agent's answer came from:** `kindgi.provenance.get(runId)`
-  (`GET /v1/provenance/{runId}`). A flow run has none of its own: each agent
-  step's `step.completed` entry in the flow's journal names its turn's run
-  (`payload.output.runId`).
+- **Where an answer came from:** `kindgi.provenance.get(runId)`
+  (`GET /v1/provenance/{runId}`). An agent turn's record has its model and
+  tool calls. A finished flow run has its own record: a `step` node per step
+  (`step:<nodeId>`, a loop's iterations `step:<nodeId>@<loop>#<i>`) with the
+  `runs` it started, and `stepUsage`, its model usage per step. Until it's
+  written, the not-found error's `fields.recordState` is `being-written` (or
+  `failed`).
 - **What it cost:** `kindgi.cost.usage.query({ rootRunId: runId })`
   (`GET /v1/cost/records?rootRunId={runId}`): `.data`, one record per model
   call, with its `model`, `usage` (`promptTokens`, `completionTokens`) and
@@ -321,7 +324,7 @@ const month = await kindgi.cost.usage.summary({
 // month.totalUsd; month.groups[i].key ({ month: '2026-10' }), .totalUsd, .tokens
 ```
 
-Docs: https://docs.kindgi.com/v0.2/guides/observability/cost-per-run/
+Docs: https://docs.kindgi.com/v0.3/guides/observability/cost-per-run/
 
 Show it in the app's own UI. **Never:**
 
@@ -332,7 +335,7 @@ Show it in the app's own UI. **Never:**
 - **link users to Kindgi's console** or any Kindgi UI for this data.
 
 To keep a copy (reporting, search), pull it through the API into the app's
-own tables. Docs: https://docs.kindgi.com/v0.2/guides/runs/show-runs-in-your-app/
+own tables. Docs: https://docs.kindgi.com/v0.3/guides/runs/show-runs-in-your-app/
 
 ## Upgrading a deployment
 
@@ -342,22 +345,22 @@ doesn't have yet, then serving. Migrations only go forward: an upgrade
 starts with a backup of the database, and going back means restoring it and
 running the older version on it.
 
-- **On Cloud Run, a small dev deployment** (`network_mode = "none"`, on
-  runtime 0.1.8 or later): the Cloud Run module's `./upgrade.sh`, as of the
-  `@kindgi/sdk@<version>` tag of the release you're upgrading to, since it
-  knows the steps up to its own release. Run `./upgrade.sh --dry-run` first:
-  it changes nothing, and lists what a real run would change. Its plan also
-  reads every `*.auto.tfvars.json` in the module's folder (the pack's env),
-  and `yes` applies exactly the saved plan it showed. The module README's
-  Upgrading section has the rest:
+- **On Cloud Run, a deployment of the module** (on runtime 0.1.8 or later,
+  in any `network_mode`; before the `@kindgi/sdk@0.3.0` tag, `"none"` only):
+  the module's `./upgrade.sh`, as of the `@kindgi/sdk@<version>` tag of the
+  release you're upgrading to, since it knows the steps up to its own
+  release. It takes a `--var-file` for each file the deployment's variables
+  are in. Run `./upgrade.sh --dry-run` first: it changes nothing, and lists
+  what a real run would change. A real run's `yes` applies exactly the
+  saved plan it showed. The module README's Upgrading section has the rest:
   https://github.com/kindgi/kindgi-sdk/tree/main/deploy/gcp-cloud-run#upgrading
 - **Any other Cloud Run deployment:** by hand, staging first, as the Cloud
   Run page's "Upgrade by hand" section says:
-  https://docs.kindgi.com/v0.2/deploy/self-hosted/cloud-run/#upgrade-by-hand
-- **On Azure Container Apps:** the "Operate it" section of its page,
-  https://docs.kindgi.com/v0.2/deploy/self-hosted/azure-container-apps/#operate-it.
-- **Otherwise:** the operate page's upgrade steps,
-  https://docs.kindgi.com/v0.2/deploy/self-hosted/operate/#upgrade-the-runtime.
+  https://docs.kindgi.com/v0.3/deploy/self-hosted/cloud-run/#upgrade-by-hand
+- **On Azure Container Apps:** the "Operate it" section of its page:
+  https://docs.kindgi.com/v0.3/deploy/self-hosted/azure-container-apps/#operate-it
+- **Otherwise:** the operate page's upgrade steps:
+  https://docs.kindgi.com/v0.3/deploy/self-hosted/operate/#upgrade-the-runtime
 
 An upgrade changes a running deployment: give the person the commands to run
 in their own terminal (`./upgrade.sh` waits for them to type `yes`).

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.4"
-sdk_version: "0.2.0"
+version: "0.1.5"
+sdk_version: "0.3.0-rc.0"
 pack_languages: [java]
 sources:
   - sdks/java/kindgi-pack/README.md
@@ -134,8 +134,10 @@ public final class BriefWriter {
   **`tool(id, range)`** is a tool of another pack, with a semver **range**
   (`"^1.0.0"`); the highest active matching version is picked at turn
   start. An agent with no tools is chat-only.
-- **`guardrail(Guardrail)`** or **`guardrail(id)`:** evaluated once per turn
-  on the final answer, before it is stored. An id with no registered
+- **`guardrail(Guardrail)`** or **`guardrail(id)`:** checks the final answer,
+  before it is stored. One whose action is `retry` sends the answer back to
+  the model for a new one, up to `retry.maxAttempts` answers in all (default
+  2); then the turn fails (`guardrail-violation`). An id with no registered
   guardrail fails the turn.
 - **`set("parameters", List.of(Map.of("name", …, "type", …, "required", …)))`:**
   inputs the caller supplies per run. They fill `{{ … }}` in the
@@ -167,6 +169,12 @@ public final class BriefWriter {
   goes back to the model as the call's result, so it can fix the call. The
   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.
+- **`set("parallelToolCalls", false)`:** when a model step asks for several
+  calls at once, an agent runs calls to read-only tools (`mutating(false)`, no
+  changing effect) that come one after another at the same time, up to 8 of
+  them, and any other call on its own, in the order the model asked; the results reach the conversation in that order either way. A call that may wait, for another system's answer or for the person who started the run to connect an app, runs on its own too. `false`
+  runs every call on its own, for read-only tools that mustn't overlap (a
+  rate-limited API, say).
 
 **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

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.2"
-sdk_version: "0.2.0"
+version: "0.1.3"
+sdk_version: "0.3.0-rc.0"
 pack_languages: [java]
 sources:
   - sdks/java/kindgi-pack/README.md
@@ -38,8 +38,10 @@ 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
 is **data**, not code: a `public static final Flow` field of a class in a
 `flows` package. The runtime runs it step by step, journals every step, and
-can resume a run that was interrupted. A run pins the flow version it
-started on.
+can resume a run that was interrupted. A run keeps the flow version it
+started on. A run that names no version takes the version pinned for its
+project (or its org, or the tenant), else the newest version the project
+reaches.
 
 Use a flow when the order of the work is known: parse, then classify, then
 branch, then write. Use a single agent when the model should decide the

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

@@ -6,18 +6,18 @@ description: >
   `public static final` field, a `(config, trace)` check returning a
   `CheckResult`, `RunTrace`, config records and the values a check runs
   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.
+  a guardrail onto an agent. halt fails the turn and retry sends the answer
+  back to the model for a new one (escalate / compensate are only recorded
+  in 0.1), 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.2"
-sdk_version: "0.2.0"
+version: "0.1.4"
+sdk_version: "0.3.0-rc.0"
 pack_languages: [java]
 sources:
   - sdks/java/kindgi-pack/README.md
@@ -42,6 +42,8 @@ class in a `guardrails` package. For an agent turn, the runtime evaluates
 every guardrail the agent lists once, on the final answer, before it is
 stored.
 
+`Guardrail.define` has no field for the other points a guardrail can run at (`at`, and a check's `points`), so a Java guardrail runs at the final answer only; the points are documented at https://docs.kindgi.com/v0.3/guides/guardrails/configure-a-guardrail/#where-in-the-turn-it-runs.
+
 Ask what the rule should catch before writing one. The sample
 `response-not-empty` guardrail is a demonstration, not a template.
 
@@ -50,14 +52,20 @@ Ask what the rule should catch before writing one. The sample
 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`).
+- **`halt` and `retry` act.** A failed `halt` guardrail fails the turn with
+  `guardrail-violation`, and the answer is not stored. A failed `retry`
+  guardrail sends the answer back to the model, with the check's reason in a
+  user message, for a new one; the failed answer isn't stored. When it has
+  failed `retry.maxAttempts` answers (the first one included; 2 when left
+  out), the turn fails with `guardrail-violation` and
+  `details.attempts`. Each new answer is a model call that the agent's
+  `budget.maxSteps` counts. The `halt` and `retry` guardrails judge each
+  answer, a judge's calls included, which `budget.maxCostUsd` doesn't count;
+  the others judge only the answer that's sent. A new answer can call tools
+  again, side-effecting ones included, with approvals as usual. `escalate`
+  and `compensate` are recorded on the turn's violations, as `log-only` is,
+  and the turn completes: nothing escalates or calls a compensating tool. So
+  "block the reply and make the agent try again" is a `retry` guardrail.
 - **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
@@ -155,11 +163,12 @@ public final class Citations {
   builder refuses a check with neither.
   - In an agent turn, a failed `halt` guardrail fails the turn
     (`guardrail-violation`), and the answer is not stored.
+  - A failed `retry` guardrail sends the answer back for a new one, up to
+    its `maxAttempts` answers (above).
   - Any other action reports the failure in the turn result's `violations`,
     and the turn completes.
-  - In 0.1 the runtime acts only on `halt`: `retry`, `escalate` and
-    `compensate` are recorded on the violation, with no second attempt,
-    escalation or compensating call.
+  - `escalate` and `compensate` are recorded on the violation, with no
+    escalation or compensating call in 0.1.
 - **`severity`:** `info`, `warn`, `error` (default) or `critical`. It's
   independent of the action: dashboards group by severity, and execution
   follows the action.
@@ -229,8 +238,9 @@ no registered guardrail fails the turn before the model is called
 2. **`set("config", …)` keyed by Java names.** It's keyed like the wire: the
    record's Jackson names.
 3. **No `onViolation` or `action`.** The builder refuses the check.
-4. **Expecting another attempt.** `halt` stops the turn, and in 0.1 `retry`
-   doesn't run the turn again: it's only recorded.
+4. **Expecting `halt` to try again.** `halt` stops the turn; `retry` asks
+   the model for a new answer, and fails the turn once its `maxAttempts`
+   answers have failed.
 5. **Calling a model from the check.** That isn't available: keep checks
    pure.
 6. **Throwing for a broken rule.** Return `CheckResult.fail(…)`. An