@kindgi/sdk 0.0.0-bootstrap.0 → 0.1.1

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

@@ -0,0 +1,302 @@
+---
+name: kindgi-authoring-flows
+description: >
+  Covers writing flows for a Kindgi pack with @kindgi/sdk: defineFlow,
+  tool and agent steps, edges and `when` conditions, branches that join
+  again, inputMapping from runInput / nodeOutputs, typed agent output in
+  a flow, the flow's declared output, loops (foreach / while) and fanout,
+  per-edge retry and timeout, and running a flow (kindgi runs start
+  --flow, in the background, as a dry run) and reading its journal. Load
+  this whenever you are authoring or editing code inside a pack's flows/
+  directory, defining a flow, or when the user asks to add, change or
+  debug one. Tools are covered by kindgi-authoring-tools, agents by
+  kindgi-authoring-agents.
+type: core
+library: "@kindgi/sdk"
+version: "0.1.2"
+sdk_version: "0.0.0"
+pack_languages: [node]
+sources:
+  - packages/flow/src/types.ts
+  - packages/flow/src/define.ts
+---
+
+# Authoring Kindgi flows
+
+> **Running `kindgi`:** the CLI is a devDependency of the project (`@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 …`. Commands below are written `kindgi …` for brevity.
+
+A **flow** is a versioned, durable graph of steps: tools (your code) and
+agents (a model's judgment), joined by edges that can carry conditions.
+It is **data**, not code: `defineFlow({...})` in `flows/<name>/index.ts`.
+The runtime runs it step by step, journals every step, and can resume a
+run that was interrupted. A run pins the flow version it started on.
+
+Use a flow when the order of the work is known: parse, then classify,
+then branch, then write. Use a single agent when the model should decide
+the order.
+
+## Ask before building
+
+- **What goes in, and what comes out?** The run input's shape and the
+  output the caller reads. They become `runInput.*` paths and `output`.
+- **Which steps are code, which are judgment?** Deterministic work
+  (parse, rank, look up, write) is a tool; judgment (classify, draft,
+  summarize) is an agent with a typed `output`.
+- **Where does it branch?** Every branch needs a condition, and the
+  steps after a branch must cope with the branch that didn't run.
+- **What does it change outside Kindgi?** A tool that only reads
+  declares `mutating: false`, and a dry run runs it. A tool that writes
+  doesn't (leaving it out counts as mutating), and a dry run stops there.
+
+## A flow
+
+```ts
+// flows/triage-ticket/index.ts
+import { defineFlow } from '@kindgi/sdk/define';
+
+const isBilling = {
+  op: 'eq',
+  left: { path: 'nodeOutputs.classify.output.category' },
+  right: { literal: 'billing' },
+} as const;
+
+const defined = defineFlow({
+  id: 'acme.triage-ticket',
+  version: '0.1.0',
+  name: 'Triage a support ticket',
+  description: 'Parses a ticket, classifies it, looks up billing when needed, drafts a reply.',
+  nodes: [
+    {
+      id: 'parse',
+      kind: 'tool',
+      ref: 'acme.parse-ticket',
+      inputMapping: { ticket: { path: 'runInput.ticket' } },
+    },
+    {
+      id: 'classify',
+      kind: 'agent',
+      ref: 'acme.ticket-classifier', // an agent with a typed `output`
+      inputMapping: { text: { path: 'nodeOutputs.parse.text' } },
+      config: { parameters: { product: 'acme-cloud' } },
+    },
+    {
+      id: 'billing',
+      kind: 'tool',
+      ref: 'acme.lookup-invoice',
+      inputMapping: { customerId: { path: 'runInput.ticket.customerId' } },
+    },
+    {
+      id: 'reply',
+      kind: 'tool',
+      ref: 'acme.draft-reply',
+      inputMapping: {
+        category: { path: 'nodeOutputs.classify.output.category' },
+        invoice: { path: 'nodeOutputs.billing.invoice' }, // absent when billing didn't run
+      },
+    },
+  ],
+  edges: [
+    { id: 'e0', from: '$start', to: 'parse' },
+    { id: 'e1', from: 'parse', to: 'classify' },
+    { id: 'e2', from: 'classify', to: 'billing', when: isBilling },
+    { id: 'e3', from: 'classify', to: 'reply', when: { op: 'not', child: isBilling } },
+    { id: 'e4', from: 'billing', to: 'reply' },
+    { id: 'e5', from: 'reply', to: '$end' },
+  ],
+  output: {
+    mapping: {
+      category: { path: 'nodeOutputs.classify.output.category' },
+      reply: { path: 'nodeOutputs.reply.text' },
+    },
+    schema: {
+      type: 'object',
+      properties: { category: { type: 'string' }, reply: { type: 'string' } },
+      required: ['category', 'reply'],
+    },
+  },
+});
+
+if (defined.kind === 'err') {
+  throw new Error(`acme.triage-ticket failed to compile: ${defined.error.message}`);
+}
+
+export default defined.value;
+```
+
+`defineFlow` checks the shape where it is written: ids, the version,
+edges between nodes that exist, `$start` / `$end`, no cycles, paths
+rooted where they may be. It doesn't check that `acme.parse-ticket`
+exists. That is checked when a run starts (see "Running a flow").
+
+## Nodes
+
+- **`kind: 'tool'`** runs the tool `ref` (its id). The tool's input is
+  what the node's `inputMapping` builds, else the output of the node's
+  single upstream node (the run input after `$start`). It is validated
+  against the tool's input schema, so a mismatch fails the step with
+  `input-validation-failed`. The node's output is the tool's return value.
+- **`kind: 'agent'`** runs one turn of the agent `ref` as a child run of
+  the flow run. The agent gets the node's input in two ways:
+  - as **structured input**: `{{ input.text }}` in its instructions;
+  - as its user message (the input as JSON).
+
+  `config.parameters` fills the agent's `parameters` (string, number or
+  boolean values). `config.version` pins an agent version; without it
+  the latest active version runs.
+
+  The node's output:
+  - `output` is the agent's typed answer (its `output` schema);
+  - `text` is the answer as text;
+  - `runId` and `conversationId` belong to the child run.
+
+  Read a field as `nodeOutputs.<node>.output.<field>`. An answer that
+  doesn't fit the agent's `output` schema, after its repairs, fails the
+  step with `output-schema-violation`.
+
+  An approval inside the agent's turn parks the flow until it's decided.
+- **`kind: 'loop'`** repeats a body: `loopKind: 'foreach'` once per
+  element of `iterateOver` (`concurrency` up to 32 in parallel), or
+  `loopKind: 'while'` until `exitCondition`.
+  - The body has its own nodes and edges, with `$loop-start` /
+    `$loop-end`; the element is the body's input.
+  - `maxIterations` and `outputSchema` are required.
+  - The loop's output is `finalOutput`, plus `outputs` with
+    `collectAllIterations: true`.
+  - Node ids must be unique across the whole flow, bodies included.
+- **`kind: 'fanout'`** runs several handlers on the same input at once,
+  each a `branch` with an `outputSchema`. `convergence` decides the
+  result:
+  - `'all-succeed'`: every branch must succeed;
+  - `'any-succeed'`: the first success wins;
+  - `'settle-all'`: wait for every branch and report each.
+- **`kind: 'subgraph'`** (a sub-flow) is part of the flow schema, but a
+  run refuses it today (`flow-unbound`). Inline the steps instead.
+
+## Edges and conditions
+
+An edge goes from a node (or `$start`) to a node (or `$end`). Without
+`when` it fires when its source completes; with `when` it fires only if
+the condition is true. Conditions are JSON:
+
+| Operator | Shape |
+|---|---|
+| `eq` `ne` `lt` `lte` `gt` `gte` | `{ op, left, right }` |
+| `in` `notIn` | `{ op, value, set }` |
+| `exists` `notExists` `truthy` `falsy` | `{ op, value }` |
+| `and` `or` | `{ op, children: [...] }` |
+| `not` | `{ op, child }` |
+
+Each operand is `{ literal: … }` or `{ path: … }`. When a path doesn't
+resolve, `eq`, `lt`, `lte`, `gt` and `gte` are false and `ne` is true. So
+for the "otherwise" branch, write `not` around the condition (as above),
+rather than a second comparison: it covers exactly what the first edge
+doesn't.
+
+**Joining branches.** A node with several incoming edges runs once every
+one of them is decided and at least one fired. In the example, `reply`
+runs after `billing` on the billing branch, and straight after `classify`
+otherwise. A node none of whose incoming edges fired is skipped, and so
+is everything only it leads to.
+
+**Edge policy** (`policy` on the edge into a node with a single incoming
+edge):
+- `retry: { maxAttempts, delayMs?, backoff?, maxDelayMs? }`: up to 10
+  attempts in all;
+- `timeoutMs`: a step that takes longer fails with `reason: 'timeout'`;
+- `concurrencyKey`: at most one such step at a time in the tenant;
+- `priority`: −100 to 100.
+
+A node with several incoming edges ignores them.
+
+## Inputs and the output
+
+`inputMapping` maps each key to a `{ literal }` or a `{ path }`. Paths are
+dot-separated (a number segment indexes an array: `items.0.sku`), rooted at:
+- `runInput.…`: the input the run was started with;
+- `nodeOutputs.<nodeId>.…`: a step's output. For an agent step, add
+  `.output.<field>` to read its typed answer;
+- `state.…`: values written by the runtime's own handlers. Pack tools
+  don't write it, so use `nodeOutputs`.
+
+A path that doesn't resolve leaves its key out. A step after a branch
+that didn't run gets no `invoice` key at all, rather than `invoice:
+undefined`. Make that key optional in the tool's input schema.
+
+`output` is what the run returns: a `mapping` resolved when the run
+finishes, checked against `schema` if you give one. A run whose output
+doesn't match fails. Without `output`, the run returns the output of the
+step that reached `$end`.
+
+## Running a flow
+
+From another terminal in the pack directory, while `kindgi dev` runs:
+
+```sh
+kindgi runs start --flow=acme.triage-ticket --input='{"ticket":{"customerId":"c-1","body":"Charged twice"}}'
+kindgi runs start --flow=acme.triage-ticket --input=@ticket.json --no-wait   # the run id now; it finishes in the background
+kindgi runs start --flow=acme.triage-ticket --input=@ticket.json --dry-run   # runs only read-only tools
+kindgi runs get <run-id>        # status, output, failureMessage
+kindgi runs journal <run-id>    # every step.started / step.completed / edge.evaluated
+kindgi runs stream <run-id>     # follow a running one
+kindgi runs cancel <run-id>
+```
+
+- **A refusal before the run exists:** `422 flow-unbound` names the
+  nodes a run can't bind: a tool or agent id the tenant doesn't have, or
+  a sub-flow. Fix the ids; nothing ran.
+- **A failed step fails the run**, and `failureMessage` says which step
+  and why. Retry it on its edge with `policy.retry` only if running the
+  step twice is safe.
+- **`--no-wait`** is how an application starts runs (`options: { wait:
+  false }` with `@kindgi/sdk/client`). It answers with the run id at once;
+  poll `GET /v1/runs/<id>` or follow the stream.
+- **`--dry-run`** runs a tool only if it's declared read-only:
+  `mutating: false`, and no `writes`, `deletes`, `spawns-run`,
+  `emits-event` or `external-side-effect` effect. The first other tool
+  stops the run with `dry-run-effectful-tool`, and everything before it
+  really ran. That's useful for checking the wiring without the writes.
+
+## Iterating on a flow
+
+Save the file and `kindgi dev` re-indexes; the next run uses the new
+definition, with no restart. A run already in flight keeps the version it
+started on. Bump `version` when callers' contract changes (the input or
+the output), not on every save.
+
+## Common mistakes
+
+1. **Building a flow without asking what goes in and comes out.** The
+   pack's `echo-flow` proves the runtime works. It isn't a template for
+   the user's flow.
+2. **A second comparison for "otherwise".** On a path that may be
+   missing, `eq` is false and `ne` is true, and `lt`/`gt` are both false,
+   so a hand-written opposite can miss a case or overlap. Use `not` around
+   the positive condition: it covers exactly what the first edge doesn't.
+3. **Reading an agent step's answer at `nodeOutputs.<step>.<field>`.**
+   The typed answer is under `.output`: `nodeOutputs.<step>.output.<field>`.
+   An agent without an `output` schema has only `text`.
+4. **A required input key fed by a branch that may not run.** The key is
+   omitted, the tool's input check fails, and so does the step. Make the
+   key optional in the tool's input schema.
+5. **`mutating: false` on a tool that writes.** A dry run runs it for
+   real unless its `effects` declare the write, and an agent's tool
+   gates (when on, with no rule for it) let it through unasked.
+6. **A read-only tool without `mutating: false`.** Leaving it out counts
+   as mutating: a dry run stops at the tool, and an agent's tool gates
+   ask before it. kindgi-authoring-tools has the details.
+7. **A sub-flow node.** A run refuses it (`flow-unbound`) until
+   sub-flows are supported.
+8. **Duplicate node ids inside a loop body.** Ids are unique across the
+   whole flow, bodies included.
+9. **Missing `Result` unwrap.** Check `defined.kind === 'err'` and throw,
+   so a broken flow fails when its module loads, not on the first run.
+
+## When the framework itself is the problem
+
+If the bug is in Kindgi or `@kindgi/sdk` (a step's output missing a
+field, a condition that evaluates wrongly, a misleading error) and not in
+the pack's code, load `kindgi-framework-feedback` and file it with
+`kindgi feedback write`.

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

@@ -0,0 +1,297 @@
+---
+name: kindgi-authoring-guardrails
+description: >
+  Covers writing guardrails (safety checks) for a Kindgi pack: the check
+  implementation via defineCheck from @kindgi/sdk/define, the guardrail
+  declaration a pack file default-exports (the indexer's shape), the
+  three kinds (zero-llm / llm-judge / external), action semantics
+  (halt / retry / escalate / log-only / compensate), severity levels,
+  scope selectors, config schemas via Zod or JSON Schema, validating a
+  declaration with defineGuardrail from @kindgi/guardrails, and how
+  guardrails reach agents. Load this whenever you are authoring or
+  editing code inside a pack's guardrails/ directory, defining a check,
+  or wiring a guardrail onto an agent. Authoring tools is covered by
+  kindgi-authoring-tools; authoring agents is covered by
+  kindgi-authoring-agents.
+type: core
+library: "@kindgi/sdk"
+version: "0.3.6"
+sdk_version: "0.0.0"
+pack_languages: [node]
+sources:
+  - packages/guardrails/src/types.ts
+  - packages/guardrails/src/define-check.ts
+  - packages/guardrails/src/define.ts
+  - packages/guardrails/src/judge.ts
+  - packages/guardrails/src/checks.ts
+  - packages/handler-runtime/src/kindgi-index.ts
+  - packages/handler-runtime/src/handler-runner.ts
+---
+
+# Authoring Kindgi guardrails
+
+> **Running `kindgi`:** the CLI is a devDependency of the project (`@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 …`. Commands below are written `kindgi …` for brevity.
+
+A **guardrail** is a safety rule an agent turn must satisfy. It combines
+a **check** (the function that inspects the turn's trace) with an
+**action** (what happens when the check fails). In a pack, a guardrail
+lives at `guardrails/<name>/index.ts`. For an agent turn, the runtime
+evaluates every guardrail the agent lists once, on the final response,
+before the response is stored.
+
+## Mental model: guardrail vs check
+
+- **Check** — the implementation. `defineCheck({ id, kind, configSchema?,
+  evaluate })` from `@kindgi/sdk/define` returns a registered check whose
+  `evaluate(config, trace, bindings)` resolves to `{ passed, reason? }`.
+  Zero-llm checks are pure over the trace.
+- **Guardrail** — the declaration: `id`, `kind`, the `check` it uses,
+  the check's `config`, and `action` / `severity` / `scope`. Its type is
+  `Guardrail` from `@kindgi/guardrails`. One check can back many
+  guardrails with different configs.
+- **Built-in checks** (`BUILT_IN_CHECK_IDS` in `@kindgi/guardrails`):
+  `must-cite`, `never-call-tool`, `max-tool-calls`, `output-matches`,
+  `tool-order`, `required-substring`, `forbidden-substring`. A guardrail
+  can name one of these instead of shipping its own check.
+
+`@kindgi/sdk` exports `defineCheck` but no helper for the guardrail
+itself: a pack file default-exports the declaration as a plain object.
+
+## A pack guardrail file (zero-llm)
+
+```ts
+// guardrails/no-fabricated-quotes/index.ts
+import { defineCheck } from '@kindgi/sdk/define';
+import { z } from 'zod';
+
+// The check implementation. The pack service calls `check.evaluate`.
+export const check = defineCheck({
+  id: 'acme.checks.no-fabricated-quotes',
+  kind: 'zero-llm',
+  configSchema: z.object({ minPrecedentCalls: z.number().int().min(0).optional() }),
+  evaluate: async (config, trace) => {
+    const needed = config.minPrecedentCalls ?? 1;
+    const precedentCalls = trace.toolCalls.filter((c) => c.toolName === 'acme.fetch-precedent');
+    if (precedentCalls.length < needed) {
+      return {
+        passed: false,
+        reason: `Only ${precedentCalls.length} precedent lookups (need ${needed}+).`,
+      };
+    }
+    return { passed: true };
+  },
+});
+
+// The guardrail declaration the indexer reads.
+export default {
+  id: 'acme.no-fabricated-quotes',
+  name: 'No fabricated quotations',
+  kind: 'zero-llm',
+  check,
+  action: { 'on-violation': 'halt' },
+  severity: 'critical',
+};
+```
+
+How the pack tooling reads this file:
+
+- The **indexer** (`packages/handler-runtime/src/kindgi-index.ts`)
+  recognises a guardrail by a default export with a `kind` and an
+  `action` object carrying `on-violation`. It records `id`, `name`,
+  `kind`, `action`, `severity`, `scope`, `sandbox` / `limits` /
+  `network`, and the check: its id (`check` may be the check id as a
+  string, or the check object) and its config schema (from the check's
+  `configZod`, `configSchema` or `configJsonSchema`, or a top-level
+  `configZod` / `configSchema`), and the declaration's `config` — what
+  the check runs with. It does not record `description`, `budget` or
+  `judgeCapabilities`.
+- The **pack service** loads the same module to run the check. It uses
+  the module's `evaluate` export, or the `default` / `check` export when
+  that is a function or has an `evaluate` method — here, the named
+  `check` export.
+
+## Validating a declaration in-process
+
+`defineGuardrail(spec, checks)` from `@kindgi/guardrails` validates a
+`Guardrail` against the wire schema and a check registry: the check id
+must be registered, the check's `kind` must match, and `config` must
+pass the check's config schema. It returns a `Result`; use it in tests
+or wherever guardrails are registered in-process.
+
+```ts
+import { createCheckRegistry, defineGuardrail } from '@kindgi/guardrails';
+import type { GuardrailId } from '@kindgi/sdk/types';
+
+import { check } from './index.js';
+
+const checks = createCheckRegistry([check]); // built-in checks are included
+const defined = defineGuardrail(
+  {
+    id: 'acme.no-fabricated-quotes' as GuardrailId,
+    kind: 'zero-llm',
+    check: check.id,
+    config: { minPrecedentCalls: 2 },
+    action: { 'on-violation': 'halt' },
+    severity: 'critical',
+  },
+  checks,
+);
+if (defined.kind === 'err') {
+  throw new Error(`acme.no-fabricated-quotes: ${defined.error.message}`);
+}
+```
+
+Registering a guardrail through the API (`POST /v1/guardrails`, or
+`client.guardrails.author(spec, { projectId })` in `@kindgi/sdk/client`)
+stores the declaration only; the check it names must already be
+available to the runtime that evaluates it.
+
+## Field-by-field
+
+- **`id`** — `<pack-id>.<guardrail-name>` (kebab-case, dot-namespaced).
+  Name the ASSERTION as a positive rule (e.g. `no-fabricated-quotes`,
+  `response-not-empty`, `must-cite-source`).
+- **`kind`**:
+  - `'zero-llm'` — pure function over the trace. Fast, deterministic,
+    free. **The default choice for most safety rules.**
+  - `'llm-judge'` — a model scores the turn against a rubric. Costs
+    money; requires `judgeCapabilities`. See below.
+  - `'external'` — evaluated outside the engine. The built-in
+    `external` strategy returns an `invalid-guardrail` error; a caller
+    that wants external evaluation registers its own strategy.
+- **`check`** — the id of a registered check (built-in, or one built
+  with `defineCheck`). In a pack file it may also be the check object.
+- **`config`** — the check's parameters, validated against the check's
+  `configSchema` by `defineGuardrail`. In a pack, the declaration's
+  `config` goes into the index and the check runs with it; without one
+  it runs with `{}`. A declaration a pack file default-exports isn't run
+  through `defineGuardrail`, so nothing validates its `config`: keep it
+  valid against the schema yourself. `evaluate` receives the config as
+  declared —
+  schema defaults are not filled in — so handle absent optional fields.
+- **`action.on-violation`** — `'halt'`, `'retry'` (with
+  `retry.maxAttempts`, 1–10), `'escalate'` (with `escalateTo`),
+  `'log-only'`, `'compensate'` (with `compensateWith`, a tool id). In an
+  agent turn, a failed `halt` guardrail fails the turn with
+  `guardrail-violation` and the response is not stored; failures with
+  any other action are reported in `AgentTurnResult.violations` and the
+  turn completes. The action handlers in `@kindgi/guardrails`
+  (`retryHandler`, `escalateHandler`, `compensateHandler`, …) record the
+  intent for callers that act on it. In 0.1 the runtime acts only on
+  `halt`: `retry`, `escalate` and `compensate` are recorded on the
+  violation, with no second attempt, escalation or compensating call.
+- **`severity`** — `'info'` / `'warn'` / `'error'` (the default) /
+  `'critical'`. Orthogonal to `action`: logs and dashboards group by
+  severity; execution follows the action. A `log-only` guardrail can
+  still be `'critical'`.
+- **`scope`** — when the guardrail applies. `{ when: 'always' }` fires
+  everywhere; `{ when: 'ci-only' }` blocks CI but not runtime;
+  `{ when: 'runtime-only' }` enforces at runtime but not CI. `agents`,
+  `flows` and `tenants` lists narrow it further.
+- **`budget`** — `{ maxCostUsd?, maxLatencyMs? }`, relevant to
+  `llm-judge`. Declarative: the runtime does not enforce it.
+- **`judgeCapabilities`** — for `llm-judge`: the capability
+  declaration used to route the judge model.
+
+## LLM-judge guardrail (costs money)
+
+An `llm-judge` guardrail does not run custom check code: the engine's
+`llm-judge` strategy sends the turn's trace and the rubric in `config`
+(`{ rubric, responseFormat?, threshold?, temperature? }`) to a model
+routed through `judgeCapabilities`, and parses a PASS/FAIL or a score.
+
+```ts
+import type { Guardrail } from '@kindgi/guardrails';
+import type { GuardrailId } from '@kindgi/sdk/types';
+
+export const toneProfessional: Guardrail = {
+  id: 'acme.tone-professional' as GuardrailId,
+  kind: 'llm-judge',
+  // Required by the `Guardrail` type; the llm-judge strategy judges
+  // with `config` and does not call this check.
+  check: 'acme.checks.tone-professional',
+  config: {
+    rubric: 'The response is professional in tone and contains no slang.',
+    responseFormat: 'pass-fail',
+  },
+  judgeCapabilities: { needs: [{ feature: 'structured-output' }] },
+  action: { 'on-violation': 'log-only' },
+  severity: 'warn',
+  budget: { maxCostUsd: 0.01, maxLatencyMs: 5000 }, // declarative, not enforced
+};
+```
+
+The judge is resolved from the provider registry passed in the
+evaluation bindings (or a pinned `judgeProvider`), under the tenant
+policy in those bindings when one is passed. Checks that run in a pack are called with empty
+`bindings` — no provider registry — so a pack check cannot call a model
+itself; use `kind: 'llm-judge'` for model-based rules.
+
+## Wiring the guardrail onto an agent
+
+Agents reference guardrails by id:
+
+```ts
+// agents/brief-writer/index.ts
+guardrails: ['acme.no-fabricated-quotes'],
+```
+
+At the start of each turn, the runtime resolves these ids against the
+guardrails available to the run. An id that isn't registered fails the
+turn before the model is called (`Error [invalid-request]: Agent "…"
+references guardrails not in the registry: <id>`), so register the
+guardrail before an agent references it.
+
+## Changing a guardrail
+
+Guardrails have no `version` field; the id is the stable identifier.
+Changing a guardrail's check, config, severity or action changes
+behavior for every agent that references it. When you tighten a rule
+(raise severity from `warn` to `error`, switch the action from
+`log-only` to `halt`), check whether the agents that reference it are
+ready for the stricter enforcement.
+
+## Common mistakes
+
+1. **Confusing guardrail and check.** The id in `agent.guardrails: [...]`
+   is the GUARDRAIL id, not the check id. The agent binds to
+   guardrails; guardrails reference checks.
+
+2. **A check whose `evaluate` always returns `passed: true`.** If you
+   are stubbing the check, give the guardrail `action: { 'on-violation':
+   'log-only' }` so it is honest about not being enforced.
+
+3. **Calling a model from a pack check.** Pack checks receive empty
+   `bindings`; there is no provider registry to route through. Declare
+   an `llm-judge` guardrail with a rubric instead.
+
+4. **Not declaring `configSchema`.** Without it, `config` is
+   `Record<string, unknown>` — no validation, no editor completion,
+   silent typos. Prefer Zod for TS-side inference on
+   `evaluate(config, ...)`.
+
+5. **Ignoring the `Result` from `defineGuardrail`.** It returns
+   `Result<Guardrail, …>`; check `kind` and throw at load time.
+   `defineCheck` itself throws when its `configSchema` can't be
+   compiled.
+
+## References
+
+- 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/
+- Built-in check implementations: `packages/guardrails/src/checks.ts`.
+
+## When the framework itself is the problem
+
+If you diagnose that the bug lives in Kindgi/`@kindgi/sdk` itself
+(guardrail runtime dropping context fields, check-sandbox dispatch
+regression, misleading error message, CLI friction) — not in the
+pack's own code — load the `kindgi-framework-feedback` skill and file
+a structured report with `kindgi feedback write`. That diagnostic is
+high-signal input the maintainers can act on; don't let it disappear
+into the transcript.