@kindgi/sdk 0.1.4 → 0.1.5-rc.0

package/skills/kindgi-python-authoring-tools/SKILL.md

@@ -116,7 +116,11 @@ def verify_citation(citation: Citation, ctx: ToolContext) -> Verdict:
   or wait with `ctx.cancellation.wait(timeout)` between slow steps.
 - `ctx.secrets` — the secrets the tool declares in `needs_spec`,
   resolved for the call's tenant (below).
-- `ctx.env`, `ctx.config` — **reserved, empty today**.
+- `ctx.env` — the env values the tool declares in `needs_spec`, resolved
+  for the call: its project's value, else its org's, else the tenant's
+  (`kindgi env set NAME <value> --scope=project:<id> --env=<env>`).
+  Strings, and not secret. Empty from an older runtime.
+- `ctx.config` — **reserved, empty today**.
 
 ## Configuration and secrets
 
@@ -140,6 +144,33 @@ fails the call, naming the secret, when it is missing or doesn't match.
 Every declared secret is required. In a test, pass them:
 `ToolContext.for_test(secrets={"CITATOR_KEY": "…"})`.
 
+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 `needs_spec`, read from `ctx.env`:
+
+```python
+@tool(
+    id="acme.find-order",
+    mutating=False,
+    needs_spec={
+        "env": {
+            "ORDERS_BASE_URL": {"type": "string", "pattern": "^https://"},
+            "ORDERS_REGION": {"type": "string", "enum": ["eu", "us"], "default": "eu"},
+        }
+    },
+)
+def find_order(lookup: Lookup, ctx: ToolContext) -> Found:
+    """…"""
+    return Found(url=f"{ctx.env['ORDERS_BASE_URL']}/{ctx.env['ORDERS_REGION']}/orders/{lookup.order_id}")
+```
+
+- **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, never an env value.
+- **In a test:** `ToolContext.for_test(env={"ORDERS_BASE_URL": "…"})`.
+
 Everything else comes from the process environment: `os.environ["CITATOR_URL"]`.
 The pack service runs with the pack's environment — in `kindgi dev`
 that is the pack's `.env` and `.env.local` (or `[tool.kindgi.dev]
@@ -274,9 +305,9 @@ removed field, a narrower type — not on every save.
 ## Common mistakes
 
 1. **Copying the sample tool's shape without asking what the tool should do.**
-2. **Reading `ctx.env` / `ctx.config`, or an undeclared `ctx.secrets` name.**
-   The first two are empty, and `ctx.secrets` holds only what `needs_spec`
-   declares; use `os.environ` for the rest.
+2. **Reading `ctx.config`, or an undeclared `ctx.env` or `ctx.secrets` name.**
+   `ctx.config` is empty, and `ctx.env` and `ctx.secrets` hold only what
+   `needs_spec` declares; use `os.environ` for the rest.
 3. **A non-object input** (`def f(n: int)`): the input must be a model,
    TypedDict, dataclass or object schema.
 4. **No docstring and no `description=`**, or an unannotated input or

package/skills/kindgi-python-getting-started/SKILL.md

@@ -189,7 +189,7 @@ from kindgi.client import Kindgi
 client = Kindgi()  # KINDGI_API_URL + KINDGI_API_TOKEN, or Kindgi(url, token=…)
 run = client.runs.start(agent="my-pack.echo-agent", input={"userMessage": "Ada"})
 print(run.status, run.output["response"]["content"])
-for event in client.runs.stream(str(run.id)):
+for event in client.runs.follow(run.id):  # to the run's end, reconnecting
     print(event.kind)
 ```
 

package/skills/kindgi-scala-authoring-agents/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: kindgi-scala-authoring-agents
+description: >
+  Covers writing agents for a Kindgi pack in Scala (`kindgi-pack-scala`,
+  `com.kindgi.pack.scaladsl`): `Agent(id)` as a `val` of an object named like
+  its file, wiring tools (`Tool` vals or an id with a version range) and
+  guardrails, capabilities and model choice (preferredProvider /
+  preferredModel), conversation policy, turn budgets, prompt parameters, a
+  typed answer from a case class (`output[T]`), and tool-error retries, all
+  as data with Scala maps. Load this whenever you are authoring or editing
+  code in a Scala pack's agents packages (a pack whose `kindgi.config.json`
+  says `"language": "scala"`), defining an agent, or when the user asks to
+  add, change or refactor one. Scala tools are covered by
+  kindgi-scala-authoring-tools, Scala guardrails by
+  kindgi-scala-authoring-guardrails, connecting a real model by
+  kindgi-authoring-providers.
+type: core
+library: "kindgi-pack-scala"
+version: "0.1.0"
+sdk_version: "0.0.0"
+pack_languages: [scala]
+sources:
+  - sdks/scala/README.md
+  - sdks/scala/kindgi-pack-scala/src/main/scala/com/kindgi/pack/scaladsl/Agent.scala
+  - packages/specs/schemas/agent.schema.json
+  - packages/specs/schemas/pack-index.schema.json
+---
+
+# Authoring Kindgi agents in Scala
+
+> **Running `kindgi`:** the pack pins its CLI (`"cli"` in
+> `kindgi.config.json`), and `./kindgiw` runs that version, so every
+> `kindgi <command>` below runs as `./kindgiw <command>`.
+>
+> Scala support is in preview: tested and supported, but the API may still
+> change in 0.1.6 without the usual deprecation period.
+
+An **agent** is a versioned, model-driven orchestrator. It's made of:
+- instructions (a prompt template);
+- the tools it may call;
+- the capabilities its model needs;
+- guardrails that gate its answer;
+- optionally, a conversation policy.
+
+In a Scala pack it is **data**: a `val` of type `Agent` in an object named
+like its file, in an `agents` package. The model runs in the Kindgi runtime,
+not in your JVM. Your Scala code runs only inside the agent's tools and
+guardrail checks.
+
+## Ask before building
+
+"Add an agent" is a conversation opener, not a ticket. Before writing a
+file, ask:
+
+- **What should the agent do?** The purpose drives everything else.
+- **Which tools does it need?** New ones, or existing ones?
+- **Multi-turn or one-shot?** History changes the shape.
+- **Any rules it must respect?** Those become guardrails.
+
+The pack's sample agent proves the runtime works end to end. It is not the
+shape to imitate unless the user asks for that.
+
+## An agent
+
+```scala
+// src/main/scala/acme/agents/BriefWriter.scala
+package acme.agents
+
+import acme.guardrails.ResponseNotEmpty
+import acme.tools.Echo
+import com.kindgi.pack.scaladsl._
+
+/** acme.brief-writer: drafts a brief's argument from the case facts. */
+object BriefWriter {
+  /** The typed answer: the final message must be JSON of this shape. */
+  final case class Brief(argument: String, citations: List[String])
+
+  val agent: Agent = Agent("acme.brief-writer")
+    .version("0.1.0")
+    .name("Brief Writer")
+    .description("Drafts appellate briefs from a case file; cites precedents.")
+    .instructions(
+      "You are drafting a brief in {{ jurisdiction }}. The user gives the case facts; you write " +
+        "a Section IV argument citing at least two precedents. Check every cite with the echo tool " +
+        "before using it. Never invent one.")
+    .capability(Map("needs" -> List(Map("feature" -> "tool-use"))))
+    .tool(Echo.tool)
+    .guardrail(ResponseNotEmpty.guardrail)
+    .set("parameters", List(Map("name" -> "jurisdiction", "type" -> "string", "required" -> true)))
+    .set("conversationPolicy", Map("historyLimit" -> 20))
+    .set("budget", Map("maxSteps" -> 8, "maxCostUsd" -> 0.5, "maxWallMs" -> 60000))
+    .set("toolErrors", Map("maxRetries" -> 1, "retryOn" -> List("invalid-arguments", "unknown-tool")))
+    .output[Brief]
+    .build()
+}
+```
+
+- Tools and guardrails are the pack's own vals, imported like any member:
+  `.tool(Echo.tool)`, `.guardrail(ResponseNotEmpty.guardrail)`.
+- **`build()` needs a version, a name and instructions.** Anything missing
+  is an error where the agent is defined, and the indexer reports it with
+  the file.
+- **Every other field is `set(field, value)`, keyed as on the wire,** with
+  Scala maps and lists: the field and its maps are camelCase
+  (`conversationPolicy`, `maxSteps`, `historyLimit`), as `agent.schema.json`
+  names them. The indexer checks each agent against the pack index's
+  schema, and `kindgi dev` reports a mistake with its file.
+- An object may hold several agents, each in its own `val`.
+
+## Field by field
+
+- **`id`:** `<pack-id>.<agent-name>`, kebab-case, dot-namespaced.
+- **`version`:** an exact semver. Conversations pin the version they started
+  on.
+- **`name`, `description`**, and `set("tags", List(…))`: for people and
+  listings. The model never sees the description.
+- **`instructions`:** a LiquidJS template. `{{ variable }}` comes from
+  `parameters` or the runtime's own variables (`today`, `now`, `agent.*`,
+  `conversation.*`). It's rendered strictly: an unknown variable fails the
+  turn. Write it as a brief for a capable colleague: what to do, which tools
+  to prefer, what to refuse, the quality bar. Name a tool by what it does
+  ("the verify-citation tool"), never by its dotted id. The model sees ids in
+  its provider's form (`acme__verify-citation` for Anthropic and
+  OpenAI-compatible models), and a dotted id in the instructions can make it
+  call a name it wasn't given. `instructions(Map("prompt" -> …, "version" -> …))`
+  references a registered prompt block instead.
+- **`capability(Map(…))`:** what the model must support, such as
+  `Map("needs" -> List(Map("feature" -> "tool-use")))`. Call it once per
+  capability. The turn routes its first capability to pick a provider and
+  model; with none declared, the turn fails.
+- **`tool(tool)`:** pins that tool's version (its own, or the pack's).
+  **`tool(id, range)`** is a tool of another pack, with a semver **range**
+  (`"^1.0.0"`); the highest active matching version is picked at turn
+  start. An agent with no tools is chat-only.
+- **`guardrail(guardrail)`** or **`guardrail(id)`:** evaluated once per turn
+  on the final answer, before it is stored. An id with no registered
+  guardrail fails the turn.
+- **`set("parameters", List(Map("name" -> …, "type" -> …, "required" -> …)))`:**
+  inputs the caller supplies per run. They fill `{{ … }}` in the
+  instructions.
+- **`set("preferredProvider", "anthropic")`, `set("preferredModel", "claude-haiku-4-5")`:**
+  soft hints. The router prefers them when they satisfy the capabilities.
+  To *require* a model, put it in the capability:
+  `Map("needs" -> List(Map("feature" -> "tool-use"), Map("models" -> Map("allow" -> List("claude-haiku-4-5")))))`.
+- **`set("conversationPolicy", …)`:** `historyLimit` caps the prior messages
+  loaded, and `hitl` configures approval gates. Absent, the turn loads the
+  full history with no gates. A tenant's `hitl` policy can tighten the gates
+  (a shorter timeout, a higher reviewer role, stricter per tool), never
+  loosen them.
+- **`set("budget", …)`:** per turn. `maxSteps` counts model calls (default
+  8); `maxCostUsd`; `maxWallMs` (default 120 000). Exceeding the steps or the
+  cost fails the turn (`budget-exceeded`); running out of wall time aborts
+  it. Leave room for real models: a turn with tool calls can take tens of
+  seconds.
+- **`output[T]`:** a typed answer, with its schema derived from the case
+  class. The final answer must be JSON matching it. A wrong one goes back to
+  the model with the problems (`maxRepairs`, default 1), and then the turn
+  fails (`output-schema-violation`). For `maxRepairs` or a schema of your
+  own, use `set("output", Map("schema" -> …, "maxRepairs" -> 2))`. The parsed
+  answer is the turn result's `output`. In a flow it is
+  `nodeOutputs.<step>.output.<field>`.
+- **`set("toolErrors", …)`:** `maxRetries` and `retryOn`. A failed tool call
+  goes back to the model as the call's result, so it can fix the call. The
+  default kinds are `invalid-arguments` and `unknown-tool` (nothing ran). Add
+  `tool-error` only when retrying the tool is safe. Each retry costs a step.
+
+## Which model answers
+
+Agents run on a registered model provider: the router picks one whose
+models satisfy the capabilities. `kindgi dev` gives a new pack `dev-echo`, a
+**fallback** that answers only while no other provider fits. It calls the
+first tool and replies "⚠ dev-echo isn't a real model: …", then "Tool
+responded: …". The turn carries the `fallback-provider` and
+`dev-echo-not-a-model` warnings. dev-echo can't fill in any other tool
+input, and can't give a typed answer: an agent with an output type fails
+with `output-schema-violation` until a real model is registered. To register
+one, see `kindgi-authoring-providers` (`./kindgiw providers register --preset=anthropic`,
+or `"providers": [{"preset": "anthropic"}]` in `kindgi.config.json`).
+
+## Iterating
+
+Save the file: `kindgi dev` recompiles through sbt's server, re-indexes, and
+the next run uses it, with no restart. Bump `version` when you break what
+callers rely on (a removed parameter, an incompatible output), not on every
+save.
+
+Run an agent from another terminal in the pack directory:
+
+```sh
+./kindgiw runs start --agent=acme.brief-writer --input='{"userMessage":"…","parameters":{"jurisdiction":"US"}}'
+```
+
+## Common mistakes
+
+1. **Building an agent without asking what it should do.** Copying the
+   sample's shape answers the wrong question.
+2. **No `capability(…)`.** The turn can't pick a model.
+3. **Scala names inside the maps.** `set("budget", Map("max_steps" -> 4))`
+   isn't a budget: the keys are the wire's camelCase (`maxSteps`,
+   `historyLimit`, `maxRetries`).
+4. **An unregistered guardrail id.** Pass the `Guardrail` val, or make sure
+   the id is one the tenant has.
+5. **`{{ variable }}` not in `parameters`.** The turn fails when the
+   instructions render.
+6. **An agent as a `def` or a `lazy val`.** It's a file error: make it a
+   `val`.
+7. **A tight `maxWallMs` with a real model.** 15 s aborts real turns under
+   load; 60 s is a safer start.
+8. **Expecting dev-echo to give a typed answer.** It can't: register a real
+   model first.
+
+## When the framework itself is the problem
+
+If the bug is in Kindgi, kindgi-pack or the Scala layer (the index dropping
+a field, a misleading error, the router picking the wrong model) and not in
+the pack's code, load `kindgi-framework-feedback` and file it with
+`./kindgiw feedback write`.

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

@@ -0,0 +1,357 @@
+---
+name: kindgi-scala-authoring-flows
+description: >
+  Covers writing flows for a Kindgi pack in Scala (`kindgi-pack-scala`,
+  `com.kindgi.pack.scaladsl`): `Flow(id)` as a `val` of an object named like
+  its file, tool and agent steps (`toolNode`, `agentNode`, or a node map
+  with `inputMapping` and `config`), edges and their `when` conditions and
+  `policy` (`edge(Map(…))`), branches that join again, inputMapping from
+  runInput / nodeOutputs, typed agent output in a flow, the flow's declared
+  output, loops and fanout, and running a flow (runs start --flow, in the
+  background, as a dry run) and reading its journal. Load this whenever you
+  are authoring or editing code in a Scala pack's flows packages (a pack
+  whose `kindgi.config.json` says `"language": "scala"`), defining a flow,
+  or when the user asks to add, change or debug one. Scala tools are
+  covered by kindgi-scala-authoring-tools, Scala agents by
+  kindgi-scala-authoring-agents.
+type: core
+library: "kindgi-pack-scala"
+version: "0.1.0"
+sdk_version: "0.0.0"
+pack_languages: [scala]
+sources:
+  - sdks/scala/README.md
+  - sdks/scala/kindgi-pack-scala/src/main/scala/com/kindgi/pack/scaladsl/Agent.scala
+  - packages/specs/schemas/flow.schema.json
+---
+
+# Authoring Kindgi flows in Scala
+
+> **Running `kindgi`:** the pack pins its CLI (`"cli"` in
+> `kindgi.config.json`), and `./kindgiw` runs that version, so every
+> `kindgi <command>` below runs as `./kindgiw <command>`.
+>
+> Scala support is in preview: tested and supported, but the API may still
+> change in 0.1.6 without the usual deprecation period.
+
+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: a `val` of type `Flow` in an object named like its
+file, in a `flows` package. 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?** Know which tools write: a dry run
+  stops before them (see "Running a flow").
+
+## A flow
+
+The tools and the agent it runs:
+
+```scala
+// src/main/scala/acme/tools/Tickets.scala
+package acme.tools
+
+import com.kindgi.pack.scaladsl._
+
+/** The ticket tools: parse one, look its invoice up, draft the reply. */
+object Tickets {
+  final case class Ticket(customerId: String, body: String)
+  final case class ParseInput(ticket: Ticket)
+  final case class Parsed(text: String)
+  final case class InvoiceInput(customerId: String)
+  final case class Invoice(number: String, amount: BigDecimal)
+  final case class Found(invoice: Invoice)
+  /** `invoice` is absent when the billing step didn't run: an Option. */
+  final case class ReplyInput(category: String, invoice: Option[Invoice])
+  final case class Reply(text: String)
+
+  val parse: Tool[ParseInput, Parsed] = Tool[ParseInput, Parsed]("acme.parse-ticket")
+    .description("Extracts a ticket's text.")
+    .readOnly
+    .handler((in, _) => Parsed(in.ticket.body.strip))
+
+  val lookupInvoice: Tool[InvoiceInput, Found] = Tool[InvoiceInput, Found]("acme.lookup-invoice")
+    .description("The customer's latest invoice.")
+    .readOnly
+    .handler((_, _) => Found(Invoice("INV-1", BigDecimal("42.00"))))
+
+  val draftReply: Tool[ReplyInput, Reply] = Tool[ReplyInput, Reply]("acme.draft-reply")
+    .description("Drafts a reply for the ticket's category.")
+    .readOnly
+    .handler((in, _) =>
+      Reply(in.invoice match {
+        case Some(invoice) => s"Invoice ${invoice.number} is ${invoice.amount}."
+        case None          => s"Thanks, we're on it (${in.category})."
+      }))
+}
+```
+
+```scala
+// src/main/scala/acme/agents/TicketClassifier.scala
+package acme.agents
+
+import com.kindgi.pack.scaladsl._
+
+/** acme.ticket-classifier: one word for a ticket's category. */
+object TicketClassifier {
+  final case class Category(category: String)
+
+  val agent: Agent = Agent("acme.ticket-classifier")
+    .version("0.1.0")
+    .name("Ticket classifier")
+    .instructions(
+      "Classify the support ticket for {{ product }}: answer billing, bug or other, " +
+        "as JSON with one field, category.")
+    .capability(Map("needs" -> List(Map("feature" -> "tool-use"))))
+    .set("parameters", List(Map("name" -> "product", "type" -> "string", "required" -> true)))
+    .output[Category]
+    .build()
+}
+```
+
+The flow:
+
+```scala
+// src/main/scala/acme/flows/TriageTicket.scala
+package acme.flows
+
+import acme.agents.TicketClassifier
+import acme.tools.Tickets
+import com.kindgi.pack.scaladsl._
+
+/** acme.triage-ticket: parse, classify, look billing up when needed, reply. */
+object TriageTicket {
+  private val isBilling = Map(
+    "op" -> "eq",
+    "left" -> Map("path" -> "nodeOutputs.classify.output.category"),
+    "right" -> Map("literal" -> "billing"))
+
+  val flow: Flow = Flow("acme.triage-ticket")
+    .version("0.1.0")
+    .set("name", "Triage a support ticket")
+    .set("description", "Parses a ticket, classifies it, looks billing up when needed, drafts a reply.")
+    .node(Map("id" -> "parse", "kind" -> "tool", "ref" -> Tickets.parse,
+      "inputMapping" -> Map("ticket" -> Map("path" -> "runInput.ticket"))))
+    .node(Map("id" -> "classify", "kind" -> "agent", "ref" -> TicketClassifier.agent,
+      "inputMapping" -> Map("text" -> Map("path" -> "nodeOutputs.parse.text")),
+      "config" -> Map("parameters" -> Map("product" -> "acme-cloud"))))
+    .node(Map("id" -> "billing", "kind" -> "tool", "ref" -> Tickets.lookupInvoice,
+      "inputMapping" -> Map("customerId" -> Map("path" -> "runInput.ticket.customerId"))))
+    .node(Map("id" -> "reply", "kind" -> "tool", "ref" -> Tickets.draftReply,
+      "inputMapping" -> Map(
+        "category" -> Map("path" -> "nodeOutputs.classify.output.category"),
+        "invoice" -> Map("path" -> "nodeOutputs.billing.invoice"))))
+    .edge("e0", "$start", "parse")
+    .edge("e1", "parse", "classify")
+    .edge(Map("id" -> "e2", "from" -> "classify", "to" -> "billing", "when" -> isBilling))
+    .edge(Map("id" -> "e3", "from" -> "classify", "to" -> "reply", "when" -> Map("op" -> "not", "child" -> isBilling)))
+    .edge("e4", "billing", "reply")
+    .edge("e5", "reply", "$end")
+    .set("output", Map(
+      "mapping" -> Map(
+        "category" -> Map("path" -> "nodeOutputs.classify.output.category"),
+        "reply" -> Map("path" -> "nodeOutputs.reply.text")),
+      "schema" -> Map(
+        "type" -> "object",
+        "properties" -> Map("category" -> Map("type" -> "string"), "reply" -> Map("type" -> "string")),
+        "required" -> List("category", "reply"))))
+    .build()
+}
+```
+
+- **Steps:** `toolNode(id, tool)` and `agentNode(id, agent)` are a step with
+  nothing more. A step with an `inputMapping`, a `config`, a loop or a fanout
+  is a map, `node(Map(…))`, as `flow.schema.json` describes it. In a node's
+  map, a `Tool`, `Agent` or `Flow` (loop bodies and fanout branches included)
+  becomes its id. A primitive of another pack is its id string.
+- **Edges:** `edge(id, from, to)` joins two steps. An edge with a condition
+  (`when`) or a `policy` is a map, `edge(Map(…))`.
+- **Other fields:** `set(field, value)` takes `name`, `description`,
+  `output`, `maxParallelism` and `metadata`. `build()` needs a version.
+- **The maps are the wire's shape,** in Scala maps and lists, so their keys
+  are camelCase (`inputMapping`, `loopKind`, `maxIterations`).
+- **Where it's checked:** the indexer checks every flow against
+  `flow.schema.json` (version, node and edge shapes, `$start` / `$end`).
+  `kindgi dev` reports a mistake as a file error that says what and where,
+  while the pack's other primitives keep serving. Whether a step's tool or
+  agent exists is checked when a run starts (see "Running a flow").
+
+## Nodes
+
+- **A tool step** (`"kind" -> "tool"`) runs the tool `ref`.
+  - Its input is what the node's `inputMapping` builds; else, the output of
+    the node's single upstream node (the run input after `$start`).
+  - The input is checked against the tool's input schema, so a mismatch
+    fails the step with `input-validation-failed`.
+  - The node's output is what the tool returned, as JSON.
+- **An agent step** (`"kind" -> "agent"`) runs one turn of the agent `ref`,
+  as a child run of the flow run.
+  - The agent gets the node's input two ways: as structured input
+    (`{{ input.text }}` in its instructions), and as its user message (the
+    input as JSON).
+  - `"config" -> Map("parameters" -> Map(…))` fills the agent's `parameters`
+    (string, number or boolean values). `"config" -> Map("version" -> "1.2.0")`
+    pins an agent version; without it, the latest active version runs.
+  - The node's output: `output` is the agent's typed answer (its
+    `output[T]`); `text` is the answer as text; `runId` and `conversationId`
+    are the child run's. Read a field as `nodeOutputs.<node>.output.<field>`.
+  - An answer that doesn't fit the agent's output, after its repairs, fails
+    the step with `output-schema-violation`. An approval inside the agent's
+    turn parks the flow until it's decided.
+- **A loop** (`"kind" -> "loop"`) repeats a body.
+  - `"loopKind" -> "foreach"` runs it once per element of `iterateOver`
+    (`concurrency` up to 32 in parallel). `"loopKind" -> "while"` runs it
+    until `exitCondition`.
+  - The body (`"body" -> Map("nodes" -> List(…), "edges" -> List(…))`) has
+    its own nodes and edges, with `$loop-start` and `$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.
+- **A fanout** (`"kind" -> "fanout"`) runs several handlers on the same input
+  at once. Each is a branch (`branchId`, `handler`: a `Tool` or an id, and
+  `outputSchema`). `convergence` decides the result: `all-succeed`,
+  `any-succeed` (the first success wins), or `settle-all` (wait for every
+  branch and report each).
+- **A sub-flow** (`"kind" -> "subgraph"`) 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 maps:
+
+| 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` (a list) |
+| `not` | `op`, `child` |
+
+Each operand is `Map("literal" -> …)` or `Map("path" -> …)`. When a path
+doesn't resolve, `eq`, `lt`, `lte`, `gt` and `gte` are false, and `ne` is
+true. So for the "otherwise" branch, wrap the condition in `not` (as above)
+rather than writing a second comparison: it covers exactly what the first
+edge doesn't. A condition used twice is easiest as a `val` (`isBilling`).
+
+**Joining branches.** A node with several incoming edges runs once every one
+of them is decided and at least one fired. Above, `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; a node with several ignores it):
+- `"retry" -> Map("maxAttempts" -> …, "delayMs" -> …)`, with `backoff` and
+  `maxDelayMs` optional; 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.
+
+## Inputs and the output
+
+`inputMapping` maps each key to a `literal` or a `path`. Its keys are the
+tool's input **as it travels**: the case class's Jackson names (a parameter
+`customerId` is the key `customerId`; with `@JsonProperty("customer_id")`,
+it's `customer_id`). Paths are dot-separated (a number segment indexes an
+array: `items.0.sku`), rooted at:
+- `runInput.…`: the input the run started with;
+- `nodeOutputs.<nodeId>.…`: a step's output. For an agent step, add
+  `.output.<field>` to read its typed answer;
+- `state.…`: values the runtime's own handlers write. Pack tools don't
+  write it, so use `nodeOutputs`.
+
+A path that doesn't resolve leaves its key out. So a step after a branch
+that didn't run gets no `invoice` key at all. Make that parameter an
+`Option` (as above), or give it a default.
+
+`set("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 an 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
+./kindgiw runs start --flow=acme.triage-ticket --input='{"ticket":{"customerId":"c-1","body":"Charged twice"}}'
+./kindgiw runs start --flow=acme.triage-ticket --input=@ticket.json --no-wait   # the run id now; it finishes in the background
+./kindgiw runs start --flow=acme.triage-ticket --input=@ticket.json --dry-run   # stops before a tool that may write
+./kindgiw runs get <run-id>        # status, output, failureMessage
+./kindgiw runs journal <run-id>    # every step.started / step.completed / edge.evaluated
+./kindgiw runs stream <run-id>     # follow a running one
+./kindgiw 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`, but only if running the
+  step twice is safe.
+- **`--no-wait`** is how an application starts runs
+  (`"options": {"wait": false}`). It answers with the run id at once; poll
+  the run or follow its stream.
+- **`--dry-run`** runs a tool only if it's declared read-only (`readOnly`)
+  and has 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.
+
+## Iterating on a flow
+
+Save the file, and `kindgi dev` recompiles and 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
+   `EchoFlow` 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. Wrap the positive
+   condition in `not`.
+3. **Reading an agent step's answer at `nodeOutputs.<step>.<field>`.** The
+   typed answer is under `.output`. An agent without an output type has
+   only `text`.
+4. **A required input parameter fed by a branch that may not run.** The key
+   is left out, the tool's input check fails, and so does the step. Make it
+   an `Option`, or give it a default.
+5. **`inputMapping` keys in the wrong spelling.** They're the input's wire
+   names.
+6. **A `when` given through `set("edges", …)`.** `build()` writes the edges
+   added with `edge(…)`; use `edge(Map(…))` for an edge with a condition or
+   a policy.
+7. **A sub-flow node.** A run refuses it (`flow-unbound`).
+8. **Duplicate node ids inside a loop body.** Ids are unique across the
+   whole flow, bodies included.
+9. **`readOnly` on a tool that writes.** A dry run then runs it for real.
+10. **A flow as a `def` or a `lazy val`.** It's a file error: make it a
+    `val`.
+
+## When the framework itself is the problem
+
+If the bug is in Kindgi, kindgi-pack or the Scala layer (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
+`./kindgiw feedback write`.