@kindgi/cli 0.1.4-rc.5 → 0.1.5-rc.0

package/dist/sdk-skills/kindgi-scala-authoring-tools/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: kindgi-scala-authoring-tools
+description: >
+  Covers writing tools for a Kindgi pack in Scala (`kindgi-pack-scala`,
+  `com.kindgi.pack.scaladsl`): `Tool[Input, Output](id)` as a `val` of an
+  object named like its file, schemas from case classes (Option, defaults,
+  collections, Jakarta constraints) or `Tool.json` with maps, `handler` and
+  `handlerAsync` (a Future), `ToolContext` and cancellation, secrets
+  (`needsSpec`) and configuration, errors, `readOnly` and effects, munit
+  tests with `tool.call`, and wiring a tool onto an agent. Load this
+  whenever you are authoring or editing code in a Scala pack's tools
+  packages (a pack whose `kindgi.config.json` says `"language": "scala"`),
+  defining a tool, or wiring one onto an agent. Scala agents are covered by
+  kindgi-scala-authoring-agents, getting started by
+  kindgi-scala-getting-started.
+type: core
+library: "kindgi-pack-scala"
+version: "0.1.0"
+sdk_version: "0.1.5-rc.0"
+pack_languages: [scala]
+sources:
+  - sdks/scala/README.md
+  - sdks/scala/kindgi-pack-scala/src/main/scala/com/kindgi/pack/scaladsl/Tool.scala
+  - sdks/java/kindgi-pack/README.md
+---
+
+# Authoring Kindgi tools 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>`. sbt is the one on
+> your `PATH`.
+>
+> Scala support is in preview: tested and supported, but the API may still
+> change in 0.1.6 without the usual deprecation period.
+
+A **tool** is a unit of work an agent (or a flow step) calls: typed input,
+typed output, your code in between. In a Scala pack it is a `val` of type
+`Tool[I, O]` in an object named like its file (`VerifyCitation.scala` holds
+`object VerifyCitation`), in a `tools` package
+(`src/main/scala/**/tools/**/*.scala`; in an app, `**/kindgi/tools/**`).
+Kindgi runs it in the pack's own JVM (the pack service) and calls it over
+HTTP. The model sees its id, description and input schema.
+
+Before writing one, establish what it should **do**: what it computes or
+fetches, what the caller provides, what it returns. "Add a tool" is a
+conversation opener. The pack's sample tools prove the runtime works; they
+are not the shape to copy unless the user asks.
+
+## A tool
+
+```scala
+// src/main/scala/acme/tools/VerifyCitation.scala
+package acme.tools
+
+import com.kindgi.pack.scaladsl._
+import jakarta.validation.constraints.{Pattern, Size}
+
+/** acme.verify-citation: checks a legal citation against the citator. */
+object VerifyCitation {
+  final case class Input(
+      @Size(min = 1) citation: String,
+      @Pattern(regexp = "^(US|UK|EU)$") jurisdiction: String)
+
+  final case class Output(found: Boolean, canonicalCite: Option[String])
+
+  val tool: Tool[Input, Output] = Tool[Input, Output]("acme.verify-citation")
+    .description("Verifies a legal citation against the citator; returns whether it resolves and its canonical form.")
+    .readOnly
+    .set("needsSpec", Map("secrets" -> Map("CITATOR_KEY" -> Map("type" -> "string", "minLength" -> 20))))
+    .handler((in, ctx) =>
+      verify(in, String.valueOf(ctx.secrets.get("CITATOR_KEY")), sys.env.getOrElse("CITATOR_URL", "")))
+
+  /** The tool's work, with what it reads from its context and the environment passed in: a test calls it. */
+  def verify(in: Input, key: String, citatorUrl: String): Output = {
+    val hit = Citator.lookup(citatorUrl, key, in.citation, in.jurisdiction)
+    Output(hit.isDefined, hit)
+  }
+}
+```
+
+```scala
+// src/main/scala/acme/tools/Citator.scala
+package acme.tools
+
+import java.net.URI
+import java.net.URLEncoder
+import java.net.http.{HttpClient, HttpRequest, HttpResponse}
+import java.nio.charset.StandardCharsets
+
+/** The citator's API: an object with no tools in it is a helper, not a primitive. */
+object Citator {
+  private val http = HttpClient.newHttpClient()
+
+  def lookup(baseUrl: String, key: String, citation: String, jurisdiction: String): Option[String] = {
+    val query = s"q=${URLEncoder.encode(citation, StandardCharsets.UTF_8)}&j=$jurisdiction"
+    val request = HttpRequest.newBuilder(URI.create(s"$baseUrl/lookup?$query"))
+      .header("Authorization", s"Bearer $key")
+      .build()
+    val response = http.send(request, HttpResponse.BodyHandlers.ofString())
+    if (response.statusCode() == 200) Some(response.body()) else None
+  }
+}
+```
+
+- **Where it lives:** a `val` of the object named like the file. The
+  indexer reads the object's vals, and only the primitives that object
+  defined. A tool defined as a `def` or a `lazy val` is a file error that
+  says to make it a `val`: the indexer can't read one without running it.
+  An object with no tools in it is a helper. So is a file with no object
+  (a case class, a trait).
+- **Id:** `<pack-id>.<tool-name>`, kebab-case, dot-namespaced.
+- **Description:** what it does and returns. The model reads it to decide
+  when to call the tool. It isn't enforced, so never leave it out.
+- **Version:** the pack's (`pack.version`), or `.version("1.2.0")` (an exact
+  semver).
+- **Schemas:** from the case classes `Tool[Input, Output]` names. A
+  parameter is a property, by its Jackson name
+  (`@JsonProperty("canonical_cite")` renames one). The input must be an
+  **object**: a model calls a tool with an object of arguments.
+
+  | In Scala | In the schema |
+  |---|---|
+  | `String`, `Int`/`Long`, `Double`/`BigDecimal`, `Boolean`; `BigInt` | `string`, `integer`, `number`, `boolean`; `integer` |
+  | `Option[T]` | not required; `null` allowed |
+  | a parameter's default (`greeting: String = "Hello"`) | `default`, not required; the service fills it in |
+  | `Seq[T]`, `List[T]`, `Vector[T]`; `Set[T]` | `array`; `array` with `uniqueItems` |
+  | `Map[String, T]` | `object` with `additionalProperties` |
+  | a Scala 3 simple enum (`enum Scale { case C, F }`) | `string`, `enum` of its case names |
+  | `@Size`, `@Min`, `@Max`, `@Pattern`, `@Email`, `@NotBlank`, `@Positive`, … | the matching keywords |
+
+  **In Scala 3, name a Java annotation's arguments:** `@Min(value = 0)`, not
+  `@Min(0)`. Scala 3 passes a positional argument to the wrong element.
+  When a type can't say it, `Tool.json(id).inputSchema(Map(…))` takes the
+  schema as Scala maps, and the handler gets a `Map[String, Any]`.
+- **Handler:** `(in, ctx) => output`. It may throw. It runs on a thread of
+  its own, so blocking I/O is fine. `handlerAsync((in, ctx) => future)`
+  returns a `Future[O]`, and the service awaits it.
+- **Validation:** before the handler runs, the input is checked against the
+  schema (its defaults filled in). Then what the handler returns is checked
+  against the output schema. A bad input comes back as
+  `input-validation-failed`, naming the field (a bad output as
+  `output-validation-failed`). The agent's `toolErrors` policy decides
+  whether the model gets to fix the call.
+
+## `ToolContext`
+
+- `ctx.tenantId`: the tenant the call is for. Key per-tenant state by it.
+- `ctx.runId`: the run (an agent turn or a flow step) the call belongs to.
+- `ctx.requestId`: this call, such as the model's tool-call id. Useful for
+  logs and idempotency keys.
+- `ctx.projectId`, `ctx.orgId`: the run's project, and its org (`null` when
+  it has none). The runtime sets them from the run, never from the input.
+  To check an id the input names, compare it with these.
+- `ctx.cancellation` fires when the call's deadline passes (120 s by
+  default) or the caller goes away. A blocking handler's thread is
+  interrupted too. A loop checks `ctx.cancellation.isCancelled`. A `Future`
+  has no way to stop, so stop the work behind it with
+  `ctx.cancellation.onCancel(() => …)`.
+- `ctx.secrets`: the secrets the tool declares (below), as a Java map.
+  Printing the context shows their names, never their values.
+- `ctx.env`, `ctx.config`: **reserved, empty today**.
+
+## Configuration and secrets
+
+A secret that belongs to the tenant, such as an API key a customer gives
+you, is declared with `set("needsSpec", …)` and read from `ctx.secrets`, as
+above. The runtime resolves every declared secret on every call, for the
+call's tenant, in its env (`KINDGI_ENV`; under `kindgi dev`, `local`: the
+pack's `.env` and `.env.local`). It checks each against its schema, and fails
+the call, naming the secret, when one is missing or doesn't match. Every
+declared secret is required.
+
+Everything else comes from the process environment: `sys.env("CITATOR_URL")`.
+Under `kindgi dev`, the pack service gets the pack's `.env` and `.env.local`,
+and restarts when they change. Nothing else from your shell reaches it
+except `PATH`, `HOME` and `TMPDIR`; `SBT_OPTS` reaches sbt only. Put a secret
+there by hand, or with `./kindgiw secrets set NAME --env=local --scope=tenant`
+(a no-echo prompt), and keep the env files out of git. A deployed service
+names the variables it needs in `kindgi.config.json`:
+`"env": {"required": ["DATABASE_URL"], "optional": ["SENTRY_DSN"]}`. Without
+a required one it isn't ready. `KINDGI_*` names are Kindgi's own and never
+reach pack code.
+
+## Errors and output
+
+- Throw for a failure, or fail the `Future`: the call fails with
+  `handler-throw` and the exception's message. In an agent turn, the model
+  sees the failure only when the agent's `toolErrors` policy includes
+  `tool-error`, so retrying must be safe for that tool.
+- What the handler logs goes to the pack service's output (`kindgi dev`
+  shows it as `[pack] …`), never into a result.
+
+## Other declarations
+
+**`readOnly`** declares a tool that changes nothing outside itself (a lookup,
+a search, a calculation): it's `mutating(false)`. A dry run
+(`./kindgiw runs start --dry-run`) runs it. Leave it off for anything that
+writes, sends, charges or deletes: such a tool stops a dry run. It's also
+the tool's approval default: an agent that turns approval gates on
+(`conversationPolicy.hitl`) asks before any tool that isn't read-only on its
+first use.
+
+`effect(kind, resource)` declares a side effect, such as
+`.effect("writes", "db:ledger")`. A dry run also stops at a tool with a
+`writes`, `deletes`, `spawns-run`, `emits-event` or `external-side-effect`
+effect. `set(field, value)` sets the index entry's other fields (`needs`,
+`needsSpec`, `sandbox`, `limits`, `network`), with Scala maps and lists. They
+are recorded for policy and review, so declare what the tool really does.
+
+There is no HTTP-tool form (TypeScript's `kind: 'http'`). A tool that calls
+an HTTP API is a handler with `java.net.http.HttpClient`, as above.
+
+## Testing
+
+`tool.call(input, ctx)` runs the handler with the input as given (no schema
+check). `ToolContext.forTest()` is a context with a test tenant and run and
+nothing else. A handler that reads the environment and calls a service is
+tested through the method it calls, with a stub server:
+
+```scala
+// src/test/scala/acme/VerifyCitationSuite.scala
+package acme
+
+import acme.tools.VerifyCitation
+import com.sun.net.httpserver.HttpServer
+import java.net.InetSocketAddress
+
+class VerifyCitationSuite extends munit.FunSuite {
+  test("an unknown citation is not found") {
+    val citator = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0)
+    citator.createContext("/lookup", exchange => {
+      exchange.sendResponseHeaders(404, -1)
+      exchange.close()
+    })
+    citator.start()
+    try {
+      val url = s"http://127.0.0.1:${citator.getAddress.getPort}"
+      assert(!VerifyCitation.verify(VerifyCitation.Input("1 U.S. 1", "US"), "test-key", url).found)
+    } finally citator.stop(0)
+  }
+}
+```
+
+`sbt test` runs the tests (anything under `src/test/` is never indexed). To
+see the schemas Kindgi derives:
+
+```sh
+java -cp "$(sbt -batch -error 'export Runtime/fullClasspath')" com.kindgi.pack.Main index --pack-dir .
+```
+
+## Wiring the tool onto an agent
+
+Pass the `Tool`, which pins that tool's version:
+
+```scala
+Agent("acme.brief-writer")
+  // …
+  .tool(VerifyCitation.tool)
+```
+
+A tool of another pack is `.tool("other.lookup", "^1.0.0")`: its id and a
+semver **range**, and the highest active version matching it is picked at
+turn start. In a flow, `toolNode("verify", VerifyCitation.tool)` runs it.
+
+## Iterating
+
+Save the file. `kindgi dev` recompiles through sbt's server, and the next
+call runs the new code. A compile error is reported as `file:line:col`, and
+the last good code keeps serving. Bump the version when callers' contract
+changes (a 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. **A tool as a `def` or a `lazy val`.** It's a file error: make it a `val`.
+3. **An object not named like its file.** The indexer reads `Greet.scala`'s
+   `object Greet`, and a file without one is an error.
+4. **No description.** The model can't tell when to call the tool.
+5. **`@Min(0)` in Scala 3.** Name the argument: `@Min(value = 0)`.
+6. **A primitive inside a type parameter** (`Seq[Int]`, `Option[Long]`). On
+   the JVM it's `Object`, so the schema allows any JSON value there. Use a
+   case class (`Seq[Item]`), or say the schema with `Tool.json`.
+7. **Reading `ctx.env` or `ctx.config`, or an undeclared secret.** The first
+   two are empty, and `ctx.secrets` holds only what `needsSpec` declares.
+   Use `sys.env` for the rest.
+8. **A library the tool uses as `% Test` or `% Provided`.** It works under
+   `kindgi dev` and fails in the image, which ships the runtime classpath
+   only.
+9. **A read-only tool without `readOnly`.** A dry run stops at it, and an
+   approval gate asks before it on first use.
+10. **`readOnly` on a tool that writes.** A dry run then runs it for real.
+11. **A jackson-module-scala that doesn't match your app's
+    `jackson-databind` minor version.** It refuses to load: depend on the
+    matching one.
+
+## When the framework itself is the problem
+
+If the bug is in Kindgi, kindgi-pack or the Scala layer (a schema derived
+wrong, a misleading error, the pack service misbehaving) and not in the
+tool's code, load `kindgi-framework-feedback` and file it with
+`./kindgiw feedback write`.

package/dist/sdk-skills/kindgi-scala-getting-started/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: kindgi-scala-getting-started
+description: >
+  Getting a Scala Kindgi pack running: what a pack is, scaffolding one
+  (`kindgi init <name> --template=scala`) or adding Kindgi to an existing
+  sbt app (`kindgi.config.json`, discovery under `kindgi` packages),
+  `./kindgiw dev` through sbt's server, the first agent run, connecting a
+  real model, flows, calling the Kindgi API from Scala, building an image,
+  and the Scala layer's known limits. Load this when an sbt 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 Scala pack
+  (`kindgi.config.json` with `"language": "scala"`) for the first time.
+  Authoring tools, guardrails, agents and flows is covered by
+  kindgi-scala-authoring-tools, kindgi-scala-authoring-guardrails,
+  kindgi-scala-authoring-agents and kindgi-scala-authoring-flows; models by
+  kindgi-authoring-providers.
+type: core
+library: "kindgi-pack-scala"
+version: "0.1.0"
+sdk_version: "0.1.5-rc.0"
+pack_languages: [scala]
+sources:
+  - sdks/scala/README.md
+  - site/src/content/docs/start/quickstart-scala.md
+---
+
+# Getting started with Kindgi in Scala
+
+> **Running `kindgi`:** the pack pins its CLI (`"cli"` in
+> `kindgi.config.json`), and `./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>`. `./kindgiw upgrade`
+> moves the pin, and kindgi-pack-scala's version in `build.sbt` with it.
+>
+> **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": "scala"`). Its primitives are the `val`s
+of an object named like its file (`Greet.scala` holds `object Greet`), in
+four kinds of packages:
+
+- **Tools** (`…/tools/…`, `Tool[Input, Output](id)`): your Scala code an
+  agent or flow calls.
+- **Guardrails** (`…/guardrails/…`, `Guardrail[Config](id)`): checks over an
+  agent's turn.
+- **Agents** (`…/agents/…`, `Agent(id)`): data. Instructions, tools,
+  capabilities. The model runs in Kindgi.
+- **Flows** (`…/flows/…`, `Flow(id)`): data. Steps (tool or agent nodes) and
+  the edges between them.
+
+The Scala layer (`com.kindgi %% kindgi-pack-scala`, package
+`com.kindgi.pack.scaladsl`) is thin, over the Java SDK: kindgi-pack's
+indexer reads the pack, and its pack service runs the tools and checks in
+the pack's own JVM, called over HTTP. Everything else runs in the Kindgi
+runtime. It's built for Scala 2.13 and 3.3. In those packages:
+- An object with no primitives, or a file with no object (a case class, a
+  trait), is a helper.
+- A primitive defined as a `def` or a `lazy val` is an error: make it a
+  `val`.
+- Tests (`src/test/`) are never primitives.
+
+## Scaffold a new pack
+
+You need a JDK 17 or later (`JAVA_HOME`) and sbt.
+
+```sh
+npx --yes @kindgi/cli@0.1 init my-pack --template=scala   # or: uvx --from "kindgi-cli>=0.1,<0.2" kindgi init …
+cd my-pack
+sbt 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 compiles through sbt's server
+(`sbt --client`), so a save compiles in about a second once it's warm.
+- When no sbt server is running, it starts one, and stops it when it stops.
+- A server you already run (your IDE's) is used and left running.
+- A compile error is reported as `file:line:col`, and the last good code
+  keeps serving.
+- It uses `JAVA_HOME`'s JDK (or `dev.javaHome` in `kindgi.config.json`) and
+  the `sbt` on your `PATH` (or `dev.sbt`, such as `["sbt", "-mem", "2048"]`).
+- `SBT_OPTS` reaches sbt, never the pack.
+
+## Add Kindgi to an existing sbt app
+
+In the app's directory (where its `build.sbt` is):
+
+```sh
+npx --yes @kindgi/cli@0.1 init   # --pack-id=<id> if the build's name doesn't make one
+./kindgiw dev
+```
+
+`init` writes `kindgi.config.json`:
+- the pack id, from the build's `name`, and its version;
+- the CLI version it pins (`"cli"`, which `./kindgiw` runs, also written);
+- discovery under `kindgi` packages (`src/main/scala/**/kindgi/tools/**/*.scala`
+  and so on), so the app's own `tools` packages are never taken for
+  Kindgi's.
+
+It leaves `build.sbt` alone, and prints the dependency to add (from Maven
+Central, at the CLI's version):
+
+```scala
+libraryDependencies += "com.kindgi" %% "kindgi-pack-scala" % "…"
+```
+
+It also adds these skills and `.gitignore` entries. An app with a
+`build.sbt` next to a `package.json` or a `pom.xml` gets a TypeScript or Java
+pack unless you pass `--template=scala`.
+
+A tool there is a `val` of an object in a `kindgi.tools` package under the
+app's own (`com.acme.app.kindgi.tools`), and calls the app's code directly. A
+library a tool uses must be on the runtime classpath (not `% Test` or
+`% Provided`): the image ships the runtime classpath 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": "scala", the pack's id and version, the CLI it pins
+├── build.sbt                                # kindgi-pack-scala, Scala 3.3, Java 17
+├── project/build.properties                 # the sbt version
+├── kindgiw, kindgiw.cmd                     # the Kindgi CLI wrapper
+├── src/main/scala/mypack/
+│   ├── tools/Echo.scala, tools/Greet.scala  # Tool[Input, Output](...)
+│   ├── guardrails/ResponseNotEmpty.scala    # Guardrail[Config](...)
+│   ├── agents/EchoAgent.scala               # Agent(...)
+│   └── flows/EchoFlow.scala                 # Flow(...)
+├── src/test/scala/mypack/ToolsSuite.scala   # the tools, called directly (munit)
+└── .claude/skills/                          # these skills (`./kindgiw skills sync` refreshes them)
+```
+
+The package comes from the pack's id, with Java's and Scala's keywords
+escaped (`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
+java -cp "$(sbt -batch -error 'export Runtime/fullClasspath')" 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:
+
+```scala
+val flow: Flow = Flow("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-scala-authoring-flows`.
+
+## Calling Kindgi from Scala
+
+The Java client, `com.kindgi:kindgi-client` (on Maven Central, at the same
+version as the CLI), covers the whole API, with typed models and errors,
+and works from Scala as it is:
+
+```scala
+import com.kindgi.client.Kindgi
+import com.kindgi.client.models.StartRunBody
+import scala.jdk.CollectionConverters._
+
+val client = Kindgi.create()   // KINDGI_API_URL + KINDGI_API_TOKEN; in dev, the running kindgi dev
+val run = client.runs().start(StartRunBody.WithAgent.builder()
+  .agent("my-pack.echo-agent")
+  .input(Map[String, AnyRef]("userMessage" -> "Ada").asJava)
+  .build())
+val events = client.runs().follow(run.id())
+try events.asScala.foreach(event => println(event.kind()))
+finally events.close()
+```
+
+The methods follow the API's operations: `approvals.reviewers.list` is
+`client.approvals().reviewers().list()`. `client.async()` has the same ones,
+answering `CompletableFuture`s (`scala.jdk.FutureConverters` turns them into
+`Future`s). A refused call throws a typed `KindgiApiException`. 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 Slick, Doobie or Quill. 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. sbt builds it in a pinned sbt + JDK 17 image, fetching
+kindgi-pack-scala and kindgi-pack from Maven Central, and copies the runtime
+classpath as jars. 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.
+
+## Known limits
+
+- **Scala's primitives inside a type parameter** (`Seq[Int]`,
+  `Option[Long]`) are `Object` on the JVM, so the schema allows any JSON
+  value there. Use a case class (`Seq[Item]`), or give the schema with
+  `Tool.json`.
+- **In Scala 3, name a Java annotation's arguments:** `@Min(value = 0)`, not
+  `@Min(0)`.
+- **A Scala 3 enum whose cases take parameters** is a sealed hierarchy, not
+  a string: describe it with `@JsonTypeInfo` and `@JsonSubTypes`. A simple
+  enum is a string of its case names.
+- **jackson-module-scala must match your app's `jackson-databind` minor
+  version.** If your app uses a newer Jackson, depend on the matching
+  `jackson-module-scala` yourself.
+
+## 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-scala-authoring-tools`.
+- A guardrail: `kindgi-scala-authoring-guardrails`.
+- An agent: `kindgi-scala-authoring-agents`.
+- A flow: `kindgi-scala-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, kindgi-pack or the Scala layer and not in the
+pack's code, load `kindgi-framework-feedback` and file it with
+`./kindgiw feedback write`.

package/dist/templates/java/.mvn/wrapper/maven-wrapper.properties

@@ -0,0 +1,3 @@
+wrapperVersion=3.3.4
+distributionType=only-script
+distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.16/apache-maven-3.9.16-bin.zip

package/dist/templates/java/AGENTS.md

@@ -0,0 +1,31 @@
+# AGENTS.md
+
+This directory is a Kindgi pack written in Java (`com.kindgi:kindgi-pack`).
+Tools (`Tool.define(...)`) and guardrail checks (`Guardrail.define(...)`) are
+`public static final` fields of classes under `src/main/java/**/tools/` and
+`…/guardrails/`; agents (`Agent.define(...)`) and flows (`Flow.define(...)`) are
+data, under `…/agents/` and `…/flows/`. A tool's input and output schemas come
+from its record types (Jakarta Validation constraints become their keywords). A
+helper class there is package-private, or a record, an enum or an interface.
+The config is `kindgi.config.json`.
+
+- `kindgi dev` boots Kindgi locally, compiles this pack with Maven and runs it
+  with its JDK (17 or later), recompiling on every save.
+- `./mvnw test` runs the tests; `Tool.call(input, ToolContext.forTest())` calls
+  a handler directly.
+- `java -cp "target/classes:$(cat target/classpath.txt)" com.kindgi.pack.Main index --pack-dir .`
+  shows what Kindgi sees, after
+  `./mvnw -q compile dependency:build-classpath -Dmdep.outputFile=target/classpath.txt`.
+- Agents answer through a model provider. `kindgi dev` gives a new pack
+  `dev-echo`, a fallback that isn't a model: it calls the first tool and
+  replies "Tool responded: …" after a warning line, while no other provider
+  fits. For a real model, put one LLM provider's key in `.env`
+  (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY` or
+  `OPENROUTER_API_KEY`) and add a `providers` list with its preset
+  (`[{"preset": "anthropic"}]`, or `"openai"`, `"gemini-api"`, `"groq"`,
+  `"openrouter"`) to `kindgi.config.json`: `kindgi dev` then registers it on
+  every boot, in every worktree.
+
+When you diagnose a framework bug (something in Kindgi itself, not in this
+pack's code), append an entry to `FEEDBACK.md` at the pack root with
+`kindgi feedback write`.