@kindgi/cli 0.1.10 → 0.2.0-rc.0

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.10"
+version: "0.3.16"
+sdk_version: "0.2.0-rc.0"
 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,32 @@ 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. 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, or one on Azure Container Apps:** the
+  "Operate it" section of its page,
+  https://docs.kindgi.com/v0.2/deploy/self-hosted/cloud-run/#operate-it or
+  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.10"
+sdk_version: "0.2.0-rc.0"
 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.10"
+sdk_version: "0.2.0-rc.0"
 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.10"
+sdk_version: "0.2.0-rc.0"
 pack_languages: [java]
 sources:
   - sdks/java/kindgi-pack/README.md

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

@@ -15,7 +15,7 @@ description: >
 type: core
 library: "kindgi-pack (Java)"
 version: "0.1.3"
-sdk_version: "0.1.10"
+sdk_version: "0.2.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.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, unless it's marked `.mutating(false)` (mark read-only tools so). 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 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
@@ -244,8 +272,57 @@ 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`
 
@@ -253,6 +330,7 @@ an HTTP API is a handler with `java.net.http.HttpClient`, as above.
 
 - **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 or a schedule's `toolsAllowedUnattended` (`--allow-unattended=<tool-id>` on `kindgi webhooks` and `kindgi schedules`). 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 +340,21 @@ 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
 
 ## 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 +452,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
 

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

@@ -10,14 +10,15 @@ description: >
   `kindgi.config.json` yet and the user asks to "add Kindgi", "make an
   agent", "set up a pack", or when you are orienting in a Java pack
   (`kindgi.config.json` with `"language": "java"`) for the first time.
-  Authoring tools, guardrails, agents and flows is covered by
-  kindgi-java-authoring-tools, kindgi-java-authoring-guardrails,
-  kindgi-java-authoring-agents and kindgi-java-authoring-flows; models by
-  kindgi-authoring-providers.
+  Load it too when upgrading a self-hosted deployment, or when asked for
+  a migration script (there is none). Authoring tools, guardrails, agents
+  and flows is covered by kindgi-java-authoring-tools,
+  kindgi-java-authoring-guardrails, kindgi-java-authoring-agents and
+  kindgi-java-authoring-flows; models by kindgi-authoring-providers.
 type: core
 library: "kindgi-pack (Java)"
-version: "0.1.3"
-sdk_version: "0.1.10"
+version: "0.1.4"
+sdk_version: "0.2.0-rc.0"
 pack_languages: [java]
 sources:
   - sdks/java/kindgi-pack/README.md
@@ -64,7 +65,7 @@ You need a JDK 17 or later (`JAVA_HOME`). Maven comes with the pack
 (`./mvnw`).
 
 ```sh
-npx --yes @kindgi/cli@0.1 init my-pack --template=java   # or: uvx --from "kindgi-cli>=0.1,<0.2" kindgi init …
+npx --yes @kindgi/cli@0.2 init my-pack --template=java   # or: uvx --from "kindgi-cli>=0.2,<0.3" kindgi init …
 cd my-pack
 ./mvnw test        # the template's tests: the tools, called directly
 ./kindgiw dev      # boots Kindgi locally and runs this pack, recompiling on save
@@ -88,7 +89,7 @@ reported as `file:line:col`, and the last good code keeps serving.
 In the app's directory (where its `pom.xml` is):
 
 ```sh
-npx --yes @kindgi/cli@0.1 init   # --pack-id=<id> if the app's artifactId doesn't make one
+npx --yes @kindgi/cli@0.2 init   # --pack-id=<id> if the app's artifactId doesn't make one
 ./kindgiw dev
 ```
 
@@ -235,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.1/guides/runs/show-runs-in-your-app/
+Docs: https://docs.kindgi.com/v0.2/guides/runs/show-runs-in-your-app/
 
 ## Build an image
 
@@ -254,6 +255,34 @@ deployed pack service missing a required one isn't ready, and its `/readyz`
 names it; one the pack doesn't declare is dropped before the code loads
 (`kindgi dev` keeps it).
 
+## 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. 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, or one on Azure Container Apps:** the
+  "Operate it" section of its page,
+  https://docs.kindgi.com/v0.2/deploy/self-hosted/cloud-run/#operate-it or
+  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`).
+
+Not `./kindgiw upgrade`: that moves the pack's own pins (the CLI's and
+kindgi-pack's), not a deployment's runtime.
+
 ## Two things need the human
 
 - **The pack id and version** in `kindgi.config.json`. The id prefixes every

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

@@ -16,7 +16,7 @@ description: >
 type: core
 library: "kindgi (Python)"
 version: "0.1.7"
-sdk_version: "0.1.10"
+sdk_version: "0.2.0-rc.0"
 pack_languages: [python]
 sources:
   - sdks/python/src/kindgi/pack/define.py
@@ -142,8 +142,8 @@ brief_writer = Agent(
   loosen them. `"separateApprover"` in `hitl` (`True`, or
   `{"overrides": {"<tool id>": True}}`) makes a tool's approval need
   someone other than whoever asked.
-- **`budget`** — per turn: `maxSteps` (model calls, default 8),
-  `maxCostUsd`, `maxWallMs` (default 120 000). Steps or cost exceeded
+- **`budget`** — per turn: `maxSteps` (model calls, default 8, at most
+  32), `maxCostUsd`, `maxWallMs` (default 120 000). Steps or cost exceeded
   fails the turn (`budget-exceeded`); out of wall time aborts it. Leave
   room for real models: a turn with tool calls can take tens of seconds.
 - **`output`** — a typed answer: a pydantic model class (or any type
@@ -182,7 +182,7 @@ 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.1/guides/agents/give-an-agent-memory/.
+  instruction. See https://docs.kindgi.com/v0.2/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

@@ -17,7 +17,7 @@ description: >
 type: core
 library: "kindgi (Python)"
 version: "0.1.2"
-sdk_version: "0.1.10"
+sdk_version: "0.2.0-rc.0"
 pack_languages: [python]
 sources:
   - sdks/python/src/kindgi/pack/define.py

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

@@ -16,7 +16,7 @@ description: >
 type: core
 library: "kindgi (Python)"
 version: "0.1.5"
-sdk_version: "0.1.10"
+sdk_version: "0.2.0-rc.0"
 pack_languages: [python]
 sources:
   - sdks/python/src/kindgi/pack/define.py

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

@@ -15,7 +15,7 @@ description: >
 type: core
 library: "kindgi (Python)"
 version: "0.1.5"
-sdk_version: "0.1.10"
+sdk_version: "0.2.0-rc.0"
 pack_languages: [python]
 sources:
   - sdks/python/src/kindgi/pack/define.py
@@ -95,8 +95,10 @@ def verify_citation(citation: Citation, ctx: ToolContext) -> Verdict:
   field's path (a bad output as `output-validation-failed`); the agent's
   `tool_errors` policy decides whether the model gets to fix the call.
 - **Problems in the declaration** (a missing docstring, an
-  unannotated parameter, a non-object input) raise `DefinitionError`
-  where the tool is declared; the indexer reports it with the file.
+  unannotated parameter, a non-object input, or an input or output
+  schema the runtime's compile refuses, such as one with a keyword it
+  doesn't know) raise `DefinitionError` where the tool is declared; the
+  indexer reports it with the file.
 
 ## `ToolContext`
 
@@ -112,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.1/guides/tools/write-a-tool/#make-a-side-effect-happen-once
+  Docs: https://docs.kindgi.com/v0.2/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
@@ -136,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.1/guides/tools/write-a-tool/#log-from-a-tool
+  https://docs.kindgi.com/v0.2/guides/tools/write-a-tool/#log-from-a-tool
 
 ## Configuration and secrets
 
@@ -189,7 +191,7 @@ def find_order(lookup: Lookup, ctx: ToolContext) -> Found:
   precondition-failed: Tool "acme-orders.needs-account" was not run: env-value-missing: tool "acme-orders.needs-account" needs env value "ACME_ACCOUNT_ID" in env "local", and none is set for project e889c1f5-eae7-45dc-8669-5bd029a5d85c, its org, or the tenant. Set it: kindgi env set ACME_ACCOUNT_ID <value> --scope=project:e889c1f5-eae7-45dc-8669-5bd029a5d85c --env=local (or --scope=tenant, for every project)
   ```
 - **Not secret:** env values are recorded with each run that uses them and shown in its journal. A credential is a secret, never an env value.
-- **In a test:** `ToolContext.for_test(env={"ORDERS_BASE_URL": "…"})`.
+- **In a test:** `ToolContext.for_test(tool=find_order, env={"ORDERS_BASE_URL": "…"})` decides them as a run does: a schema `default` fills a name the test doesn't set, each value is checked, and a missing or invalid one raises `ValueError`.
 
 Everything else comes from the process environment: `os.environ["CITATOR_URL"]`.
 The pack service runs with the pack's environment — in `kindgi dev`
@@ -207,6 +209,38 @@ the pack service drops every other variable before your code loads
 unset once deployed. `KINDGI_*` names are Kindgi's own settings: 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):
+
+```python
+import httpx
+
+from kindgi import ConnectionRejected, ToolContext, tool
+
+
+@tool(
+    id="my-pack.send-mail",
+    needs_spec={"connections": {"mail": {"app": "google", "permissions": ["gmail.send"], "as": "person"}}},
+)
+def send_mail(message: Message, ctx: ToolContext) -> Sent:
+    """Sends a message from the person's mailbox."""
+    mail = ctx.connections["mail"]
+    res = httpx.get(url, headers={"authorization": f"Bearer {mail.access_token}"})
+    if res.status_code == 401:
+        raise ConnectionRejected("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:** `access_token` 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:** `raise ConnectionRejected("mail")`, with the connection's name (a second argument can say what the app answered, never the token), or raise your own error `from` it. 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={"kind": "connection", "connection": "mail"}`.
+- **Unattended runs:** in a run no person started, a tool that uses a `"person"` connection waits for that person's yes, unless it's marked `mutating=False` (mark read-only tools so). 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 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/
+
 ## Errors and output
 
 - Raise an exception for a failure: the call fails with
@@ -248,6 +282,7 @@ policy and review; declare what the tool really does.
 
 - **An agent's call waits** for a person's yes, whatever the agent's `conversation_policy` says in `hitl["tools"]`. 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 or a schedule's `toolsAllowedUnattended` (`--allow-unattended=<tool-id>` on `kindgi webhooks` and `kindgi schedules`). 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 out, it counts as `False`. Declare it on a tool that moves money or changes something people rely on:
 
@@ -262,7 +297,7 @@ def refund(request: RefundRequest) -> Refunded:
     """Refunds an order."""
 ```
 
-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
 
 ## HTTP tools — one request, no code
 
@@ -394,7 +429,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.1/guides/secrets/dev-sandbox/).
+    (https://docs.kindgi.com/v0.2/guides/secrets/dev-sandbox/).
 
 ## When the framework itself is the problem