@kindgi/cli 0.2.0-rc.1 → 0.3.0-rc.0

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

@@ -14,8 +14,8 @@ description: >
   by kindgi-java-getting-started.
 type: core
 library: "kindgi-pack (Java)"
-version: "0.1.4"
-sdk_version: "0.2.0-rc.1"
+version: "0.1.5"
+sdk_version: "0.3.0-rc.0"
 pack_languages: [java]
 sources:
   - sdks/java/kindgi-pack/README.md
@@ -170,7 +170,7 @@ final class Citator {
   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.2/guides/tools/write-a-tool/#make-a-side-effect-happen-once
+  https://docs.kindgi.com/v0.3/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.
@@ -243,7 +243,7 @@ public static final Tool<Input, Output> TOOL = Tool.define("my-pack.send-mail")
 - **Unattended runs:** in a run no person started, a tool that uses a `"person"` connection waits for that person's yes, reads included: `.mutating(false)` doesn't lift it. The agent's own approval settings can't lift it; only a trigger's `toolsAllowedUnattended` can, which a project admin sets, as for `needsApprovalWhenUnattended` (below). In a run a new mail started, the mail is a stranger's text, so two more calls wait: a call of a tool that isn't `.mutating(false)`, and, when the trigger reads the company's mailbox, a read with the company's connection to that app. The mail trigger's `toolsAllowedUnattended` lifts these too.
 - **In a unit test:** `ToolContext.forTest(Map.of("mail", new ToolConnection("c-1", "google", "Google", "test", new ConnectionAccount("1", "ana@acme.com"), null)))`; the last argument, when the token expires, can be `null`. `ctx.connections()` is empty when the tool declares none.
 
-Docs: https://docs.kindgi.com/v0.2/guides/connections/use-a-connection/
+Docs: https://docs.kindgi.com/v0.3/guides/connections/use-a-connection/
 
 ## Errors and output
 
@@ -260,10 +260,16 @@ Docs: https://docs.kindgi.com/v0.2/guides/connections/use-a-connection/
 **`mutating(false)`** declares a tool read-only: it changes nothing outside
 itself (a lookup, a search, a calculation). A dry run
 (`./kindgiw runs start --dry-run`) runs it. Leave it unset for anything that
-writes, sends, charges or deletes: such a tool stops a dry run. It's also
-the tool's approval default: an agent that turns approval gates on
+writes, sends, charges or deletes: such a tool stops a dry run. It's also the
+tool's approval default: an agent that turns approval gates on
 (`conversationPolicy.hitl`) asks before any tool that isn't read-only on its
-first use.
+first use. And it decides what runs together: when a model step asks for
+several calls at once, an agent runs calls to read-only tools (no changing
+effect either) 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 (an agent with
+`set("parallelToolCalls", false)` runs every call on its own). 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.
 
 In a run a new mail started, a call of a tool that isn't read-only waits
 for a person's yes, unless the mail trigger's `toolsAllowedUnattended`
@@ -344,7 +350,7 @@ In a run a person started (signed in, or with their own API key), the agent's ru
       .needsApprovalWhenUnattended(true)
 ```
 
-Docs: https://docs.kindgi.com/v0.2/guides/approvals/ask-before-a-tool-runs/#when-no-person-started-the-run
+Docs: https://docs.kindgi.com/v0.3/guides/approvals/ask-before-a-tool-runs/#when-no-person-started-the-run
 
 ## Results that are text from outside: `resultIsOutsideData`
 
@@ -446,10 +452,11 @@ removed field, a narrower type), not on every save.
 7. **A class the tool uses with `test` or `provided` scope.** It works under
    `kindgi dev` and fails in the image, which copies the runtime classpath
    only. Use `compile` or `runtime` scope.
-8. **A read-only tool without `mutating(false)`.** A dry run stops at it, and
-   an approval gate asks before it on first use.
+8. **A read-only tool without `mutating(false)`.** A dry run stops at it, an
+   approval gate asks before it on first use, and an agent runs each call to
+   it on its own.
 9. **`mutating(false)` on a tool that writes.** A dry run then runs it for
-   real.
+   real, and an agent may run it at the same time as other calls.
 10. **A Jackson module registered only in code, on your own `ObjectMapper`.**
     kindgi-pack finds modules as `findAndRegisterModules()` does, through
     `META-INF/services`. Declare it there, or the tool's input and schema
@@ -460,7 +467,7 @@ removed field, a narrower type), not on every save.
     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.2/guides/secrets/dev-sandbox/).
+    (https://docs.kindgi.com/v0.3/guides/secrets/dev-sandbox/).
 
 ## When the framework itself is the problem
 

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

@@ -17,8 +17,8 @@ description: >
   kindgi-java-authoring-flows; models by kindgi-authoring-providers.
 type: core
 library: "kindgi-pack (Java)"
-version: "0.1.4"
-sdk_version: "0.2.0-rc.1"
+version: "0.1.6"
+sdk_version: "0.3.0-rc.0"
 pack_languages: [java]
 sources:
   - sdks/java/kindgi-pack/README.md
@@ -236,7 +236,7 @@ Show it in the app's own UI. **Never:**
   gives no database access.
 - **link users to Kindgi's console**, or any Kindgi UI, for this data.
 
-Docs: https://docs.kindgi.com/v0.2/guides/runs/show-runs-in-your-app/
+Docs: https://docs.kindgi.com/v0.3/guides/runs/show-runs-in-your-app/
 
 ## Build an image
 
@@ -263,22 +263,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-python-authoring-agents/SKILL.md

@@ -15,8 +15,8 @@ description: >
   model by kindgi-authoring-providers.
 type: core
 library: "kindgi (Python)"
-version: "0.1.7"
-sdk_version: "0.2.0-rc.1"
+version: "0.1.9"
+sdk_version: "0.3.0-rc.0"
 pack_languages: [python]
 sources:
   - sdks/python/src/kindgi/pack/define.py
@@ -124,9 +124,12 @@ brief_writer = Agent(
   `version` is a semver **range**; the highest active matching version
   is picked at turn start. A bare string is rejected. Empty = a
   chat-only agent.
-- **`guardrails`** — `Guardrail` objects or ids. Evaluated once per
-  turn on the final answer, before it is stored. An id with no
-  registered guardrail fails the turn (`unresolved-guardrail`).
+- **`guardrails`** — `Guardrail` objects or ids. They check 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 (`unresolved-guardrail`).
 - **`parameters`** — inputs the caller supplies per run
   (`{"name", "type", "required"}`); they fill `{{ … }}` in the
   instructions.
@@ -160,6 +163,14 @@ brief_writer = Agent(
   the call. 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.
+- **`parallel_tool_calls`** — default on: when a model step asks for several
+  calls at once, calls to read-only tools (`mutating=False`, no changing
+  effect) that come one after another run 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).
 - **`retrieval`** — what the agent reads from memory before each turn;
   empty = no memory. Each intent is a dict with the API's keys:
   `{"types": ["acme.preference"], "scope": "same-user", "mode": "both",
@@ -182,7 +193,8 @@ brief_writer = Agent(
   one person, or instruction-like text, waits for a person's approval.
   Use a model with reliable tool calling. `{"instructionTypes":
   ["acme.policy"]}` makes a retrieved, verified fact of those types an
-  instruction. See https://docs.kindgi.com/v0.2/guides/agents/give-an-agent-memory/.
+  instruction. "Give an agent memory" has the rest:
+  https://docs.kindgi.com/v0.3/guides/agents/give-an-agent-memory/
 
 **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-python-authoring-flows/SKILL.md

@@ -16,8 +16,8 @@ description: >
   kindgi-python-authoring-agents.
 type: core
 library: "kindgi (Python)"
-version: "0.1.2"
-sdk_version: "0.2.0-rc.1"
+version: "0.1.3"
+sdk_version: "0.3.0-rc.0"
 pack_languages: [python]
 sources:
   - sdks/python/src/kindgi/pack/define.py
@@ -37,8 +37,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 `Flow(...)` at module level in
 `flows/<name>.py`. 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.
+step, and 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

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

@@ -5,18 +5,19 @@ description: >
   pack in Python (the `kindgi` package): the `@guardrail` decorator over a
   `(config, trace)` check, `RunTrace` and `CheckResult`, config models,
   actions, severity and scope, unit tests, 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 inside a Python pack's
-  guardrails/ directory (a pack whose config is `[tool.kindgi]` in
-  pyproject.toml), defining a check, or wiring a guardrail onto an agent.
-  Python agents are covered by kindgi-python-authoring-agents, Python tools
-  by kindgi-python-authoring-tools.
+  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
+  inside a Python pack's guardrails/ directory (a pack whose config is
+  `[tool.kindgi]` in pyproject.toml), defining a check, or wiring a
+  guardrail onto an agent. Python agents are covered by
+  kindgi-python-authoring-agents, Python tools by
+  kindgi-python-authoring-tools.
 type: core
 library: "kindgi (Python)"
-version: "0.1.5"
-sdk_version: "0.2.0-rc.1"
+version: "0.1.7"
+sdk_version: "0.3.0-rc.0"
 pack_languages: [python]
 sources:
   - sdks/python/src/kindgi/pack/define.py
@@ -39,6 +40,8 @@ level in a file under `guardrails/` declares both. For an agent turn,
 the runtime evaluates every guardrail the agent lists once, on the final
 answer, before it is stored.
 
+`@guardrail(...)` has no field for the other points a guardrail can run at (`at`, and a check's `points`), so a Python 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.
 
@@ -47,14 +50,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.user_input`), its tool calls and their results
   (`trace.tool_calls`, `trace.tool_results`) and its answer
@@ -136,17 +145,16 @@ def no_fabricated_quotes(config: Config, trace: RunTrace) -> CheckResult:
 - **`id`** — `<pack-id>.<guardrail-name>`, kebab-case. Name the rule as
   a positive assertion: `no-fabricated-quotes`, `response-not-empty`.
 - **`on_violation`** — the action: `"halt"`, `"retry"`, `"escalate"`,
-  `"log-only"`, `"compensate"`. For one that needs settings pass the
-  whole object with `action=` instead (exactly one of the two):
+  `"log-only"`, `"compensate"`. For one that needs settings pass the whole
+  object with `action=` instead (exactly one of the two):
   `action={"on-violation": "retry", "retry": {"maxAttempts": 2}}`,
-  `{"on-violation": "escalate", "escalateTo": …}`,
-  `{"on-violation": "compensate", "compensateWith": "<tool id>"}`.
-  In an agent turn a failed `halt` guardrail fails the turn
-  (`guardrail-violation`) and the answer is not stored; 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.
+  `{"on-violation": "escalate", "escalateTo": …}`, `{"on-violation":
+  "compensate", "compensateWith": "<tool id>"}`. In an agent turn a failed
+  `halt` guardrail fails the turn (`guardrail-violation`) and the answer is
+  not stored; a failed `retry` one sends the answer back for a new one
+  (above); any other action reports the failure in the turn result's
+  `violations` and the turn completes. `escalate` and `compensate` are
+  recorded on the violation, with no escalation or compensating call in 0.1.
 - **`severity`** — `"info"`, `"warn"`, `"error"` (default), `"critical"`.
   Independent of the action: dashboards group by severity, execution
   follows the action.
@@ -206,8 +214,9 @@ references guardrails not in the registry: <id>`).
 2. **Snake_case keys in `config=`.** It is keyed like the wire — the
    model's aliases (`{"minLookups": 2}`), not the field names.
 3. **Both `on_violation=` and `action=`, or neither** — `DefinitionError`.
-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.** Not available; keep checks pure.
 6. **Raising for a broken rule.** Return `CheckResult(passed=False,
    reason=…)`; an exception is an evaluation error, not a violation.

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.6"
-sdk_version: "0.2.0-rc.1"
+version: "0.1.7"
+sdk_version: "0.3.0-rc.0"
 pack_languages: [python]
 sources:
   - sdks/python/src/kindgi/pack/define.py
@@ -114,7 +114,7 @@ def verify_citation(citation: Citation, ctx: ToolContext) -> Verdict:
   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.2/guides/tools/write-a-tool/#make-a-side-effect-happen-once
+  Docs: https://docs.kindgi.com/v0.3/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
@@ -138,7 +138,7 @@ def verify_citation(citation: Citation, ctx: ToolContext) -> Verdict:
   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.2/guides/tools/write-a-tool/#log-from-a-tool
+  https://docs.kindgi.com/v0.3/guides/tools/write-a-tool/#log-from-a-tool
 
 ## Configuration and secrets
 
@@ -239,7 +239,7 @@ def send_mail(message: Message, ctx: ToolContext) -> Sent:
 - **Unattended runs:** in a run no person started, a tool that uses a `"person"` connection waits for that person's yes, reads included: `mutating=False` doesn't lift it. The agent's own approval settings can't lift it; only a trigger's `toolsAllowedUnattended` can, which a project admin sets, as for `needs_approval_when_unattended` (below). In a run a new mail started, the mail is a stranger's text, so two more calls wait: a call of a tool that isn't `mutating=False`, and, when the trigger reads the company's mailbox, a read with the company's connection to that app. The mail trigger's `toolsAllowedUnattended` lifts these too.
 - **In a unit test:** `ToolContext.for_test(connections={"mail": ToolConnection(connection_id="c-1", app="google", app_name="Google", access_token="test", account=ConnectionAccount(id="1", label="ana@acme.com"))})`, all from `kindgi`. `ctx.connections` is empty when the tool declares none.
 
-Docs: https://docs.kindgi.com/v0.2/guides/connections/use-a-connection/
+Docs: https://docs.kindgi.com/v0.3/guides/connections/use-a-connection/
 
 ## Errors and output
 
@@ -263,6 +263,15 @@ approval gates on (`conversation_policy={"hitl": {"tools": {...}}}`)
 and has neither an override for the tool nor a `default` doesn't ask
 before a read-only tool, and asks before any other on first use.
 
+And it decides what runs together: when a model step asks for several calls at
+once, an agent runs calls to read-only tools (no changing effect either) 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. 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. The results reach the conversation and the model in that order
+either way. `Agent(..., parallel_tool_calls=False)` runs every call on its
+own.
+
 In a run a new mail started, a call of a tool that isn't read-only waits
 for a person's yes, unless the mail trigger's `toolsAllowedUnattended`
 lists it.
@@ -301,7 +310,7 @@ def refund(request: RefundRequest) -> Refunded:
     """Refunds an order."""
 ```
 
-Docs: https://docs.kindgi.com/v0.2/guides/approvals/ask-before-a-tool-runs/#when-no-person-started-the-run
+Docs: https://docs.kindgi.com/v0.3/guides/approvals/ask-before-a-tool-runs/#when-no-person-started-the-run
 
 ## Results that are text from outside: `result_is_outside_data`
 
@@ -422,9 +431,10 @@ removed field, a narrower type — not on every save.
    modules — the template's import `tools.x` directly.)
 8. **Blocking inside `async def`.** Use a `def` handler for blocking I/O.
 9. **A read-only tool without `mutating=False`.** A dry run stops at it,
-   and an agent's tool approval gate asks before it on first use.
+   an agent's tool approval gate asks before it on first use, and an
+   agent runs each call to it on its own.
 10. **`mutating=False` on a tool that writes.** A dry run then runs it
-    for real.
+    for real, and an agent may run it at the same time as other calls.
 11. **A package a tool imports, only in a dev group.** The deployed pack
     installs without dev dependencies (`uv sync --no-dev`, or Poetry's
     main group only), so the import works under `kindgi dev` and fails in
@@ -437,7 +447,7 @@ removed field, a narrower type — not on every save.
     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.2/guides/secrets/dev-sandbox/).
+    (https://docs.kindgi.com/v0.3/guides/secrets/dev-sandbox/).
 
 ## When the framework itself is the problem
 

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

@@ -16,8 +16,8 @@ description: >
   models by kindgi-authoring-providers.
 type: core
 library: "kindgi (Python)"
-version: "0.1.10"
-sdk_version: "0.2.0-rc.1"
+version: "0.1.13"
+sdk_version: "0.3.0-rc.0"
 pack_languages: [python]
 sources:
   - sdks/python/README.md
@@ -223,10 +223,13 @@ then `run.id`). The app reads the rest through the API, server side, with
   (`GET /v1/runs/{runId}`); status and timing only: `client.runs.progress(run_id)`.
 - **The audit, step by step:** `client.runs.journal(run_id).data`
   (`GET /v1/runs/{runId}/journal`).
-- **Where an agent's answer came from:** `client.provenance.get(run_id)`
-  (`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
-  (`entry.payload["output"]["runId"]`).
+- **Where an answer came from:** `client.provenance.get(run_id)`
+  (`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 `.step_usage`, its model usage per step. Until it's
+  written, the not-found error's `.details["recordState"]` is `being-written`
+  (or `failed`).
 - **What it cost:** `client.cost.records.list(root_run_id=run_id).data`
   (`GET /v1/cost/records?rootRunId={runId}`): one record per model call,
   with its `model`, `usage` (`prompt_tokens`, `completion_tokens`) and
@@ -258,7 +261,7 @@ month = client.cost.aggregate(
 # month.total_usd; month.groups[i].key ({"month": "2026-10"}), .total_usd, .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:**
 
@@ -270,7 +273,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/
 
 ## Build an image
 
@@ -312,22 +315,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-scala-authoring-agents/SKILL.md

@@ -16,8 +16,8 @@ description: >
   kindgi-authoring-providers.
 type: core
 library: "kindgi-pack-scala"
-version: "0.1.4"
-sdk_version: "0.2.0-rc.1"
+version: "0.1.5"
+sdk_version: "0.3.0-rc.0"
 pack_languages: [scala]
 sources:
   - sdks/scala/README.md
@@ -132,8 +132,10 @@ object 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(Map("name" -> …, "type" -> …, "required" -> …)))`:**
   inputs the caller supplies per run. They fill `{{ … }}` in the
@@ -165,6 +167,12 @@ object 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-scala-authoring-flows/SKILL.md

@@ -16,8 +16,8 @@ description: >
   kindgi-scala-authoring-agents.
 type: core
 library: "kindgi-pack-scala"
-version: "0.1.2"
-sdk_version: "0.2.0-rc.1"
+version: "0.1.3"
+sdk_version: "0.3.0-rc.0"
 pack_languages: [scala]
 sources:
   - sdks/scala/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 `val` of type `Flow` in an object named like its
 file, 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.
+step, and 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