@kindgi/sdk 0.1.4 → 0.1.5

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

@@ -0,0 +1,270 @@
+---
+name: kindgi-java-getting-started
+description: >
+  Getting a Java Kindgi pack running: what a pack is, scaffolding one
+  (`kindgi init <name> --template=java`) or adding Kindgi to an existing
+  Maven app (`kindgi.config.json`, discovery under `kindgi` packages),
+  `./kindgiw dev`, the first agent run, connecting a real model, flows,
+  calling the Kindgi API from Java (`com.kindgi:kindgi-client`), and
+  building an image. Load this when a Maven project has no
+  `kindgi.config.json` yet and the user asks to "add Kindgi", "make an
+  agent", "set up a pack", or when you are orienting in a Java pack
+  (`kindgi.config.json` with `"language": "java"`) for the first time.
+  Authoring tools, guardrails, agents and flows is covered by
+  kindgi-java-authoring-tools, kindgi-java-authoring-guardrails,
+  kindgi-java-authoring-agents and kindgi-java-authoring-flows; models by
+  kindgi-authoring-providers.
+type: core
+library: "kindgi-pack (Java)"
+version: "0.1.0"
+sdk_version: "0.0.0"
+pack_languages: [java]
+sources:
+  - sdks/java/kindgi-pack/README.md
+  - sdks/java/README.md
+  - site/src/content/docs/start/quickstart-java.md
+---
+
+# Getting started with Kindgi in Java
+
+> **Running `kindgi`:** the pack pins its CLI (`"cli"` in
+> `kindgi.config.json`), as Maven's wrapper pins Maven. `./kindgiw` runs that
+> version (`kindgiw.cmd` on Windows): through Node's `npx` when Node is
+> installed, else `uvx`. So every `kindgi <command>` below runs as
+> `./kindgiw <command>`, and `./kindgiw upgrade` moves the pin.
+>
+> **Preview:** Java and Scala support is tested and supported, but its API
+> may still change in 0.1.6 without the usual deprecation period.
+
+## What a pack is
+
+A **pack** is a project Kindgi indexes and runs. Its config is
+`kindgi.config.json` (`"language": "java"`). Its primitives are
+`public static final` fields of classes in four kinds of packages:
+
+- **Tools** (`…/tools/…`, `Tool.define`): your Java code an agent or flow
+  calls.
+- **Guardrails** (`…/guardrails/…`, `Guardrail.define`): checks over an
+  agent's turn.
+- **Agents** (`…/agents/…`, `Agent.define`): data. Instructions, tools,
+  capabilities. The model runs in Kindgi.
+- **Flows** (`…/flows/…`, `Flow.define`): data. Steps (tool or agent nodes)
+  and the edges between them.
+
+Kindgi runs the tools and checks in the pack's own JVM (the pack service,
+`com.kindgi:kindgi-pack`) and calls them over HTTP. Everything else runs in
+the Kindgi runtime. In those packages, a helper is a package-private class,
+a record, an enum or an interface. A public class that defines nothing is
+an error, so a forgotten `static` can't drop a tool silently. Tests
+(`*Test.java`, `*IT.java`, `src/test/`) are never primitives.
+
+## Scaffold a new pack
+
+You need a JDK 17 or later (`JAVA_HOME`). Maven comes with the pack
+(`./mvnw`).
+
+```sh
+npx --yes @kindgi/cli@0.1 init my-pack --template=java   # or: uvx --from "kindgi-cli>=0.1,<0.2" kindgi init …
+cd my-pack
+./mvnw test        # the template's tests: the tools, called directly
+./kindgiw dev      # boots Kindgi locally and runs this pack, recompiling on save
+```
+
+`kindgi dev` needs Docker and Postgres. It starts Postgres in Docker unless
+`KINDGI_DATABASE_URL` points at yours. It checks the JDK (`JAVA_HOME`'s, or
+`dev.javaHome` in `kindgi.config.json`) and Maven (the pack's `mvnw`, or
+`dev.maven`, such as `["mvn", "-s", "settings.xml"]`). Maven compiles the
+pack, the Java indexer reads it, and a save recompiles. A compile error is
+reported as `file:line:col`, and the last good code keeps serving.
+`MAVEN_ARGS` and `MAVEN_OPTS` reach Maven, never the pack.
+
+## Add Kindgi to an existing Maven app
+
+In the app's directory (where its `pom.xml` is):
+
+```sh
+npx --yes @kindgi/cli@0.1 init   # --pack-id=<id> if the app's artifactId doesn't make one
+./kindgiw dev
+```
+
+`init` writes `kindgi.config.json`:
+- the pack id, from the app's `artifactId`, and its version;
+- the CLI version it pins (`"cli"`, which `./kindgiw` runs, also written);
+- discovery under `kindgi` packages (`src/main/java/**/kindgi/tools/**/*.java`
+  and so on), so the app's own `tools` packages are never taken for
+  Kindgi's.
+
+It leaves `pom.xml` alone, and prints the `com.kindgi:kindgi-pack`
+dependency to add (from Maven Central, at the CLI's version). It also adds
+these skills and `.gitignore` entries. An app with both a `package.json` and
+a `pom.xml` gets a TypeScript pack unless you pass `--template=java`.
+
+A tool there is a class in a `kindgi.tools` package under the app's own
+(`com.acme.app.kindgi.tools`), and calls the app's code directly. A class a
+tool uses must be on the runtime classpath (`compile` or `runtime` scope,
+not `test` or `provided`): the image copies the runtime dependencies only.
+`kindgi dev` reads the app's `.env` and `.env.local`: keys already there
+reach the tools as environment variables.
+
+## Layout of the template
+
+```
+my-pack/
+├── kindgi.config.json                       # "language": "java", the pack's id and version, the CLI it pins
+├── pom.xml                                  # com.kindgi:kindgi-pack, Java 17
+├── mvnw, .mvn/                              # the Maven wrapper
+├── kindgiw, kindgiw.cmd                     # the Kindgi CLI wrapper
+├── src/main/java/mypack/
+│   ├── tools/Echo.java, tools/Greet.java    # Tool.define(...)
+│   ├── guardrails/ResponseNotEmpty.java     # Guardrail.define(...)
+│   ├── agents/EchoAgent.java                # Agent.define(...)
+│   └── flows/EchoFlow.java                  # Flow.define(...)
+├── src/test/java/mypack/ToolsTest.java      # the tools, called directly
+└── .claude/skills/                          # these skills (`./kindgiw skills sync` refreshes them)
+```
+
+The package comes from the pack's id (`my-pack` becomes `mypack`).
+`kindgi.config.json` also takes `discovery`, `dev`, `env`, `environments`,
+`image` and `providers`.
+
+## First run
+
+With `kindgi dev` running, from another terminal in the pack directory:
+
+```sh
+./kindgiw runs start --agent=my-pack.echo-agent --input='{"userMessage":"Ada"}'
+./kindgiw runs start --flow=my-pack.echo-flow --input='{"message":"Ada"}'
+```
+
+The agent's answer comes from `dev-echo`, a **fallback** provider a new pack
+gets: no model, no key. It calls the agent's first tool with
+`{"message": <userMessage>}` 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. It can't fill in any other tool's input,
+and it can't give a typed answer. For a real model, store an LLM provider's
+key and register its preset (Anthropic below; `./kindgiw providers presets`
+lists OpenAI, Gemini, Groq and OpenRouter too):
+
+```sh
+./kindgiw secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt; writes .env.local
+./kindgiw providers register --preset=anthropic
+```
+
+It takes over at the next turn. That registration is in this project's dev
+database only. To have `kindgi dev` register it on every boot, in every
+worktree and after `--reset`, declare it in `kindgi.config.json`:
+`"providers": [{"preset": "anthropic"}]` (its key, `ANTHROPIC_API_KEY`, comes
+from the env files). Details and other providers: `kindgi-authoring-providers`.
+
+To see what Kindgi sees (the index), with no runtime:
+
+```sh
+./mvnw -q compile dependency:build-classpath -Dmdep.outputFile=target/classpath.txt
+java -cp "target/classes:$(cat target/classpath.txt)" com.kindgi.pack.Main index --pack-dir .
+```
+
+## Flows
+
+A flow is data: nodes and edges (`flow.schema.json`). A node's ref may be
+the `Tool` itself:
+
+```java
+public static final Flow FLOW = Flow.define("acme.ledger.record-flow")
+    .version("0.1.0")
+    .toolNode("record", RecordExpense.TOOL)
+    .edge("e-start", "$start", "record")
+    .edge("e-end", "record", "$end")
+    .build();
+```
+
+A node gets the output of its single upstream node (the run input after
+`$start`), or what its `inputMapping` says. Run one with
+`./kindgiw runs start --flow=<id> --input='{…}'`. For branches, loops and
+agent steps, see `kindgi-java-authoring-flows`.
+
+## Calling Kindgi from Java
+
+`com.kindgi:kindgi-client` (on Maven Central, at the same version as the
+CLI) covers the whole API, with typed models and errors:
+
+```java
+Kindgi client = Kindgi.create();   // KINDGI_API_URL + KINDGI_API_TOKEN; in dev, the running kindgi dev
+Run run = client.runs().start(StartRunBody.WithAgent.builder()
+    .agent("my-pack.echo-agent")
+    .input(Map.of("userMessage", "Ada"))
+    .build());
+try (EventStream<RunEvent> events = client.runs().follow(run.id())) {
+  for (RunEvent event : events) System.out.println(event.kind());
+}
+```
+
+The methods follow the API's operations: `approvals.reviewers.list` is
+`client.approvals().reviewers().list()`. `client.async()` has the same ones,
+answering `CompletableFuture`s. A refused call throws a typed
+`KindgiApiException` (`NotFoundException`, …). The client shades its own
+Jackson, so the app's Jackson is left alone. In production it never reads
+`.kindgirc.json`: set `KINDGI_API_URL` and `KINDGI_API_TOKEN`.
+
+## Your app and Kindgi's data
+
+When the app keeps something a run did (a ticket a flow triaged, an answer
+an agent gave), its own row stores the run's id, in a column such as
+`kindgi_run_id`. The app reads the rest through the API, server side:
+
+- **Status, output, timing:** `client.runs().get(runId)`.
+- **The audit, step by step:** `client.runs().journal(runId)`.
+- **What it cost:** `client.cost().records().list(…)`, filtered by the run.
+- **When a run finished:** the `run.finished` webhook, not polling.
+
+Show it in the app's own UI. **Never:**
+
+- **query Kindgi's database**, even on the app's own Postgres server, or map
+  its tables in JPA. Its schema is private and changes with every release,
+  row-level security guards every tenant query, and a runtime Kindgi hosts
+  gives no database access.
+- **link users to Kindgi's console**, or any Kindgi UI, for this data.
+
+Docs: https://docs.kindgi.com/v0.1/guides/runs/show-runs-in-your-app/
+
+## Build an image
+
+`./kindgiw build --env=<name>` builds the pack's image for an
+`environments.<name>` block of `kindgi.config.json`; `--local` builds it with
+this machine's Docker. Maven compiles the pack in a pinned Maven + JDK 17
+image, fetching kindgi-pack from Maven Central. The index is built in the
+image, and the pack service runs on a JRE 17 as its entrypoint, as user
+65532.
+
+Debian packages the code needs are declared in `kindgi.config.json`, and the
+image installs them: `"image": {"systemPackages": ["tesseract-ocr"]}`
+(names, or `name=version`). So are the variables the code reads, names only:
+`"env": {"required": ["DATABASE_URL"], "optional": ["SENTRY_DSN"]}`. A
+deployed pack service missing a required one isn't ready, and its `/readyz`
+names it.
+
+## Two things need the human
+
+- **The pack id and version** in `kindgi.config.json`. The id prefixes every
+  primitive (`<pack-id>.<name>`): pick it once.
+- **Model credentials.** Ask for the key; never invent or hard-code one.
+
+## Next
+
+- A tool: `kindgi-java-authoring-tools`.
+- A guardrail: `kindgi-java-authoring-guardrails`.
+- An agent: `kindgi-java-authoring-agents`.
+- A flow: `kindgi-java-authoring-flows`.
+- A real model: `kindgi-authoring-providers`.
+- An external resource (a database) for the coding agent:
+  `kindgi-authoring-mcp-servers`.
+
+## Keeping skills up to date
+
+`./kindgiw skills sync` refreshes `.claude/skills/` from the CLI's copy
+(local edits are kept unless `--force`). `kindgi dev` says when they are out
+of date.
+
+## When the framework itself is the problem
+
+If the bug is in Kindgi or kindgi-pack and not in the pack's code, load
+`kindgi-framework-feedback` and file it with `./kindgiw feedback write`.

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

@@ -15,7 +15,7 @@ description: >
   model by kindgi-authoring-providers.
 type: core
 library: "kindgi (Python)"
-version: "0.1.4"
+version: "0.1.5"
 sdk_version: "0.0.0"
 pack_languages: [python]
 sources:
@@ -158,7 +158,29 @@ brief_writer = Agent(
   the call. 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.
-- **`retrieval`** — memory retrieval declarations; usually `[]`.
+- **`retrieval`** — what the agent reads from memory before each turn;
+  empty = no memory. Each intent is a dict with the API's keys:
+  `{"types": ["acme.preference"], "scope": "same-user", "mode": "both",
+  "limit": 5}`. `scope` is `same-user`, `same-conversation`,
+  `same-project` or `tenant`; `mode` absent (newest first), `keyword`,
+  `semantic` or `both`. Facts reach the model as data in a `<memory>`
+  block, never as instructions. `semantic`/`both` need embeddings on the
+  runtime (`KINDGI_MEMORY_EMBEDDINGS`); without them a `semantic` intent
+  fails the turn (`semantic-unavailable`). `{"source": "conversations",
+  "scope": "same-user"}` recalls this agent's earlier conversations: the
+  people's own words only, unless `"roles": ["user", "agent"]`.
+  `same-user` memory (facts, recall or `remember`) is the run's end user's:
+  pass `participantId` on every run. A run without one reads and keeps
+  none (its result warns `memory-needs-participant`), never the memory of
+  the user a key acts for, who may serve many people.
+- **`memory`** — `{"remember": {"types": ["acme.preference"], "scope":
+  "same-user", "keepDays": 30}}` gives the turn the built-in tool
+  `kindgi_remember` (name it exactly so in the instructions). The model
+  picks type, text, `key` and expiry, never the scope; a fact wider than
+  one person, or instruction-like text, waits for a person's approval.
+  Use a model with reliable tool calling. `{"instructionTypes":
+  ["acme.policy"]}` makes a retrieved, verified fact of those types an
+  instruction. See https://docs.kindgi.com/v0.1/guides/agents/give-an-agent-memory/.
 
 ## Which model answers
 

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

@@ -14,7 +14,7 @@ description: >
   kindgi-python-authoring-tools.
 type: core
 library: "kindgi (Python)"
-version: "0.1.3"
+version: "0.1.4"
 sdk_version: "0.0.0"
 pack_languages: [python]
 sources:
@@ -121,7 +121,14 @@ def no_fabricated_quotes(config: Config, trace: RunTrace) -> CheckResult:
 - **`config`** — the values the check runs with (above); **`config_type`**
   — the config's type when the check's first parameter isn't annotated
   with it.
-- **`name`** — a display name. **`check_id`** — defaults to the id.
+- **`name`** — a display name. **`check_id`** — defaults to the id. It
+  can't be a built-in check's id (`must-cite`, `never-call-tool`,
+  `max-tool-calls`, `output-matches`, `tool-order`, `required-substring`,
+  `forbidden-substring`): a pack can't replace a built-in, and the
+  decorator raises `DefinitionError`. Name yours
+  `<pack>.checks.<name>`. A Python pack can't use a built-in check yet,
+  since `@guardrail` always decorates a check function: write the rule
+  as your own check.
 - `sandbox=`, `limits=`, `network=` are recorded in the index.
 
 ## Testing

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

@@ -14,7 +14,7 @@ description: >
   kindgi-python-getting-started.
 type: core
 library: "kindgi (Python)"
-version: "0.1.2"
+version: "0.1.3"
 sdk_version: "0.0.0"
 pack_languages: [python]
 sources:
@@ -116,7 +116,19 @@ 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**.
+- `ctx.log` — a logger bound to the call (its records carry the run's ids,
+  the tool's id and the trace id): `ctx.log.info("refund issued",
+  {"orderId": order_id, "amountCents": amount_cents})`, or the fields as
+  keywords. Values go in the fields, never in the message. Log ids,
+  amounts and outcomes, never what a person typed (a refund's reason, a
+  message, an address): the log is read by whoever operates the runtime.
+  `ToolContext.for_test(…)` logs nothing unless you pass it `log=`. Docs:
+  https://docs.kindgi.com/v0.1/guides/tools/write-a-tool/#log-from-a-tool
 
 ## Configuration and secrets
 
@@ -140,6 +152,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 +313,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`.