@kindgi/cli 0.0.0-bootstrap.0 → 0.1.1

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

@@ -0,0 +1,252 @@
+---
+name: kindgi-authoring-agents
+description: >
+  Covers writing agents for a Kindgi pack with @kindgi/sdk:
+  defining agents via defineAgent, tool wiring with ToolRef versioning,
+  guardrail references, conversation policy, turn budgets, LLM
+  capability declarations, and prompt template variables. Load this
+  whenever you are authoring or editing code inside a pack's agents/
+  directory, defining an agent, or when the user asks to add, modify,
+  or refactor an agent. Authoring tools is covered by
+  kindgi-authoring-tools; authoring guardrails is covered by
+  kindgi-authoring-guardrails.
+type: core
+library: "@kindgi/sdk"
+version: "0.4.2"
+sdk_version: "0.1.1"
+pack_languages: [node]
+sources:
+  - packages/agents/src/types.ts
+  - packages/agents/src/define.ts
+---
+
+# Authoring Kindgi agents
+
+> **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.
+
+An **agent** is a versioned LLM-powered orchestrator: instructions (a
+prompt template), a declared set of tools it can call, capability
+declarations for the LLM provider, guardrails that gate its outputs,
+and optional multi-turn conversation policy. Agents live at
+`agents/<name>/index.ts` inside a pack.
+
+## Ask before building
+
+Requests like "add an agent" / "create an agent" / "I need an agent"
+are conversation openers, not tickets. Before writing any file, ask:
+
+- **What should the agent DO?** The purpose is the load-bearing thing.
+  Everything else derives from it.
+- **Which tools does it need?** New tools, or reuses of existing?
+- **Multi-turn or one-shot?** Conversation history changes the shape.
+- **Any specific guardrails?** Safety rules the agent must respect.
+
+The pack's existing agents are examples that prove the framework runs
+end-to-end. They are NOT the shape you imitate unless the user
+explicitly asks for that. Inferring purpose from surrounding pack
+shape is how confident, wrong code gets shipped.
+
+## Minimal agent
+
+```ts
+// agents/brief-writer/index.ts
+import { defineAgent } from '@kindgi/sdk/define';
+import type { AgentId, Semver } from '@kindgi/sdk/types';
+
+const defined = defineAgent({
+  id: 'acme.brief-writer' as AgentId,
+  version: '0.1.0' as Semver,
+  name: 'Brief Writer',
+  description:
+    'Drafts appellate briefs from a case file. Cites precedents; escalates novel legal questions.',
+  instructions:
+    'You are drafting a brief in {{ jurisdiction }}. The user provides the case facts; you produce a Section IV argument citing at least two precedents. Use `acme.verify-citation` on every cite before including it. Refuse to fabricate citations — always call the tool.',
+  capabilities: [{ needs: [{ feature: 'tool-use' as const }] }],
+  tools: [
+    { id: 'acme.verify-citation', version: '^0.1.0' },
+    { id: 'acme.fetch-precedent', version: '^0.1.0' },
+  ],
+  retrieval: [],
+  guardrails: ['acme.no-fabricated-quotes'],
+  parameters: [
+    { name: 'jurisdiction', type: 'string', required: true },
+  ],
+  conversationPolicy: { historyLimit: 20 },
+  budget: { maxSteps: 8, maxCostUsd: 0.5, maxWallMs: 60_000 },
+});
+
+if (defined.kind === 'err') {
+  throw new Error(`acme.brief-writer failed to compile: ${defined.error.message}`);
+}
+
+export default defined.value;
+```
+
+## Field-by-field
+
+- **`id`** — `<pack-id>.<agent-name>` (kebab-case, dot-namespaced).
+  Enforced.
+- **`version`** — Semver. Runs pin to a specific version; upgrading
+  the agent doesn't retroactively rewrite in-flight conversations.
+- **`instructions`** — LiquidJS template. `{{ variable }}` substitutes
+  from `parameters` or framework auto-vars (`today`, `now`, `agent.*`,
+  `conversation.*`). Rendered with `strictVariables: true` — unresolved
+  references fail loudly at invoke time. Frame instructions like a
+  competent employee brief: what the agent does, what tools to prefer,
+  what to refuse, what quality bar to hit.
+- **`capabilities`** — declares the resource kinds the agent needs at
+  runtime. `{feature: 'tool-use'}` is standard for tool-calling
+  agents. The router picks the concrete LLM provider at turn time.
+- **`tools`** — `readonly ToolRef[]`, NOT `string[]`. Each entry is
+  `{id, version}` where `version` is an npm-style semver **range**
+  (`'^0.1.0'`, `'~1.2.3'`, `'>=1.0.0 <2.0.0'`). Empty array = chat-only
+  agent.
+- **`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.
+- **`parameters`** — typed inputs the caller supplies at invoke time.
+  UI builds a "configure agent" form from these; runtime validates
+  each required parameter is provided.
+- **`preferredProvider`** — optional soft hint. When set to a
+  `ProviderMetadata.id` (e.g. `'anthropic'`, `'groq'`), the router
+  prefers that provider when at least one of its models satisfies the
+  agent's `capabilities.needs` + tenant policy. Falls back to normal
+  capability-based selection when the preferred provider is
+  unregistered or filtered out.
+- **`preferredModel`** — optional soft hint at the model level: set to
+  a `ModelInfo.name` (e.g. `'gemini-2.5-pro'`), the router prefers
+  `(provider, model)` tuples whose model matches. To require a model
+  rather than prefer it, add a hard requirement to the capability:
+  `capabilities: [{ needs: [{ feature: 'tool-use' }, { models: { allow: ['gemini-2.5-pro'] } }] }]`.
+- **`conversationPolicy`** — optional. Absent = each turn loads the
+  conversation's full history and no HITL gates apply. `historyLimit`
+  caps how many prior messages are loaded; `hitl` configures approval
+  gates (a turn-count gate and per-tool gates). A tenant's `hitl`
+  policy can tighten these — a shorter approval timeout, a higher
+  reviewer role, a stricter gate for a tool — never loosen them.
+- **`budget`** — per-turn ceiling. `maxSteps` caps model-call cycles
+  (default 8); `maxCostUsd` caps model spend; `maxWallMs` caps wall
+  time (default 120 000). Exceeding steps or cost fails the turn with
+  `budget-exceeded`; running out of wall time aborts it
+  (`agent-turn-aborted`, reason `timeout`).
+
+- **`output`** — optional typed result: `{ schema, name?, maxRepairs? }`
+  (JSON Schema, or Zod). The final answer must be JSON matching
+  `schema` (a fenced JSON block is accepted). An answer that doesn't fit
+  goes back to the model with the problems listed, up to `maxRepairs`
+  times (default 1); then the turn fails with `output-schema-violation`.
+  The parsed answer is the turn result's `output`, and in a flow
+  `nodeOutputs.<step>.output.<field>`. A Zod `.default()` field must be
+  in the answer: downstream steps read every field.
+- **`toolErrors`** — optional: what the turn does when a tool call
+  fails. The failure goes back to the model as the call's result (what
+  failed and why) so it can correct the call, up to `maxRetries` times
+  per turn (default 1), for the kinds in `retryOn` (default
+  `['invalid-arguments', 'unknown-tool']`, failures where nothing ran).
+  Add `'tool-error'` to retry a tool that ran and failed — only when
+  retrying it is safe (a mutating tool may have changed something before
+  failing). Each retry costs a step against `budget.maxSteps`. Past the
+  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.
+
+## What a turn receives
+
+- **Run directly** (`kindgi runs start --agent=… --input='{…}'`, or
+  `POST /v1/runs { agent, input }`), the input is `{ userMessage,
+  conversationId?, participantId?, parameters? }`:
+  - `userMessage` is the turn's message;
+  - `conversationId` continues a conversation;
+  - `parameters` fills the agent's `parameters` (string, number or
+    boolean values).
+- **As a flow step** (`{ kind: 'agent', ref: 'acme.brief-writer' }`), the
+  agent gets the step's input in two ways:
+  - as **structured input**, which the instructions read as
+    `{{ input.caseFacts }}`;
+  - as the user message (the input as JSON).
+
+  The step's `config.parameters` fills `parameters`, and `config.version`
+  pins a version. With a typed `output`, the flow reads the answer at
+  `nodeOutputs.<step>.output.<field>`. See `kindgi-authoring-flows`.
+
+`{{ input.* }}` is set only in a flow step, so an agent that reads it
+belongs in a flow. Rendering is strict: a direct run of such an agent
+fails when its instructions render.
+
+## Iterating on an agent
+
+Edit `agents/<name>/index.ts`, save. The next `kindgi runs start`
+sees the change — new instructions, new tool bindings, new
+capabilities, new preferredProvider, new budget. No version bump,
+no restart. Source is truth in dev.
+
+The `version` field is a **semver contract for humans reading the
+source** — it declares what conversations pinned to this agent can
+rely on. Bump because you're breaking that contract (removed a
+parameter, tightened the instructions in a user-visible way,
+switched to an incompatible provider policy), not because you saved
+the file. If you're iterating on the prompt, leave version alone.
+
+**When version matters:** conversations persist their `agentVersion`
+at start and pin resume-across-turn to that version. `kindgi deploy`
+publishes to a durable production registry that enforces the
+immutable `(id, version)` contract. Both surfaces are deploy-time
+concerns, not author-time.
+
+## Common mistakes
+
+1. **Adding an agent without asking what it should do.** The most
+   common failure mode. "Add an agent" without a stated purpose gets
+   answered by imitating the shape of the pack's example agent. Ask
+   first.
+
+2. **`tools: ['id-string']`** — `tools` is `ToolRef[]`, so TypeScript
+   rejects bare strings, and `defineAgent` returns `invalid-agent` for
+   one that slips through (plain JavaScript, a cast). Use
+   `[{id: 'acme.x', version: '^0.1.0'}]`.
+
+3. **Referencing guardrails that aren't registered.** If
+   `agent.guardrails` contains an id the tenant has no guardrail for
+   (registered via `POST /v1/guardrails`, a deploy, or `kindgi dev`),
+   turn setup fails with `unresolved-guardrail`. Either author the
+   guardrail first or drop it from the agent's list.
+
+4. **Un-declared `{{ variable }}` in instructions.** LiquidJS renders
+   with `strictVariables: true` — a reference to `{{ jurisdiction }}`
+   that isn't in `parameters` OR an auto-var throws at invoke time.
+   Either add it to `parameters` or use a framework auto-var.
+
+5. **Empty `capabilities`.** `defineAgent` rejects an empty
+   `capabilities` array (`invalid-agent`) — the turn routes its first
+   capability to pick a model. Declare
+   `[{needs: [{feature: 'tool-use' as const}]}]` (or the matching
+   feature set for your use case).
+
+6. **Missing `Result` unwrap.** `defineAgent` returns `Result<Agent,
+   InvalidAgentError>`. Always check `defined.kind === 'err' && throw`
+   so a broken agent fails at module load.
+
+## References
+
+- Type surface: `hover any @kindgi/sdk/define export` in your editor
+  for full JSDoc.
+- API reference: https://docs.kindgi.com/v0.1/reference/typescript/sdk/kindgi/sdk/define/ (every `define*` spec, field by field).
+- Common patterns: the `sample` template's `agents/echo-agent`
+  demonstrates the smallest tool-calling shape.
+
+## When the framework itself is the problem
+
+If you diagnose that the bug lives in Kindgi/`@kindgi/sdk` itself (SDK
+type drift, wire schema silently dropping a field like
+`preferredProvider`, router picking the wrong provider, 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.

package/dist/sdk-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.1.1"
+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`.