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

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

@@ -12,8 +12,8 @@ description: >
   kindgi-authoring-guardrails.
 type: core
 library: "@kindgi/sdk"
-version: "0.4.8"
-sdk_version: "0.2.0-rc.1"
+version: "0.4.10"
+sdk_version: "0.3.0-rc.0"
 pack_languages: [node]
 sources:
   - packages/agents/src/types.ts
@@ -111,10 +111,12 @@ export default defined.value;
 - **`guardrails`** — array of guardrail `id` strings. Resolved at turn
   start against the guardrails bound for the run (the tenant's
   registered guardrails). If a guardrail id isn't registered, the turn
-  fails with `unresolved-guardrail`. Guardrails are evaluated once per
-  turn, on the final response before it is stored — a blocking
-  (`halt`) violation fails the turn and the response is never written
-  to the conversation.
+  fails with `unresolved-guardrail`. Guardrails check the final
+  response before it is stored — a blocking (`halt`) violation fails
+  the turn and the response is never written to the conversation; a
+  `retry` one sends the response back to the model for a new one, up
+  to `retry.maxAttempts` answers in all (default 2); then the turn
+  fails with `guardrail-violation`.
 - **`parameters`** — typed inputs the caller supplies at invoke time.
   UI builds a "configure agent" form from these; runtime validates
   each required parameter is provided.
@@ -162,6 +164,16 @@ export default defined.value;
   retries the turn fails as before, with `toolRetries` on the error. A
   tenant's `tool-errors` policy can lower these (fewer retries, fewer
   kinds), never raise them.
+- **`parallelToolCalls`** — optional, default on. When a model step asks for
+  several calls at once, calls to read-only tools (`mutating: false`, no
+  changing effect) that come one after another run at the same time, up to 8
+  of them, and a call to any other tool runs 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. 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. `false` runs every call on its own, for read-only tools that
+  mustn't overlap (a rate-limited API, say).
 - **`retrieval`** — what the agent reads from memory before each turn.
   Empty = no memory. Each intent is
   `{ types: ['acme.preference'], scope, mode?, limit? }`, with `scope`
@@ -188,8 +200,8 @@ export default defined.value;
   person's approval. Remembering is a tool call, so use a model with
   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.2/guides/agents/give-an-agent-memory/.
+  ("Policies (verified)"). "Give an agent memory" has the rest:
+  https://docs.kindgi.com/v0.3/guides/agents/give-an-agent-memory/
 
 ## What a turn receives
 
@@ -282,7 +294,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.2/reference/typescript/sdk/kindgi/sdk/define/ (every `define*` spec, field by field).
+- API reference: https://docs.kindgi.com/v0.3/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

@@ -13,8 +13,8 @@ description: >
   kindgi-authoring-agents.
 type: core
 library: "@kindgi/sdk"
-version: "0.1.3"
-sdk_version: "0.2.0-rc.1"
+version: "0.1.4"
+sdk_version: "0.3.0-rc.0"
 pack_languages: [node]
 sources:
   - packages/flow/src/types.ts
@@ -32,7 +32,9 @@ 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.
+run that was interrupted. A run keeps the flow version it started on.
+A run that names no version takes the version pinned for its project
+(or its org, or the tenant), else the newest version the project reaches.
 
 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

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

@@ -3,22 +3,23 @@ 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), actions, severity
-  levels, scope selectors, config schemas via Zod or JSON Schema,
-  validating a declaration with defineGuardrail from @kindgi/guardrails,
-  and how guardrails reach agents. In 0.1 only the halt action acts
-  (retry / escalate / compensate are only recorded: nothing runs the
-  turn again), and a check sees only the current turn: its user message
-  and tool results, not earlier turns'. 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
+  declaration a pack file default-exports (the indexer's shape), the three
+  kinds (zero-llm / llm-judge / external), actions, severity levels, scope
+  selectors, config schemas via Zod or JSON Schema, validating a declaration
+  with validateGuardrail from @kindgi/guardrails, and how guardrails reach
+  agents. A guardrail judges the final answer, or with `at` a tool call
+  (before or after it) or each model reply that asks for tool calls. halt
+  fails the turn; retry sends the answer or reply back, refuses the call or
+  withholds its result; escalate / compensate are final-answer only and
+  only recorded. A check sees only the current turn. 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 by
   kindgi-authoring-agents.
 type: core
 library: "@kindgi/sdk"
-version: "0.3.10"
-sdk_version: "0.2.0-rc.1"
+version: "0.4.0"
+sdk_version: "0.3.0-rc.0"
 pack_languages: [node]
 sources:
   - packages/guardrails/src/types.ts
@@ -41,29 +42,61 @@ 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.
+evaluates every guardrail the agent lists where its `at` says: once, on
+the final response before it's stored (`'final-answer'`, the default), or
+in the agent loop, on each tool call before it runs (`'before-tool'`),
+on each call's result before the model sees it (`'after-tool'`), or on
+each model reply that asks for calls, before any of them runs
+(`'model-step'`).
 
 ## What a guardrail can do in 0.1
 
-Read this before you plan a guardrail. Three limits decide what can be
-built:
-
-- **Only `halt` acts.** A failed `halt` guardrail fails the turn with
-  `guardrail-violation`, and the response is not stored. `retry`,
+Read this before you plan a guardrail. These decide what can be built:
+
+- **`halt` and `retry` act.** At the final answer, a failed `halt`
+  guardrail fails the turn with `guardrail-violation`, and the response is
+  not stored. A failed `retry` guardrail sends the answer back to the
+  model, with the check's reason in a user message, for a new one; the
+  failed answer isn't stored. When it has failed `retry.maxAttempts`
+  answers (the first one included; 2 when left out), the turn fails with
+  `guardrail-violation` and `details.attempts`. Each new answer is a model
+  call that the agent's `budget.maxSteps` counts. With a `retry` guardrail
+  at the final answer, the `halt` and `retry` guardrails there judge each
+  answer, a judge's calls included, which `budget.maxCostUsd` doesn't
+  count; the others judge only the answer that's sent. A new answer can
+  call tools again, side-effecting ones included, with approvals as usual.
   `escalate` and `compensate` are recorded on the turn's violations, as
-  `log-only` is, and the turn completes: nothing runs the turn again,
-  escalates or calls a compensating tool. So "block the reply and make the
-  agent try again" can't be a guardrail. Use `halt`: the error names the
-  guardrail and the check's reason, and the message is sent again (by the
-  person, or by your app when it gets `guardrail-violation`).
+  `log-only` is, and the turn completes: nothing escalates or calls a
+  compensating tool. So "block the reply and make the agent try again" is
+  a `retry` guardrail.
+- **They act in the loop too.** At `'before-tool'` (after the call's
+  access check, before any approval is asked), `halt` fails the turn and
+  `retry` refuses the call: it doesn't run, and the model gets the reason
+  as its result. At `'after-tool'`, `retry` withholds the result: the
+  reason is stored as the call's result in its place, so neither the model
+  nor a later turn's history sees it; a replay's recorded result is judged
+  as a live one is. At `'model-step'`, `retry` sends the reply back: none
+  of its calls runs, nothing of it is stored, and the model writes a new
+  reply. `retry.maxAttempts` counts replies across the turn: each reply
+  the guardrail sent back, or one with a call it refused or a result it
+  withheld, counts once, so two calls of one reply that it refuses are one
+  attempt. When they run out, or the turn has no steps left, the turn
+  fails with `attempts`, the replies there were. A tool's own result never
+  counts as one. A `log-only` failure joins the turn's `violations`. A
+  dry run skips the model call, so no guardrail runs at these points in
+  one.
+  `escalate` and `compensate` are refused away from the final answer
+  (by `kindgi build`, `deployment-validation-failed` on deploy,
+  `400 validation-failed` on register). A failure names `details.point` and, at a tool point,
+  `details.callId`. A resumed turn reuses each point's recorded outcome:
+  no judge is asked or billed twice.
 - **A check sees one turn.** The trace holds the current turn only: its
   user message (`trace.userInput`), its tool calls and their results
   (`trace.toolCalls`, `trace.toolResults`) and its response
-  (`trace.output`). Earlier turns' messages, tool results and responses
-  aren't in it. A check that every figure in the response comes from a
-  tool result or the user's message therefore blocks a response that
-  repeats a figure seen only in an earlier turn.
+  (`trace.output`, at the final answer only). Earlier turns' messages,
+  tool results and responses aren't in it. A check that every figure in
+  the response comes from a tool result or the user's message therefore
+  blocks a response that repeats a figure seen only in an earlier turn.
 - **A check's in-memory state doesn't last.** The check runs in the pack
   service's process, so anything it keeps at module level (say, a record
   per `trace.conversationId`) is lost when that process is replaced: under
@@ -81,14 +114,20 @@ message, so a response that repeats them is still blocked.
 
 ## 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.
+- **Check** — the implementation. `defineCheck({ id, kind, points?,
+  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. `points`
+  names where it can run, from `'before-tool'`, `'after-tool'`,
+  `'model-step'` and `'final-answer'`; left out, it's `['final-answer']`.
+  An empty list, an unknown point or one named twice throws
+  `invalid-check-definition`. A check that reads `trace.output` runs at
+  the final answer; one that reads `trace.call`, `trace.result` or
+  `trace.step` names the points where they're set.
 - **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.
+  the check's `config`, `at`, and `action` / `severity` / `scope`. Its type is `Guardrail` from `@kindgi/guardrails`. One check
+  can back many guardrails with different configs, each at one of the
+  check's points.
 - **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
@@ -142,16 +181,27 @@ 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
+  `kind`, `action`, `severity`, `scope`, `at`, `sees`, `budget`, `sandbox` /
+  `limits` / `network`, and the check: its id (`check` may be the check
+  id as a string, or the check object), its points (`checkPoints`, for a
+  check the module ships) 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
+  the check runs with. It does not record `description` or
   `judgeCapabilities`. It checks `config` (none counts as `{}`) against
   the config schema: a config that doesn't fit, or a required field with
   no default left out, is a file error naming where, and `kindgi build`
-  refuses the pack.
+  refuses the pack. It also refuses an `at` it doesn't know, a malformed
+  `scope.tools` or `points`, what a point can't do in the deploy's paths
+  and words (`guardrail <id>: /action/on-violation: "escalate" is
+  recorded at the final answer only, not at "before-tool"`, and
+  `/scope/tools` for `scope.tools` away from the tool points), and an
+  `at` the module's check doesn't run at (`guardrail <id> runs at
+  'before-tool', which isn't one of its check's points (final-answer)`).
+  A built-in named as a string isn't checked there: deploy refuses one at
+  a point it doesn't run at (at `/at`, `deployment-validation-failed`),
+  and registering answers `422 guardrail-config-invalid`; registering
+  answers `400 validation-failed` for what a point can't do.
 - 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
@@ -160,6 +210,58 @@ How the pack tooling reads this file:
   declares no config gets them all), and a config that doesn't fit
   refused, naming where.
 
+## A guardrail in the agent loop
+
+```ts
+// guardrails/refund-limit/index.ts
+import { defineCheck } from '@kindgi/sdk/define';
+import { z } from 'zod';
+
+export const check = defineCheck({
+  id: 'acme.checks.refund-limit',
+  kind: 'zero-llm',
+  points: ['before-tool'],
+  configSchema: z.object({ maxAmount: z.number().positive().default(100) }),
+  evaluate: async (config, trace) => {
+    // At 'before-tool', trace.call is the call it judges; trace.toolCalls
+    // holds only the calls that ran, never this one.
+    const amount = trace.call?.arguments.amount;
+    if (typeof amount === 'number' && amount > config.maxAmount) {
+      return { passed: false, reason: `The refund is ${amount}; the limit is ${config.maxAmount}.` };
+    }
+    return { passed: true };
+  },
+});
+
+export default {
+  id: 'acme.refund-limit',
+  kind: 'zero-llm',
+  check,
+  at: 'before-tool',
+  scope: { tools: ['acme.orders.refund'] },
+  action: { 'on-violation': 'retry' },
+  severity: 'error',
+};
+```
+
+What the trace holds at each point:
+
+- `trace.at` — the point. Absent at the final answer.
+- `trace.call` — at `'before-tool'` and `'after-tool'`:
+  `{ callId, toolId, toolName, toolVersion?, arguments }`.
+- `trace.result` — at `'after-tool'`: `{ output }`, or
+  `{ error: { code?, message } }` when the call threw.
+- `trace.step` — at `'model-step'`: `{ text, toolCalls }`; `text` is
+  empty when the reply only asks for calls.
+
+Away from the final answer there's no `trace.output`, and `toolCalls` /
+`toolResults` hold only the calls that ran. At the final answer the
+trace holds every call the model asked for. A failed `halt` at a loop
+point reads
+`Turn blocked by guardrail 'acme.refund-limit' before calling acme.orders.refund: …`
+(`after <tool> ran`, `on a model reply`; out of attempts,
+`…, after 2 replies: …`).
+
 ## Using a built-in check
 
 Name the built-in as the guardrail's `check`, give its `config`, and ship
@@ -191,6 +293,15 @@ Each built-in's `config` (tool lists hold tool ids, as in
 | `required-substring` | the answer is empty, or lacks any of `patterns` | `patterns: string[]`, one or more non-empty (plain text), `caseSensitive?: boolean` (false) |
 | `forbidden-substring` | the answer contains any of `patterns` | `patterns: string[]`, one or more non-empty (plain text), `caseSensitive?: boolean` (false) |
 
+Where each runs (the guardrail's `at`): `must-cite` and
+`required-substring` at `'final-answer'` only. `never-call-tool`,
+`max-tool-calls` and `tool-order` at `'before-tool'` too, judging that
+call against the turn's earlier calls, so a call they fail never runs.
+`output-matches` and `forbidden-substring` at `'model-step'` and
+`'after-tool'` too: they read the reply's text, or the call's result (a
+string as it is, anything else as JSON, an error's message). A reply that
+only asks for calls has no text and passes `output-matches`.
+
 A config the check doesn't take is refused: a required setting left out,
 the wrong type, a setting the check doesn't know, or a regex that doesn't
 compile. Registering it answers `422 guardrail-config-invalid` (each
@@ -202,20 +313,22 @@ turn. Each built-in's JSON Schema is its registered check's
 
 ## Validating a declaration in-process
 
-`defineGuardrail(spec, checks)` from `@kindgi/guardrails` validates a
+`validateGuardrail(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.
+must be registered, the check's `kind` must match, `config` must pass
+the check's config schema, and `at` must be one of the check's points
+(the problem at `/at`). `escalate` and `compensate` must be at the final
+answer, and `scope.tools` at a tool point. It returns a `Result`; use it
+in tests or wherever guardrails are registered in-process.
 
 ```ts
-import { createCheckRegistry, defineGuardrail } from '@kindgi/guardrails';
+import { createCheckRegistry, validateGuardrail } 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(
+const validated = validateGuardrail(
   {
     id: 'acme.no-fabricated-quotes' as GuardrailId,
     kind: 'zero-llm',
@@ -226,8 +339,8 @@ const defined = defineGuardrail(
   },
   checks,
 );
-if (defined.kind === 'err') {
-  throw new Error(`acme.no-fabricated-quotes: ${defined.error.message}`);
+if (validated.kind === 'err') {
+  throw new Error(`acme.no-fabricated-quotes: ${validated.error.message}`);
 }
 ```
 
@@ -252,7 +365,7 @@ available to the runtime that evaluates it.
 - **`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`, and in a pack when the pack is
+  `configSchema`: by `validateGuardrail`, and in a pack when the pack is
   indexed (a config that doesn't fit is a file error naming where, and
   `kindgi build` refuses the pack; see "How the pack tooling reads this
   file"). In a pack, the declaration's `config` goes into the index and
@@ -260,17 +373,29 @@ available to the runtime that evaluates it.
   check's `evaluate` receives the config its schema resolves, with the
   schema's defaults applied; a check written without `defineCheck` gets
   the config as declared.
-- **`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.
+- **`at`** — where in the turn it runs: `'final-answer'` (the default),
+  `'before-tool'`, `'after-tool'` or `'model-step'`. It must be one of
+  its check's `points`. At a tool point or a model reply, a check that
+  can't run (a point its check doesn't run at as
+  `check-point-unsupported`, or its time ran out as `check-timed-out`)
+  acts as a failed one: `halt` fails the turn, `retry` refuses, withholds
+  or sends back with the reason `its check couldn't run (<code>): <message>`.
+  A check that isn't registered counts there as one that runs at the final
+  answer only, so it fails as `check-point-unsupported`, saying no check by
+  that name is registered; at the final answer it's `unknown-check`. At the
+  final answer, a `retry` whose check can't run goes on as if it passed.
+- **`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; a failed `retry` guardrail sends the answer back for a new
+  one, or at a loop point refuses the call, withholds its result or sends
+  the reply back (above); 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.
+  `escalate` and `compensate` are recorded on the violation, with no
+  escalation or compensating call in 0.1.
 - **`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
@@ -278,9 +403,18 @@ available to the runtime that evaluates it.
 - **`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.
+  `flows` and `tenants` lists narrow it further. `tools`, only at
+  `'before-tool'` and `'after-tool'`, lists the tool ids it checks; a
+  trailing `*` matches every id with that prefix (`'acme.crm.*'`), a `*`
+  anywhere else or an empty list is refused, and left out it checks every
+  tool.
+- **`budget`** — `{ maxCostUsd?, maxLatencyMs? }`. The agent loop
+  enforces `maxLatencyMs` before a tool call, after it and on each model
+  reply (`at`), with a default per kind when it's absent (10 s
+  `zero-llm`, 60 s `llm-judge`, 30 s any other); a check that runs past
+  it fails as one that couldn't run (`check-timed-out`), handled by the
+  guardrail's action. It isn't enforced at the final answer, and
+  `maxCostUsd` isn't enforced.
 - **`judgeCapabilities`** — for `llm-judge`: the capability
   declaration used to route the judge model.
 
@@ -308,7 +442,7 @@ export const toneProfessional: Guardrail = {
   judgeCapabilities: { needs: [{ feature: 'structured-output' }] },
   action: { 'on-violation': 'log-only' },
   severity: 'warn',
-  budget: { maxCostUsd: 0.01, maxLatencyMs: 5000 }, // declarative, not enforced
+  budget: { maxCostUsd: 0.01, maxLatencyMs: 5000 }, // maxLatencyMs: enforced at the loop's points only
 };
 ```
 
@@ -361,7 +495,7 @@ ready for the stricter enforcement.
    silent typos. Prefer Zod for TS-side inference on
    `evaluate(config, ...)`.
 
-5. **Ignoring the `Result` from `defineGuardrail`.** It returns
+5. **Ignoring the `Result` from `validateGuardrail`.** It returns
    `Result<Guardrail, …>`; check `kind` and throw at load time.
    `defineCheck` itself throws when its `configSchema` can't be
    compiled.
@@ -369,9 +503,9 @@ ready for the stricter enforcement.
 ## References
 
 - Type surface: hover any `@kindgi/sdk/define` export for full JSDoc;
-  `Guardrail`, `defineGuardrail` and the built-in checks are in
+  `Guardrail`, `validateGuardrail` and the built-in checks are in
   `@kindgi/guardrails`.
-- API reference: https://docs.kindgi.com/v0.2/reference/typescript/sdk/kindgi/sdk/define/
+- API reference: https://docs.kindgi.com/v0.3/reference/typescript/sdk/kindgi/sdk/define/
 - Built-in check implementations: `packages/guardrails/src/checks.ts`.
 
 ## When the framework itself is the problem