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

package/dist/sdk-skills/kindgi-fix-corrections/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: kindgi-fix-corrections
+description: >
+  Turn the experts' corrections of a Kindgi agent into fixes. Load this when
+  the person says "fix what the experts corrected", "the agent keeps getting
+  <X> wrong, correct it", "turn the refund agent's corrections into changes",
+  or points you at an agent's "no" judgments. The loop: pull the runs an
+  expert marked wrong, read why, and sort each correction to where it belongs
+  — a rule in code, a setting, an approval rule, or the agent's instructions —
+  add a pack test per correction, then publish and ask a person to make the
+  new version live, naming the corrections it fixes. Making a version live
+  and approving it stay with the person, and a correction that would loosen
+  anything — raise a limit, widen a window, drop a check — goes to the owner,
+  not the agent.
+type: core
+library: "@kindgi/sdk"
+version: "0.1.0"
+sdk_version: "0.2.0-rc.1"
+pack_languages: [node, python, java, scala]
+sources:
+  - packages/cli/src/commands/judgments.ts
+  - packages/cli/src/commands/runs.ts
+  - packages/cli/src/commands/blocks.ts
+  - packages/cli/src/commands/agents.ts
+  - packages/cli/src/commands/eval-runs.ts
+  - packages/cli/src/commands/test.ts
+---
+
+# Fixing what the experts corrected
+
+> **Running `kindgi`:** in a Node project the CLI is a devDependency
+> (`@kindgi/cli`), not a global command. Run it through the project's
+> package manager — `pnpm exec kindgi …`, `npx --no -- kindgi …` (npm),
+> `yarn kindgi …` or `bun run kindgi …`. A Python pack (`[tool.kindgi]` in
+> `pyproject.toml`) has no Node project: run the `kindgi` on `PATH`. A Java
+> or Scala pack (`kindgi.config.json`) runs the CLI it pins: `./kindgiw …`.
+> Commands below are written `kindgi …` for brevity.
+
+An expert — a support lead, a claims reviewer, an editor — marks a run's
+answer wrong and says why. Your job is to turn those corrections into
+changes to the agent, each at the layer where it belongs, so the agent
+stops making the mistake and a person can see the mistake is gone.
+
+A correction is not always a prompt change. A store's "never refund
+shipping" belongs in the refund tool's code, where it's checked every time,
+not in instructions a model may or may not follow. Sorting each correction
+to the right layer is your call, not Kindgi's: Kindgi gives you the
+corrections and the tools to change each layer.
+
+## What stays with the person
+
+1. **Never loosen a rule — a loosening correction goes to the owner.** Some
+   corrections ask for a policy *looser* than the one in force: with a 14-day
+   return window, "should have refunded — 20 days is fine for us" wants the
+   window widened; others want a limit raised, a check dropped, or a tool to
+   stop asking for approval. This skill makes none of those — it hands the
+   correction to the owner, quoted, and lets them decide. A refusal the
+   *current* rule already allows is not a loosening: the agent applied the rule
+   wrong ("should have refunded — it was inside the 14 days"), nothing about the
+   policy changes, so you fix it like any other correction — in code with a
+   test, or in the instructions through Improve. The corrections you make carry
+   out a rule the agent got wrong, tighten a rule, or change how the agent talks
+   — never loosen the policy.
+2. **Making a version live is the person's.** You publish a new version and
+   *ask* for it with `kindgi agents promote … --reason`. When the scope's
+   release gate policy has `approvals`, the promotion waits for a second person
+   (`pending-approval`) — don't try to get around it.
+3. **The pulled runs hold real conversations.** A run you pull is a real
+   customer's. Keep it out of git. Write every pack test with invented data
+   — made-up order ids, amounts and names — never a customer's words or
+   details. Never paste a whole run, or any customer's data, into the pack,
+   a commit, or a message.
+
+## Step 1 — Pull the corrections
+
+The corrections are the agent's "no" judgments. Start from the version the
+agent is running now, so you don't re-fix something an earlier version already
+fixed:
+
+```sh
+kindgi agents live acme-store.refunds --project=<project-id>
+```
+
+`agents live` shows the version a run would use for the project (and
+`agents live-versions` lists every scope with a live version). List that
+version's "no" judgments — and, as you work through them, newer versions':
+
+```sh
+kindgi judgments list --agent=acme-store.refunds --agent-version=1.0.3 --verdict=no
+```
+
+- `--agent-version` (it needs `--agent`) scopes to one version — the live one,
+  to start. Older versions' corrections may already be fixed; without a version
+  you get every version's.
+- `--verdict=no` keeps only the corrections. (Leave it off to see what the
+  experts confirmed as right, too.)
+- `--class=<judge-class-id>` keeps only one judge class — use it to take
+  only the experts' corrections once the project names its experts.
+
+Kindgi doesn't hand out corrections: two people's coding agents can pull the
+same "no" judgments, so agree outside Kindgi who takes which before you start.
+
+Read each one in full for the reason the expert gave and the run it's on:
+
+```sh
+kindgi judgments show <judgment-id>
+kindgi runs get <run-id>
+kindgi runs journal <run-id>
+```
+
+`runs get` is the run's snapshot; `runs journal` is its durable record,
+step by step, where the agent's tool calls and their arguments are. Between
+the correction's reason and the run, you have what the agent did and what it
+should have done.
+
+An expert can also have said exactly what the run should have done (runtime
+0.2.0 or later): the judgment then has a `correction`, with `calls` (each
+`{ tool, args }`, with only the argument fields that matter) and `notCalled`
+(the tools it shouldn't have called). Take those as what the pack test
+asserts. It's the expert's: never record or change a correction yourself.
+Test cases built from the run check each new version against it.
+
+## Step 2 — Sort each correction to its layer
+
+| The expert wrote | Where it belongs | How you change it |
+|---|---|---|
+| "Never refund shipping", "final sale: no refund", "over 50 on a first order, ask a person" | a rule in **code** — the tool checks it every time; a cap sends the case to a tool that always asks | edit the tool and add a test (your language's `kindgi-authoring-tools`), then `kindgi deploy` |
+| "Our return window is 14 days, not 30" | a **setting** the owner can change | publish the settings block, derive a version that pins it (Step 4) |
+| "Always have a person approve a refund" | an **approval rule** — a tenant policy that makes a tool always ask; it keys on the tool, not its arguments | a person sets it (the owner or the approver); point them to it, don't change it in code |
+| "Store credit before cash", "too stiff", "say when the money arrives" | the agent's **instructions** | leave it to Improve, run on the test cases (`kindgi proposals improve`, the improve guide) |
+
+If a correction fits none of these, treat it as a code rule when it must
+hold every time, and as instructions when it's a matter of judgment.
+
+## Step 3 — Make the change, with a test per correction
+
+Make each change in the layer you sorted it to, and add **one pack test per
+correction** so the mistake can't come back:
+
+- **Code (a tool):** add the check in the tool, and a test that the corrected
+  case is now refused or handled right (the 20-day-old order is refused, the
+  final-sale item isn't refunded). Follow your pack's language:
+  `kindgi-authoring-tools` (TypeScript), `kindgi-python-authoring-tools`,
+  `kindgi-java-authoring-tools`, or `kindgi-scala-authoring-tools`. Run the
+  pack's tests the way that skill shows — `kindgi test` wraps `vitest` for a
+  Node pack; a Python, Java or Scala pack runs its own test runner.
+- **A setting:** decide the key, its limits and its default, and publish the
+  settings block (Step 4). Add a test that the tool reads the setting and
+  acts on it.
+- **Instructions for Improve:** you don't write the prompt — you make sure the
+  corrected cases are in the test cases, then let an Improve run try wordings
+  on them (`kindgi proposals improve`). It writes a *suggested* change only
+  when a wording does better on those cases, and a person
+  decides whether to take it; nothing is applied on its own.
+
+Write tests with invented data (Step 1, rule 3). A correction that belongs
+to the owner (a setting they'd rather own) or an approver (an approval rule)
+is theirs to make — say so, and give them the one command or the console
+page, don't do it for them.
+
+## Step 4 — Publish, and ask to make it live
+
+For a **setting** change, publish the block, then derive a new agent version
+that pins it — no code change:
+
+```sh
+kindgi blocks publish acme.store-policy \
+  --block-version=1.0.1 --project=<project-id> \
+  --settings=@store-policy.json --schema=@store-policy.schema.json
+kindgi agents derive acme-store.refunds \
+  --from=1.0.3 --setting=acme.store-policy=1.0.1 --label="return window 14 days"
+```
+
+- `blocks publish` takes `--block-version` (a semver, not `--version`) and a
+  required `--project`. `--settings` is the block's values; `--schema`
+  constrains them. (`--prompt` publishes a prompt block instead; the two are
+  mutually exclusive.)
+- `agents derive --setting=<block-id>=<version>` re-pins a block the version
+  *already* references to its new version (repeat `--setting`/`--prompt` for
+  several). It makes the first free patch after the agent's highest version and
+  prints it — read that version from its output rather than assuming one. If it
+  answers `reused`, an identical version already exists: use that, don't derive
+  again.
+
+For a **code** change, `kindgi deploy` publishes the new version with the
+changed tool.
+
+Deriving needs `publish` on the agent, `blocks publish` needs `write` on the
+project, and promoting needs `promote` — the permission that makes a version
+live, which an agent's admins hold.
+
+If the person keeps test cases built from the corrected runs, try the new
+version on them first:
+
+```sh
+kindgi eval-runs start <test-set-id> --project=<project-id> \
+  --agent=acme-store.refunds --agent-version=1.0.4 --wait
+```
+
+Where an expert said what the run should have done, its summary's
+`corrections` says how many of those the version now passes (`passed` of
+`checked`). No release gate policy checks it: quote it in the promote
+`--reason`.
+
+Either way, ask a person to make the new version live, naming the
+corrections it fixes. Check first what will happen, then ask:
+
+```sh
+kindgi agents promote acme-store.refunds 1.0.4 --project=<project-id> --check
+kindgi agents promote acme-store.refunds 1.0.4 --project=<project-id> \
+  --reason="Fixes 1 correction: our return window is 14 days"
+```
+
+- The scope is `--tenant` (every project), `--org=<org-id>`, or
+  `--project=<project-id> [--segment=<key:value>]…` (one project).
+- `--check` changes nothing and answers whether it *would* make it live,
+  needs an approval, or fails the release gate policy.
+- `--reason` is kept on the record — write what the corrections were, so the
+  approver reads the change in plain words.
+- The outcome is `promoted`, or `pending-approval` when the scope's release
+  gate policy has `approvals` and a second person must approve — the "a
+  second person checks it" step, working as it should. (Whoever asked can't
+  approve their own request, unless the policy sets `separateApprover: false`.)
+
+## A worked example: the return window
+
+An expert corrects a refund: "Shouldn't have refunded — delivered 20 days
+ago, our window is 14." You pull it (Step 1), and see the window is a store
+policy, not a one-off.
+
+- **If the agent already reads a `returnWindowDays` setting:** publish the
+  block with `returnWindowDays: 14` and derive a version that pins it
+  (Step 4). Tell the owner they can change this themselves in the console —
+  Edit as a new version, then Derive a version.
+- **If it doesn't read one yet:** this is a code change, in two parts. First
+  publish the settings block with the key — `returnWindowDays` in its schema
+  (0–365, whole days) and `14` in its values — because a deploy that references
+  a block with no published version is refused ("publish the block first").
+  Then, in code, make the refund tool read `returnWindowDays` and refuse an
+  order delivered more than that many days ago (offering a person), add the
+  block to what the agent references, and add a test: an order delivered 20
+  days ago is refused (`kindgi-authoring-tools`). `kindgi deploy` publishes the
+  version with the new reference. (`agents derive` only re-pins a block the
+  version already references, so it can't introduce this one — the deploy
+  does.) The schema and value live outside the pack and outside code review, so
+  show them to the person and name them in the `--reason`.
+
+Then ask to make it live: `kindgi agents promote … --reason="Fixes 1
+correction: our return window is 14 days"`. The refund limit — the most a
+refund can be without a person — is never raised here: the cap stays in the
+tool's code, and the large-refund tool still always asks.
+
+## References
+
+- Experts record corrections in the console, or with
+  `kindgi judgments add --run=<run-id> --item=<key> --no --reason=<text>`.
+- The guide for a person:
+  <https://docs.kindgi.com/v0.2/guides/evals/fix-what-experts-corrected/>
+- Letting Improve try wordings:
+  <https://docs.kindgi.com/v0.2/guides/evals/improve-an-agent/>
+- Changing a setting or a prompt by hand:
+  <https://docs.kindgi.com/v0.2/guides/evals/change-a-prompt-or-setting/>

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

@@ -18,7 +18,7 @@ description: >
 type: core
 library: "@kindgi/sdk"
 version: "0.4.4"
-sdk_version: "0.1.11-rc.0"
+sdk_version: "0.2.0-rc.1"
 pack_languages: [node, python, java, scala]
 ---
 

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

@@ -8,14 +8,16 @@ description: >
   project has no kindgi.config.ts yet and the user asks to "add
   Kindgi", "create a pack", "scaffold a Kindgi pack", "start a
   new pack", or when the user needs the mental model for what a Kindgi
-  pack IS. Once the pack is scaffolded and you are authoring code,
+  pack IS. Load it too when upgrading a self-hosted deployment, or
+  when asked for a migration script (there is none). Once the pack is
+  scaffolded and you are authoring code,
   switch to kindgi-authoring-tools / kindgi-authoring-agents /
   kindgi-authoring-guardrails / kindgi-authoring-flows for the specific
   primitive.
 type: core
 library: "@kindgi/sdk"
-version: "0.3.14"
-sdk_version: "0.1.11-rc.0"
+version: "0.3.16"
+sdk_version: "0.2.0-rc.1"
 pack_languages: [node]
 ---
 
@@ -97,7 +99,7 @@ Either way, `init` adds `@kindgi/sdk` and `@kindgi/cli` to the project's
 one. (`npx @kindgi/cli` is the scoped package; a bare `npx kindgi` would
 fetch an unrelated package.)
 
-Four templates:
+Five templates:
 
 - `--template=minimal` (default) — folder structure only, no example
   primitives. Right when you know what you want to build.
@@ -111,6 +113,10 @@ Four templates:
   Server signed in with OAuth: house-style fixes as drafts with every
   change approved, and a flow that checks each saved article before an
   agent sees it. Its README explains each choice.
+- `--template=follow-up` — an agent that writes a follow-up mail from
+  your notes and sends it from your own Gmail, each send approved first.
+  Its send tool comes from `@kindgi/connections`, under the pack's own
+  id. Its README explains each choice.
 
 ## Boot the dev harness
 
@@ -120,8 +126,9 @@ pnpm exec kindgi dev
 
 `kindgi dev` boots a local Kindgi runtime (starting the services it
 needs on first run), indexes the pack, registers every primitive, and
-re-registers on every save. The banner prints the API URL, the seeded
-bearer token, and (if the console is bundled) the `/console/` URL.
+re-registers on every save. The banner prints the API URL, the dev
+token's last four characters (the pack's `.kindgirc.json` has it in full,
+as `token`), and (if the console is bundled) the `/console/` URL.
 
 One `kindgi dev` per pack. When one is already running (the person's
 terminal, say), `kindgi dev` exits with code 3 and prints where it is
@@ -199,7 +206,9 @@ Most of the setup is automatable, but two require your knowledge:
 - **Real LLM provider credentials** — the built-in dev-echo provider
   returns canned responses (great for the loop test, useless for real
   agents). It is a fallback, so it steps aside once a real provider is
-  registered. Declare it in `kindgi.config.ts`
+  registered. Anthropic is the example below; `kindgi providers presets`
+  lists OpenAI, Gemini, Groq and OpenRouter too.
+  Declare one in `kindgi.config.ts`
   (`providers: [{ preset: 'anthropic' }]`, the key stored by the person with
   `kindgi secrets set ANTHROPIC_API_KEY --env=local --scope=tenant`) and `kindgi dev`
   registers it on every boot, in every worktree and after `--reset`. Commit
@@ -312,7 +321,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.1/guides/observability/cost-per-run/
+Docs: https://docs.kindgi.com/v0.2/guides/observability/cost-per-run/
 
 Show it in the app's own UI. **Never:**
 
@@ -323,7 +332,35 @@ 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.1/guides/runs/show-runs-in-your-app/
+own tables. Docs: https://docs.kindgi.com/v0.2/guides/runs/show-runs-in-your-app/
+
+## Upgrading a deployment
+
+There's no migration script, and none to write: a self-hosted runtime brings
+its database up to date when it starts, applying the migrations the database
+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:
+  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.
+
+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`).
 
 ## References
 

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

@@ -16,7 +16,7 @@ description: >
 type: core
 library: "kindgi-pack (Java)"
 version: "0.1.4"
-sdk_version: "0.1.11-rc.0"
+sdk_version: "0.2.0-rc.1"
 pack_languages: [java]
 sources:
   - sdks/java/kindgi-pack/README.md
@@ -152,10 +152,10 @@ public final class BriefWriter {
   `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
-  it. Leave room for real models: a turn with tool calls can take tens of
-  seconds.
+  8, at most 32); `maxCostUsd`; `maxWallMs` (default 120 000). Exceeding
+  the steps or the cost fails the turn (`budget-exceeded`); running out of
+  wall time aborts it. Leave room for real models: a turn with tool calls
+  can take tens of seconds.
 - **`output(Type.class)`:** a typed answer, with its schema derived from the
   record. The final answer must be JSON matching it. A wrong one goes back
   to the model with the problems (`maxRepairs`, default 1), and then the

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.11-rc.0"
+sdk_version: "0.2.0-rc.1"
 pack_languages: [java]
 sources:
   - sdks/java/kindgi-pack/README.md

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

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

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.3"
-sdk_version: "0.1.11-rc.0"
+version: "0.1.4"
+sdk_version: "0.2.0-rc.1"
 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.1/guides/tools/write-a-tool/#make-a-side-effect-happen-once
+  https://docs.kindgi.com/v0.2/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.
@@ -217,6 +217,34 @@ every variable it doesn't declare is dropped before your code loads
 (`kindgi dev` keeps them), so an undeclared one works locally and is unset
 once deployed. `KINDGI_*` names are Kindgi's own: a pack can't declare one.
 
+### Connections to other apps
+
+A tool that acts in another app as a person or as the company (sending mail, opening an issue) declares a **connection**, never a secret holding someone's token, and reads the call's short-lived token from `ctx.connections()` (runtime 0.2.0 or later):
+
+```java
+public static final Tool<Input, Output> TOOL = Tool.define("my-pack.send-mail")
+    // …description, version, input, output, effects…
+    .set("needsSpec", Map.of("connections", Map.of(
+        "mail", Map.of("app", "google", "permissions", List.of("gmail.send"), "as", "person"))))
+    .handler((input, ctx) -> {
+      ToolConnection mail = ctx.connections().get("mail");
+      HttpResponse<String> res = http.send(
+          HttpRequest.newBuilder(uri).header("authorization", "Bearer " + mail.accessToken()).build(),
+          HttpResponse.BodyHandlers.ofString());
+      if (res.statusCode() == 401) throw new ConnectionRejectedException("mail");
+      // …
+    });
+```
+
+- **Whose connection:** `"as", "person"` is the connection of the person the run acts as (whoever started it, or the owner of the schedule or webhook that did); `"as", "company"` is the company's. The runtime picks it from the run, never from the input or the model. A run that acts as nobody (a service account's, an event's) fails a `"person"` call with `connection-needs-a-person`.
+- **The token:** `accessToken()` is current for this call only. Never keep, print, log or return it; it never reaches the journal. `account().label()` says whose account it is (`ana@acme.com`).
+- **A 401 from the app:** `throw new ConnectionRejectedException("mail")`, with the connection's name (a second argument can say what the app answered, never the token), or your own exception with it as the cause. The runtime renews the token once and runs the call again; refused again, the call fails with `connection-rejected`.
+- **An HTTP tool** sends the token with no code: `.authorization(new HttpAuthSpec.Connection("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/
+
 ## Errors and output
 
 - Throw for a failure: the call fails with `handler-throw` and the
@@ -237,6 +265,10 @@ 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.
 
+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.
+
 `effect(kind, resource)` declares a side effect, such as
 `.effect("writes", "db:ledger")`. A dry run also stops at a tool with a
 `writes`, `deletes`, `spawns-run`, `emits-event` or `external-side-effect`
@@ -244,15 +276,65 @@ effect. `set(field, value)` sets the index entry's other fields: `needs`,
 `needsSpec`, `sandbox`, `limits`, `network`. They are recorded for policy and
 review, so declare what the tool really does.
 
-Java has no HTTP-tool form (TypeScript's `kind: 'http'`). A tool that calls
-an HTTP API is a handler with `java.net.http.HttpClient`, as above.
+A tool that calls an HTTP API can be a handler with `java.net.http.HttpClient`,
+as above, or the request declared as data with no handler — see **HTTP tool (as
+data)** below.
+
+## HTTP tool (as data)
+
+A tool that calls an HTTP API can be the request itself, declared as data,
+instead of a handler: `.http(spec)` in place of `.handler(...)`. The Kindgi
+runtime makes the request from the spec — the SDK only builds and validates it,
+so calling such a tool in this JVM throws. Build the spec with
+`HttpToolSpec.builder()` (package `com.kindgi.pack.http`):
+
+```java
+import com.kindgi.pack.Tool;
+import com.kindgi.pack.http.HttpAuthSpec;
+import com.kindgi.pack.http.HttpMethod;
+import com.kindgi.pack.http.HttpToolSpec;
+import com.kindgi.pack.http.ToolSecretRef;
+
+public record FetchOrder(String orderId) {}
+
+public record Order(String id, String status, double total) {}
+
+public static final Tool<FetchOrder, Order> TOOL =
+    Tool.define("shop.fetch-order")
+        .description("Fetch an order by id from the storefront API.")
+        .version("0.1.0")
+        .mutating(false)
+        .input(FetchOrder.class)
+        .output(Order.class)
+        .http(
+            HttpToolSpec.builder()
+                .method(HttpMethod.GET)
+                .urlTemplate("https://api.shop.example/orders/{orderId}")
+                .authorization(
+                    new HttpAuthSpec.Bearer(new ToolSecretRef("production", "shop-api-token")))
+                .successStatus(200, 299)
+                .build());
+```
+
+Every `{placeholder}` in the URL — in the path and query only, never in the
+host or port — is a field of the input, and so is one in a
+`HttpRequestBodySpec.Text` body; `.http(...)` throws if it isn't. Authorization
+is a `secretRef` (`HttpAuthSpec.Bearer` or `HttpAuthSpec.Header`), named for the
+runtime to resolve, never a literal credential. A request body is
+`HttpRequestBodySpec.JsonInput` (the input as JSON), `InputPassthrough` or
+`Text`. `timeoutMs` (default 30 seconds) covers the whole call, the response
+read included, and a run's cancel does too; a response body over 10 MiB,
+measured decompressed, fails the call — so point a tool at an endpoint that
+pages or filters, not one that returns everything. Scala declares the same tool
+the same way, with the same `HttpToolSpec`.
 
 ## 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:
+`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, a new mail, 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.
+- **A trigger can lift both, for its own runs only.** A project admin names the tool in a webhook trigger's, a schedule's or a mail trigger's `toolsAllowedUnattended` (`--allow-unattended=<tool-id>` on `kindgi webhooks`, `kindgi schedules` and `kindgi mail-triggers`). In that trigger's runs, the tool is then as in a run a person started. The tenant's approval rules still apply.
 
 In a run a person started (signed in, or with their own API key), the agent's rules decide, as for any tool. Left unset, it counts as `false`. Declare it on a tool that moves money or changes something people rely on:
 
@@ -262,17 +344,25 @@ 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.1/guides/approvals/ask-before-a-tool-runs/#when-no-person-started-the-run
+Docs: https://docs.kindgi.com/v0.2/guides/approvals/ask-before-a-tool-runs/#when-no-person-started-the-run
+
+## Results that are text from outside: `resultIsOutsideData`
+
+`resultIsOutsideData(true)` says the tool's results are text from outside that nobody checked, such as a mail someone sent or a page a search found. An agent reads each result of the tool as data, not instructions, in that turn and in every later turn's history. It changes what the model is told, not what the tool may do: pair it with approvals for anything an agent could do with what it read. Absent means `false`.
 
 ## Testing
 
 `Tool.call(input, ctx)` runs the handler with the input as given (no schema
 check). `ToolContext.forTest()` is a context with a test tenant and run and
-nothing else; `new ToolContext(…)` builds one with secrets:
+nothing else. `ToolContext.forTest(tool, env, secrets)` adds the env values
+the tool declares in `needsSpec`, decided as a run decides them (a schema
+`default` fills a name the test doesn't set, each value is checked, and a
+missing or invalid one throws `IllegalArgumentException`), and the secrets as
+given. `ToolContext.Builder` sets the rest:
 
 ```java
-ToolContext ctx = new ToolContext("t-test", "run-test", null, null, null,
-    Map.of(), Map.of("CITATOR_KEY", "test-key-of-twenty-chars"), Map.of(), Map.of(), new Cancellation());
+ToolContext ctx = ToolContext.forTest(new ToolContext.Builder()
+    .withSecrets(Map.of("CITATOR_KEY", "test-key-of-twenty-chars")));
 Greet.Output out = Greet.TOOL.call(new Greet.Input("Ada", "Hi"), ctx);
 ```
 
@@ -370,7 +460,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.1/guides/secrets/dev-sandbox/).
+    (https://docs.kindgi.com/v0.2/guides/secrets/dev-sandbox/).
 
 ## When the framework itself is the problem