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

package/dist/private-file.js

@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * A file that holds a key or token, such as `~/.kindgi/config.json`:
+ * owner-only from its first byte, whatever mode an older one had.
+ */
+import { randomBytes } from 'node:crypto';
+import { realpath, rename, stat, unlink, writeFile } from 'node:fs/promises';
+const PRIVATE_FILE_MODE = 0o600;
+/**
+ * Replace `path` with `text` in one step: a new `0600` file beside it, then
+ * a rename (`license/stores.ts`'s way). A reader that opened the old file
+ * keeps reading the old text, and a crash leaves the old file or the new
+ * one whole. A symlink at `path` stays: the file it points to is the one
+ * replaced, so the old text doesn't stay there at its old mode. A link
+ * that points nowhere becomes a file. Only a regular file is replaced: one
+ * that's a device, a pipe or a socket (a link to `/dev/null`) is refused,
+ * and left as it is.
+ *
+ * The umask can only take bits from `0600`, so the new file is never
+ * looser; a filesystem with no modes still gets the file. On Windows too,
+ * where the rename fails while another program has the file open, and the
+ * old file stays whole.
+ */
+export async function replacePrivateFile(path, text) {
+    let target = path;
+    try {
+        target = await realpath(path);
+    }
+    catch (cause) {
+        if (cause.code !== 'ENOENT')
+            throw cause;
+    }
+    // The rename would put a file in place of whatever is there.
+    const found = await stat(target).catch((cause) => {
+        if (cause.code === 'ENOENT')
+            return undefined;
+        throw cause;
+    });
+    if (found !== undefined && !found.isFile()) {
+        throw new Error(`${target} isn't a regular file, so it was left as it is.`);
+    }
+    const temp = `${target}.${randomBytes(6).toString('hex')}.kindgi-tmp`;
+    try {
+        await writeFile(temp, text, { encoding: 'utf8', mode: PRIVATE_FILE_MODE, flag: 'wx' });
+        await rename(temp, target);
+    }
+    catch (cause) {
+        await unlink(temp).catch(() => undefined);
+        throw cause;
+    }
+}
+/**
+ * `replacePrivateFile`, except on Windows: it has no such modes, and a
+ * rename there can fail while another program has the file open, so the
+ * write there is in place.
+ */
+export async function writePrivateFile(path, text) {
+    if (process.platform === 'win32') {
+        await writeFile(path, text, 'utf8');
+        return;
+    }
+    await replacePrivateFile(path, text);
+}
+//# sourceMappingURL=private-file.js.map

package/dist/private-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"private-file.js","sourceRoot":"","sources":["../src/private-file.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE7E,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAEhC;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAAY,EAAE,IAAY;IACjE,IAAI,MAAM,GAAG,IAAI,CAAC;IAClB,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,KAAK,CAAC;IACtE,CAAC;IACD,6DAA6D;IAC7D,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QACxD,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACzE,MAAM,KAAK,CAAC;IACd,CAAC,CAAC,CAAC;IACH,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CAAC,GAAG,MAAM,iDAAiD,CAAC,CAAC;IAC9E,CAAC;IACD,MAAM,IAAI,GAAG,GAAG,MAAM,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,aAAa,CAAC;IACtE,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACvF,MAAM,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC1C,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAY,EAAE,IAAY;IAC/D,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,MAAM,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QACpC,OAAO;IACT,CAAC;IACD,MAAM,kBAAkB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AACvC,CAAC"}

package/dist/progress-head.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `ctx.progress` when the CLI streams it (`write`): the first line goes
+ * after what `runCli` says first, the dev runtime's line (`hint`, said once a
+ * command reads its key) and the pin's. `unsaid` is what's left of those
+ * for the outcome, before `later` (the pin's line, when the outcome says
+ * it): all of it when nothing was streamed, else the hint when it came
+ * after the first line.
+ */
+export declare function progressAfterHead(write: ((text: string) => void) | undefined, hint: () => string, pin: () => string): {
+    readonly progress: ((text: string) => void) | undefined;
+    readonly unsaid: (later: string) => string;
+};
+//# sourceMappingURL=progress-head.d.ts.map

package/dist/progress-head.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-head.d.ts","sourceRoot":"","sources":["../src/progress-head.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,EAC3C,IAAI,EAAE,MAAM,MAAM,EAClB,GAAG,EAAE,MAAM,MAAM,GAChB;IACD,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IACxD,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;CAC5C,CAgBA"}

package/dist/progress-head.js

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * `ctx.progress` when the CLI streams it (`write`): the first line goes
+ * after what `runCli` says first, the dev runtime's line (`hint`, said once a
+ * command reads its key) and the pin's. `unsaid` is what's left of those
+ * for the outcome, before `later` (the pin's line, when the outcome says
+ * it): all of it when nothing was streamed, else the hint when it came
+ * after the first line.
+ */
+export function progressAfterHead(write, hint, pin) {
+    let opened;
+    const unsaid = (later) => {
+        if (opened === undefined)
+            return `${hint()}${later}`;
+        return opened.hint === '' ? hint() : '';
+    };
+    if (write === undefined)
+        return { progress: undefined, unsaid };
+    const progress = (text) => {
+        if (opened !== undefined) {
+            write(text);
+            return;
+        }
+        opened = { hint: hint() };
+        write(`${opened.hint}${pin()}${text}`);
+    };
+    return { progress, unsaid };
+}
+//# sourceMappingURL=progress-head.js.map

package/dist/progress-head.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-head.js","sourceRoot":"","sources":["../src/progress-head.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAA2C,EAC3C,IAAkB,EAClB,GAAiB;IAKjB,IAAI,MAA6C,CAAC;IAClD,MAAM,MAAM,GAAG,CAAC,KAAa,EAAU,EAAE;QACvC,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,GAAG,IAAI,EAAE,GAAG,KAAK,EAAE,CAAC;QACrD,OAAO,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1C,CAAC,CAAC;IACF,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;IAChE,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAQ,EAAE;QACtC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,KAAK,CAAC,IAAI,CAAC,CAAC;YACZ,OAAO;QACT,CAAC;QACD,MAAM,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC;QAC1B,KAAK,CAAC,GAAG,MAAM,CAAC,IAAI,GAAG,GAAG,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;IACzC,CAAC,CAAC;IACF,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AAC9B,CAAC"}

package/dist/progress-lines.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Where a command's lines go (`kindgi build`'s, `kindgi deploy`'s): each to
+ * `progress` as it comes when the CLI streams them, else kept for the
+ * result's stderr (`kept`). `quiet` leaves out each `line`, never a
+ * `problem`: an error or a warning is said either way.
+ */
+export interface ProgressLines {
+    readonly line: (s: string) => void;
+    /** A line that's an error or a warning: said under `quiet` too, as `kindgi dev` does. */
+    readonly problem: (s: string) => void;
+    readonly kept: () => string;
+}
+export declare function progressLines(progress: ((text: string) => void) | undefined, quiet: boolean): ProgressLines;
+/** A line a command says, and whether it's an error or a warning: said under `--quiet` too. */
+export interface SaidLine {
+    readonly text: string;
+    readonly problem: boolean;
+}
+/**
+ * `lines` as a result's stderr, each ending in a newline. Under `quiet`,
+ * only the errors and warnings, so a blank line that sets notes apart is
+ * a note too.
+ */
+export declare function renderLines(lines: readonly SaidLine[], quiet: boolean): string;
+/** A note: left out under `--quiet`. */
+export declare const note: (text: string) => SaidLine;
+/** An error or a warning: said under `--quiet` too. */
+export declare const warning: (text: string) => SaidLine;
+//# sourceMappingURL=progress-lines.d.ts.map

package/dist/progress-lines.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-lines.d.ts","sourceRoot":"","sources":["../src/progress-lines.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,yFAAyF;IACzF,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,EAC9C,KAAK,EAAE,OAAO,GACb,aAAa,CAaf;AAED,+FAA+F;AAC/F,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAK9E;AAED,wCAAwC;AACxC,eAAO,MAAM,IAAI,GAAI,MAAM,MAAM,KAAG,QAAsC,CAAC;AAE3E,uDAAuD;AACvD,eAAO,MAAM,OAAO,GAAI,MAAM,MAAM,KAAG,QAAqC,CAAC"}

package/dist/progress-lines.js

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export function progressLines(progress, quiet) {
+    const kept = [];
+    const say = (s) => {
+        if (progress === undefined)
+            kept.push(s);
+        else
+            progress(`${s}\n`);
+    };
+    return {
+        line: (s) => {
+            if (!quiet)
+                say(s);
+        },
+        problem: say,
+        kept: () => (kept.length === 0 ? '' : `${kept.join('\n')}\n`),
+    };
+}
+/**
+ * `lines` as a result's stderr, each ending in a newline. Under `quiet`,
+ * only the errors and warnings, so a blank line that sets notes apart is
+ * a note too.
+ */
+export function renderLines(lines, quiet) {
+    return lines
+        .filter((l) => !quiet || l.problem)
+        .map((l) => `${l.text}\n`)
+        .join('');
+}
+/** A note: left out under `--quiet`. */
+export const note = (text) => ({ text, problem: false });
+/** An error or a warning: said under `--quiet` too. */
+export const warning = (text) => ({ text, problem: true });
+//# sourceMappingURL=progress-lines.js.map

package/dist/progress-lines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-lines.js","sourceRoot":"","sources":["../src/progress-lines.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAejC,MAAM,UAAU,aAAa,CAC3B,QAA8C,EAC9C,KAAc;IAEd,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,MAAM,GAAG,GAAG,CAAC,CAAS,EAAQ,EAAE;QAC9B,IAAI,QAAQ,KAAK,SAAS;YAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;;YACpC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC,CAAC;IACF,OAAO;QACL,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE;YACV,IAAI,CAAC,KAAK;gBAAE,GAAG,CAAC,CAAC,CAAC,CAAC;QACrB,CAAC;QACD,OAAO,EAAE,GAAG;QACZ,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;KAC9D,CAAC;AACJ,CAAC;AAQD;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,KAA0B,EAAE,KAAc;IACpE,OAAO,KAAK;SACT,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,OAAO,CAAC;SAClC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC;SACzB,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC;AAED,wCAAwC;AACxC,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,IAAY,EAAY,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;AAE3E,uDAAuD;AACvD,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,IAAY,EAAY,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC"}

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

@@ -13,7 +13,7 @@ description: >
 type: core
 library: "@kindgi/sdk"
 version: "0.4.8"
-sdk_version: "0.1.11-rc.0"
+sdk_version: "0.2.0-rc.0"
 pack_languages: [node]
 sources:
   - packages/agents/src/types.ts
@@ -138,9 +138,9 @@ export default defined.value;
   `hitl.separateApprover` (`true`, or `{ overrides: { '<tool id>': true } }`)
   makes a tool's approval need someone other than whoever asked.
 - **`budget`** — per-turn ceiling. `maxSteps` caps model-call cycles
-  (default 8); `maxCostUsd` caps model spend; `maxWallMs` caps wall
-  time (default 120 000). Exceeding steps or cost fails the turn with
-  `budget-exceeded`; running out of wall time aborts it
+  (default 8, at most 32); `maxCostUsd` caps model spend; `maxWallMs`
+  caps wall time (default 120 000). Exceeding steps or cost fails the
+  turn with `budget-exceeded`; running out of wall time aborts it
   (`agent-turn-aborted`, reason `timeout`).
 
 - **`output`** — optional typed result: `{ schema, name?, maxRepairs? }`
@@ -189,7 +189,7 @@ export default defined.value;
   reliable tool calling. `{ instructionTypes: ['acme.policy'] }` turns a
   retrieved, verified fact of those types into an instruction
   ("Policies (verified)"). See
-  https://docs.kindgi.com/v0.1/guides/agents/give-an-agent-memory/.
+  https://docs.kindgi.com/v0.2/guides/agents/give-an-agent-memory/.
 
 ## What a turn receives
 
@@ -282,7 +282,7 @@ concerns, not author-time.
 
 - Type surface: `hover any @kindgi/sdk/define export` in your editor
   for full JSDoc.
-- API reference: https://docs.kindgi.com/v0.1/reference/typescript/sdk/kindgi/sdk/define/ (every `define*` spec, field by field).
+- API reference: https://docs.kindgi.com/v0.2/reference/typescript/sdk/kindgi/sdk/define/ (every `define*` spec, field by field).
 - Common patterns: the `sample` template's `agents/echo-agent`
   demonstrates the smallest tool-calling shape.
 

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

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

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

@@ -18,7 +18,7 @@ description: >
 type: core
 library: "@kindgi/sdk"
 version: "0.3.10"
-sdk_version: "0.1.11-rc.0"
+sdk_version: "0.2.0-rc.0"
 pack_languages: [node]
 sources:
   - packages/guardrails/src/types.ts
@@ -371,7 +371,7 @@ ready for the stricter enforcement.
 - Type surface: hover any `@kindgi/sdk/define` export for full JSDoc;
   `Guardrail`, `defineGuardrail` and the built-in checks are in
   `@kindgi/guardrails`.
-- API reference: https://docs.kindgi.com/v0.1/reference/typescript/sdk/kindgi/sdk/define/
+- API reference: https://docs.kindgi.com/v0.2/reference/typescript/sdk/kindgi/sdk/define/
 - Built-in check implementations: `packages/guardrails/src/checks.ts`.
 
 ## When the framework itself is the problem

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

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

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

@@ -27,7 +27,7 @@ description: >
 type: core
 library: "@kindgi/sdk"
 version: "0.9.17"
-sdk_version: "0.1.11-rc.0"
+sdk_version: "0.2.0-rc.0"
 pack_languages: [node, python, java, scala]
 sources:
   - packages/adapters/model-anthropic/src/provider.ts
@@ -151,7 +151,7 @@ kindgi deploy --hosted --env=prod
   presets` for `azure-openai`'s settings.
 
 The whole flow, from signing the CLI in to going live:
-https://docs.kindgi.com/v0.1/hosted/deploy-your-agent/#your-model-key-and-its-provider
+https://docs.kindgi.com/v0.2/hosted/deploy-your-agent/#your-model-key-and-its-provider
 
 ## Path A — Hosted, native Anthropic
 
@@ -705,7 +705,7 @@ moved to `isolated` that signs in as the runtime isn't used there: a turn
 that needs it fails with `422 capability-routing-failed`. Unregister it, and
 register it again with a key.
 
-Docs: https://docs.kindgi.com/v0.1/guides/models/#with-a-bedrock-api-key
+Docs: https://docs.kindgi.com/v0.2/guides/models/#with-a-bedrock-api-key
 
 ## How the router picks between multiple providers + models
 

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

@@ -13,7 +13,7 @@ description: >
 type: core
 library: "@kindgi/sdk"
 version: "0.4.13"
-sdk_version: "0.1.11-rc.0"
+sdk_version: "0.2.0-rc.0"
 pack_languages: [node]
 sources:
   - packages/tools/src/types.ts
@@ -124,7 +124,7 @@ The output side is the reverse: the advertised output schema requires every fiel
 ctx.log?.info('refund issued', { orderId, amountCents });
 ```
 
-Put values in `fields`, never in the message. Log ids, 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, not only by the person the data is about. Docs: https://docs.kindgi.com/v0.1/guides/tools/write-a-tool/#log-from-a-tool
+Put values in `fields`, never in the message. Log ids, 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, not only by the person the data is about. Docs: https://docs.kindgi.com/v0.2/guides/tools/write-a-tool/#log-from-a-tool
 
 ### Configuration and secrets
 
@@ -172,6 +172,38 @@ const defined = defineTool({
 
 Everything else comes from the process environment: `process.env.CITATOR_URL`. The pack service runs with the pack's env files in `kindgi dev` (less any secret stored with `kindgi secrets set`, which a tool declares and reads from `ctx.secrets`, and any model provider's key, which no tool gets), and with the container's environment in an image. Declare the names your code reads in `kindgi.config.ts`, `env: { required: ['CITATOR_URL'], optional: [...] }`: a deployment injects exactly those, a pack service missing a required one isn't ready and says which, and `kindgi dev` warns about it. In an image the pack service also drops every variable the pack doesn't declare before your code loads (`kindgi dev` keeps them), so an undeclared name works locally and is unset once deployed: declare every name the code reads. Values per environment go in `environments.<name>.env`, secrets only as references.
 
+### 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):
+
+```ts
+import { ConnectionRejectedError, defineTool } from '@kindgi/sdk/define';
+
+const defined = defineTool({
+  // …id, description, version, input, output, effects…
+  needsSpec: {
+    connections: { mail: { app: 'google', permissions: ['gmail.send'], as: 'person' } },
+  },
+  handler: async (input, ctx) => {
+    const mail = ctx.connections?.mail;
+    const res = await fetch(url, { headers: { authorization: `Bearer ${mail?.accessToken}` } });
+    if (res.status === 401) throw new ConnectionRejectedError('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 ConnectionRejectedError('mail')`, with the connection's name (a second argument can say what the app answered, never the token), or your own error with it as its `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: { kind: 'connection', connection: 'mail' }`.
+- **Ready-made tools:** for Gmail, Outlook, GitHub and LinkedIn, include one from `@kindgi/connections` instead of writing it. Each is a factory, and the pack names its id; there's no default, because a tool id is the tenant's, filed under the first project that publishes it. A tool folder's `index.ts` is one line, `export default gmailSend({ id: 'acme.gmail.send' })` (`@kindgi/connections/google/tools`); `githubIssuesList`, `githubLabelsList` and `githubIssuesAddLabels` come from `@kindgi/connections/github/tools`, `outlookSend`, `outlookMessagesList` and `outlookMessageGet` from `@kindgi/connections/microsoft/tools`, and `linkedinPost` from `@kindgi/connections/linkedin/tools`. Agents and approval settings use the pack's id.
+- **Your own calls to an app's API:** `appFetch(ctx, { entry, connection, toolId, url, method, headers, body })` from `@kindgi/connections/app-fetch` sends the connection's token as the only `Authorization`, paces calls by the entry's `rateLimits` (`toolId` is what its `costs` charge; 1 when not listed), tries a busy answer again, and throws a 401 as `ConnectionRejectedError`.
+- **Unattended runs:** in a run no person started, a tool that uses an `as: 'person'` connection waits for that person's yes, unless it's marked `mutating: false` (mark read-only tools so). The agent's `conversationPolicy.hitl` can't lift it; only a trigger's `toolsAllowedUnattended` can, which a project admin sets, as for `needsApprovalWhenUnattended` (below).
+- **In a unit test:** `ctx.connections` is optional in the type; build a context with `toolContextForTest({ connections: { mail: { accessToken: 'test', account: { id: '1', label: 'ana@acme.com' }, … } } })` (`@kindgi/sdk/define`).
+
+Docs: https://docs.kindgi.com/v0.2/guides/connections/use-a-connection/
+
 ## Declarative HTTP spec
 
 ```ts
@@ -231,6 +263,7 @@ The kinds are `reads`, `writes`, `deletes`, `network`, `spawns-run`, `emits-even
 
 - **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. Absent means `false`. Declare it on a tool that moves money or changes something people rely on:
 
@@ -240,9 +273,9 @@ 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
 
-A step can run more than once (resumed after an approval, retried after a failure, run again after a crash), so a tool that writes uses `ctx.idempotencyKey`: the same every time this call runs, different for every other call. Pass it to the system you write to (an `Idempotency-Key` header, a client reference, a unique column) or look for it there first, and a refund never goes out twice. Not `ctx.requestId`: a model's call id is only unique within one of its answers. The key is absent outside a run and from a runtime before 0.1.6. Docs: https://docs.kindgi.com/v0.1/guides/tools/write-a-tool/#make-a-side-effect-happen-once
+A step can run more than once (resumed after an approval, retried after a failure, run again after a crash), so a tool that writes uses `ctx.idempotencyKey`: the same every time this call runs, different for every other call. Pass it to the system you write to (an `Idempotency-Key` header, a client reference, a unique column) or look for it there first, and a refund never goes out twice. Not `ctx.requestId`: a model's call id is only unique within one of its answers. The key is absent outside a run and from a runtime before 0.1.6. Docs: https://docs.kindgi.com/v0.2/guides/tools/write-a-tool/#make-a-side-effect-happen-once
 
 ## Tool id convention
 
@@ -381,7 +414,7 @@ run start via `semver.maxSatisfying`. No implicit `:latest`.
     folder, `~/.aws`) or any `.env*` file, and gets `EPERM` there. A tool that
     needs a path names it in `kindgi.config.ts`: `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/).
 
 12. **Importing a Next.js module that has `import 'server-only'`.** Outside
     Next.js that line stops the module from loading, so the tool fails
@@ -436,7 +469,7 @@ run start via `semver.maxSatisfying`. No implicit `:latest`.
 - Type surface: `hover any @kindgi/sdk/define export` in your editor
   for full JSDoc — every field on `DefineToolSpec` / `ToolManifest`
   documents purpose, when to set it, and gotchas.
-- API reference: https://docs.kindgi.com/v0.1/reference/typescript/sdk/kindgi/sdk/define/ (every `define*` spec, field by field).
+- API reference: https://docs.kindgi.com/v0.2/reference/typescript/sdk/kindgi/sdk/define/ (every `define*` spec, field by field).
 - Common patterns: check the `sample` template (`kindgi init
   --template=sample`) for working examples of both authoring modes.