@kindgi/cli 0.1.10 → 0.2.0-rc.0

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.10"
+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.10"
+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.10"
+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.10"
+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.10"
+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.10"
+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.
 

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.0"
+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.10"
+sdk_version: "0.2.0-rc.0"
 pack_languages: [node, python, java, scala]
 ---