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

package/dist/sdk-skills/kindgi-authoring-tools/imperative-handler.md

@@ -0,0 +1,65 @@
+# Imperative handler
+
+```ts
+// tools/verify-citation/index.ts
+import { defineTool } from '@kindgi/sdk/define';
+import type { ToolId } from '@kindgi/sdk/types';
+import { z } from 'zod';
+
+const Input = z.object({
+  citation: z.string().min(1),
+  jurisdiction: z.enum(['US', 'UK', 'EU']),
+});
+
+const Output = z.object({
+  found: z.boolean(),
+  canonicalCite: z.string().optional(),
+});
+
+const defined = defineTool({
+  id: 'acme.verify-citation' as ToolId,
+  description:
+    'Verify a legal citation against the jurisdictional citator. Returns whether the citation resolves and the canonical form.',
+  version: '0.1.0',
+  input: Input,
+  output: Output,
+  effects: [],
+  mutating: false,
+  handler: async (input, ctx) => {
+    // ctx.tenantId, ctx.abortSignal, ctx.secrets (what needsSpec declares) available;
+    // in a run, ctx.projectId and ctx.orgId (set from the run, never from the input)
+    // Return type MUST match Output schema (validated at invoke time)
+    return { found: true, canonicalCite: '...' };
+  },
+});
+
+if (defined.kind === 'err') {
+  throw new Error(`acme.verify-citation failed to compile: ${defined.error.message}`);
+}
+
+export default defined.value;
+```
+
+A handler must return a Promise; one with nothing to `await` can return `Promise.resolve({ … })` instead of being `async`, which keeps lint rules like `require-await` quiet.
+
+## What the handler receives
+
+The handler gets the **parsed** input, typed `z.infer` of `input` (Zod's output type):
+
+- **Defaults.** A `.default()` field is optional to the caller, the model included. The tool's advertised schema doesn't list it as required, and the handler always gets a value.
+- **Transforms and refinements.** `.transform()` results and `.refine()` checks apply before the handler runs. A failed refinement comes back as `input-validation-failed`.
+- **Extra keys.** A plain `z.object` accepts them and strips them. Use `z.strictObject` to reject them.
+- **JSON-Schema-authored tools** get each property's `default` filled in the same way.
+- **Unions of scalars** (`z.union([z.string(), z.number()])`, `type: ['string', 'number']` on the wire) compile and validate. A schema Kindgi's strict schema check still refuses (an open tuple, an unknown keyword) says so at `defineTool`; for a field that may hold any JSON value, `z.json()` compiles.
+
+The output side is the reverse: the advertised output schema requires every field, defaulted ones included. Return them all.
+
+## Logging from the handler
+
+`ctx.log` is a logger bound to the call: its records carry the run's ids, the tool's id and the trace id. It has `info`, `warn`, `error`, `debug` and `trace`, each `(message, fields?)`. The pack service sets it; a context your own code builds (a test's) may not, so write `ctx.log?.`:
+
+```ts
+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.3/guides/tools/write-a-tool/#log-from-a-tool

package/dist/sdk-skills/kindgi-authoring-tools/iterating-and-testing.md

@@ -0,0 +1,45 @@
+# Iterating on a tool, testing it, and shared code
+
+## Iterating on a tool
+
+Edit the source file (`tools/<tool>/index.ts`), save. The next
+`kindgi runs start` sees the change — new input/output schema, new
+description, new handler behavior. No version bump, no restart, no
+re-registration ceremony. Source is truth in dev.
+
+The `version` field is a **semver contract for humans** — it declares
+what callers can rely on. Bump it because the *contract with
+downstream callers* changed (removed a field, tightened a type,
+narrowed enum values), not because you saved the file. If you're
+iterating in dev and the shape isn't finalized, leave `version`
+alone.
+
+**When version matters:** `kindgi deploy` publishes to a durable
+production registry that enforces the immutable `(id, version)`
+contract — a re-publish of the same version with different bytes
+gets rejected. That's when semver discipline kicks in. The deploy
+tooling surfaces the check; you don't have to think about it while
+authoring.
+
+**Downstream callers still pin ranges.** An agent's `tools: [{id,
+version: '^0.1.0'}]` picks the highest active version matching the
+range at run start. Compatible tool updates (patch, minor) reach the
+agent without editing agent source; breaking updates (major) require
+the agent-author to opt in.
+
+## Testing a tool
+
+Put a tool's tests beside it, `tools/<tool>/index.test.ts`. Discovery skips `*.test.*` and `*.spec.*` files (`.ts`, `.js`, `.mjs`, `.cjs`), so the indexer never loads a test as a primitive: don't move tests elsewhere to keep them out. `invokeTool(tool, input, ctx)` from `@kindgi/sdk/define` calls the tool the way Kindgi does, schemas included, and returns a `Result`. `toolContextForTest()` builds its `ctx` (tenant `tenant-test`, run `run-test`, an abort signal) and takes what to change: `env`, `secrets`, `projectId`.
+
+```ts
+import { invokeTool, toolContextForTest } from '@kindgi/sdk/define';
+
+const result = await invokeTool(lookupOrder, { orderId: 'ord_1001' }, toolContextForTest());
+// a tool with env values: invokeToolForTest(tool, input, { env: { STORE_URL: '…' } })
+```
+
+`kindgi test` runs the pack's tests with vitest (`vitest run`; `--watch` keeps watching). In an app Kindgi was added to, `kindgi init` wrote the vitest config (`vitest.config.mts`, or `.ts` in a `"type": "module"` app): it runs `kindgi/**/*.test.ts`, and its `resolve.alias` copies `tsconfig.json`'s `paths`, which vitest doesn't read. A test that can't resolve an alias the app's code uses (`@/…`) means the two differ: update the config's alias, not the import.
+
+## Shared code
+
+Code several tools share (schemas, a client, helpers) goes outside `tools/`, for example in `lib/` beside it. Discovery loads every `.ts`, `.js` and `.mjs` file under `tools/` (tests aside) as a primitive, so a helper there fails the index. Don't put it in the app's own source either: import the app's functions from where they are (unless their module imports `server-only`: see mistake 12 in `common-mistakes.md`; for a CommonJS package's default import, see mistake 13 in `common-mistakes.md`), and keep what's Kindgi's in the pack's folder.

package/dist/sdk-skills/kindgi-authoring-tools/secrets-and-connections.md

@@ -0,0 +1,79 @@
+# Configuration, secrets and connections
+
+## Configuration and secrets
+
+A secret that belongs to the tenant — an API key a customer gives you — is declared, and read from `ctx.secrets`:
+
+```ts
+const defined = defineTool({
+  // …id, description, version, input, output, effects…
+  needsSpec: { secrets: { CITATOR_KEY: { type: 'string', minLength: 20 } } },
+  handler: async (input, ctx) => {
+    const key = ctx.secrets?.CITATOR_KEY;
+    // …
+  },
+});
+```
+
+The runtime resolves every declared secret on every call, for the call's tenant, in its env (`KINDGI_ENV`; in `kindgi dev`, `local`: the pack's `.env` and `.env.local`, then Kindgi's own `.kindgi/secrets.env`, where `kindgi secrets set` writes). It checks each value against its schema, and fails the call, naming the secret, when one is missing or doesn't match. A declared secret is required, so in a runtime call `ctx.secrets` holds it; it's optional in the type because a unit test builds its own context and passes `secrets: { CITATOR_KEY: '…' }`. **An optional secret** has a schema that names `null` (`{ type: ['string', 'null'] }`; an unconstrained `{}` stays required): one never stored, or empty, is left out of `ctx.secrets`, and the call goes on, its log line naming it. One revoked, or gone at its provider though mapped, still fails the call. Optional secrets need runtime 0.1.6 or later; an older runtime requires them.
+
+A value that differs per tenant, org or project but isn't secret (a base URL, a region, an account id) is an **env value**: declared in `needsSpec.env`, read from `ctx.env`:
+
+```ts
+const defined = defineTool({
+  // …id, description, version, input, output, effects…
+  needsSpec: {
+    env: {
+      ORDERS_BASE_URL: { type: 'string', pattern: '^https://' },
+      ORDERS_REGION: { type: 'string', enum: ['eu', 'us'], default: 'eu' },
+    },
+  },
+  handler: async ({ orderId }, ctx) => ({
+    url: `${ctx.env?.ORDERS_BASE_URL}/${ctx.env?.ORDERS_REGION}/orders/${orderId}`,
+  }),
+});
+```
+
+- **Which value a call gets:** its project's, else its org's, else the tenant's, in the runtime's env; a schema `default` makes a name optional. The values a call used are recorded with it, so a retry or a resume sees the same ones.
+- **Setting them:** `kindgi env set ORDERS_REGION us --scope=project:<project-id> --env=local` (or `--scope=tenant`, for every project). Changing a value that's already set takes `--force`.
+- **A declared value nobody set** stops the call before the tool runs. For a tool `acme-orders.needs-account` that declares `ACME_ACCOUNT_ID`, the message reads:
+  ```text
+  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 (`needsSpec.secrets`), never an env value.
+- **Schemas compile strictly:** each `needsSpec` schema must compile as the runtime compiles it (an unknown keyword is refused), and an env `default` is a string; otherwise `defineTool` returns `invalid-tool-definition`, and a deploy fails with `deployment-validation-failed`.
+- **In a unit test:** call it with `invokeToolForTest(tool, input, { env: { … } })` (`@kindgi/sdk/define`). It decides the values as a run does: a name you don't set takes its schema's `default`, each value is checked, and the handler sees the declared names only. A missing or invalid one is `precondition-failed` (`env-value-missing`, `env-value-invalid`). Plain `invokeTool` passes `ctx.env` as given (the runtime decides a pack tool's env itself).
+
+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`, with `gmailMessagesList`, `gmailMessageGet` and `gmailReply`); `githubIssuesList`, `githubLabelsList` and `githubIssuesAddLabels` come from `@kindgi/connections/github/tools`, `outlookSend`, `outlookMessagesList`, `outlookMessageGet` and `outlookReply` from `@kindgi/connections/microsoft/tools`, and `linkedinPost` from `@kindgi/connections/linkedin/tools`. Agents and approval settings use the pack's id. A mail tool acts in the person's own mailbox; `as: 'company'` makes it use the company's. `as` is part of what the tool declares, so an id you've published keeps its `as`: give a company mailbox its own tool 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, reads included: `mutating: false` doesn't lift it. 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 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:** `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.3/guides/connections/use-a-connection/

package/dist/sdk-skills/kindgi-authoring-tools/tool-flags.md

@@ -0,0 +1,45 @@
+# Read-only tools, a person's yes, and outside data
+
+## Read-only tools: `mutating`
+
+`mutating: false` declares that the tool changes nothing outside Kindgi; it only reads. Leaving `mutating` out counts as mutating, the same as `true`. It decides four things, in both authoring modes:
+
+- **Dry runs.** `kindgi runs start --dry-run` runs a tool only if it's `mutating: false` and its `effects` declare no `writes`, `deletes`, `spawns-run`, `emits-event` or `external-side-effect`. The first other tool stops the run with `dry-run-effectful-tool`.
+- **Approval gates.** When an agent turns tool gates on (`conversationPolicy.hitl.tools`) and sets neither an override for the tool nor a `default`, a `mutating: false` tool runs straight through, and any other tool asks for approval on its first use.
+- **Running together.** When a model step asks for several calls at once, an agent runs calls to read-only tools (`mutating: false`, no changing effect) that come one after another at the same time, up to 8 of them, and a call to any other tool on its own, in the order the model asked. A call that may wait, for another system's answer or for the person who started the run to connect an app, runs on its own too. A call a `before-tool` guardrail judges doesn't start until the calls before it have finished, so its check sees them as calls that ran; the read-only calls after it can run alongside it. Once a call needs an approval, the step's calls that haven't started run one at a time. The results reach the conversation and the model in the model's order either way. An agent with `parallelToolCalls: false` runs every call on its own.
+- **Runs a new mail started.** A call of a tool that isn't `mutating: false` waits for a person's yes, unless the mail trigger's `toolsAllowedUnattended` lists it.
+
+So declare `mutating: false` on every tool that only reads, and never on one that writes.
+
+A tool that writes also says what it writes, in `effects`, beside `mutating: true`:
+
+```ts
+  effects: [{ kind: 'writes', resource: 'acme:refunds' }],
+  mutating: true,
+```
+
+The kinds are `reads`, `writes`, `deletes`, `network`, `spawns-run`, `emits-event`, `external-side-effect` and `sensitive-data-egress` (`EFFECT_KINDS` in `@kindgi/tools`); `defineTool` refuses any other. `resource` is free text naming what the tool touches. A read-only tool keeps `effects: []`.
+
+## 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, 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. Absent means `false`. Declare it on a tool that moves money or changes something people rely on:
+
+```ts
+  effects: [{ kind: 'writes', resource: 'acme:refunds' }],
+  mutating: true,
+  needsApprovalWhenUnattended: true,
+```
+
+Docs: https://docs.kindgi.com/v0.3/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.3/guides/tools/write-a-tool/#make-a-side-effect-happen-once
+
+## 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`.

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

@@ -14,8 +14,8 @@ description: >
   not the agent.
 type: core
 library: "@kindgi/sdk"
-version: "0.1.0"
-sdk_version: "0.2.0-rc.1"
+version: "0.2.0"
+sdk_version: "0.3.0-rc.0"
 pack_languages: [node, python, java, scala]
 sources:
   - packages/cli/src/commands/judgments.ts
@@ -71,54 +71,18 @@ corrections and the tools to change each layer.
    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 loop
 
-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:
+1. **Pull the corrections**: the live version's "no" judgments, each read
+   in full with its run. [pull-corrections.md](pull-corrections.md)
+2. **Sort each correction to its layer**: the table below.
+3. **Make the change, with a test per correction.**
+   [make-the-change.md](make-the-change.md)
+4. **Publish, and ask a person to make it live**, with the guides to point
+   people to. [publish-and-promote.md](publish-and-promote.md)
 
-```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.
+One correction taken through all four steps:
+[worked-example.md](worked-example.md).
 
 ## Step 2 — Sort each correction to its layer
 
@@ -127,136 +91,7 @@ Test cases built from the run check each new version against 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) |
+| "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 in `publish-and-promote.md`) |
 
 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-fix-corrections/make-the-change.md

@@ -0,0 +1,25 @@
+# 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, `publish-and-promote.md`). 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 (rule 3 under "What stays with the person" in `SKILL.md`). 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.

package/dist/sdk-skills/kindgi-fix-corrections/publish-and-promote.md

@@ -0,0 +1,76 @@
+# 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`.)
+- `--check` and the request exit 3 when the answer is no or the request
+  waits for an approval. Read the printed outcome: exit 3 isn't an error.
+
+## 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.3/guides/evals/fix-what-experts-corrected/>
+- Letting Improve try wordings:
+  <https://docs.kindgi.com/v0.3/guides/evals/improve-an-agent/>
+- Changing a setting or a prompt by hand:
+  <https://docs.kindgi.com/v0.3/guides/evals/change-a-prompt-or-setting/>

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

@@ -0,0 +1,48 @@
+# 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.

package/dist/sdk-skills/kindgi-fix-corrections/worked-example.md

@@ -0,0 +1,27 @@
+# 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, `pull-corrections.md`), 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, `publish-and-promote.md`). 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.