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

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

@@ -0,0 +1,334 @@
+---
+name: kindgi-java-authoring-tools
+description: >
+  Covers writing tools for a Kindgi pack in Java (`com.kindgi:kindgi-pack`):
+  `Tool.define(id)` as a `public static final` field, input and output
+  schemas from records (Jakarta Validation constraints become keywords) or
+  a JSON Schema map, `handler` and `asyncHandler`, `ToolContext` and
+  cancellation, secrets (`needsSpec`) and configuration, errors,
+  `mutating(false)` and effects, unit tests with `Tool.call`, and wiring a
+  tool onto an agent. Load this whenever you are authoring or editing code
+  in a Java pack's tools packages (a pack whose `kindgi.config.json` says
+  `"language": "java"`), defining a tool, or wiring one onto an agent.
+  Java agents are covered by kindgi-java-authoring-agents, getting started
+  by kindgi-java-getting-started.
+type: core
+library: "kindgi-pack (Java)"
+version: "0.1.0"
+sdk_version: "0.1.5-rc.0"
+pack_languages: [java]
+sources:
+  - sdks/java/kindgi-pack/README.md
+  - sdks/java/kindgi-pack/src/main/java/com/kindgi/pack/Tool.java
+  - sdks/java/kindgi-pack/src/main/java/com/kindgi/pack/ToolContext.java
+---
+
+# Authoring Kindgi tools in Java
+
+> **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>` (`kindgiw.cmd` on
+> Windows). Maven runs as `./mvnw` (or the app's own `mvn`).
+>
+> Java 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 Java pack it is a
+`public static final Tool<I, O>` field of a class in a `tools` package
+(`src/main/java/**/tools/**/*.java`; 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
+
+```java
+// src/main/java/acme/tools/VerifyCitation.java
+package acme.tools;
+
+import com.kindgi.pack.Tool;
+import jakarta.validation.constraints.Pattern;
+import jakarta.validation.constraints.Size;
+import java.io.IOException;
+import java.util.Map;
+import org.jspecify.annotations.Nullable;
+
+/** acme.verify-citation: checks a legal citation against the citator. */
+public final class VerifyCitation {
+  public record Input(
+      @Size(min = 1) String citation,
+      @Pattern(regexp = "^(US|UK|EU)$") String jurisdiction) {}
+
+  public record Output(boolean found, @Nullable String canonicalCite) {}
+
+  public static final Tool<Input, Output> TOOL = Tool.define("acme.verify-citation")
+      .description("Verifies a legal citation against the citator; returns whether it resolves and its canonical form.")
+      .input(Input.class)
+      .output(Output.class)
+      .mutating(false)
+      .set("needsSpec", Map.of("secrets", Map.of("CITATOR_KEY", Map.of("type", "string", "minLength", 20))))
+      .handler((input, ctx) ->
+          verify(input, (String) ctx.secrets().get("CITATOR_KEY"), System.getenv("CITATOR_URL")));
+
+  /** The tool's work, with what it reads from its context and the environment passed in: a test calls it. */
+  public static Output verify(Input input, String key, String citatorUrl) throws IOException, InterruptedException {
+    String hit = Citator.lookup(citatorUrl, key, input.citation(), input.jurisdiction());
+    return new Output(hit != null, hit);
+  }
+
+  private VerifyCitation() {}
+}
+```
+
+```java
+// src/main/java/acme/tools/Citator.java
+package acme.tools;
+
+import java.io.IOException;
+import java.net.URI;
+import java.net.URLEncoder;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.nio.charset.StandardCharsets;
+import org.jspecify.annotations.Nullable;
+
+/** The citator's API. Package-private: a helper, not a primitive. */
+final class Citator {
+  private static final HttpClient HTTP = HttpClient.newHttpClient();
+
+  static @Nullable String lookup(String baseUrl, String key, String citation, String jurisdiction)
+      throws IOException, InterruptedException {
+    String query = "q=" + URLEncoder.encode(citation, StandardCharsets.UTF_8) + "&j=" + jurisdiction;
+    HttpRequest request = HttpRequest.newBuilder(URI.create(baseUrl + "/lookup?" + query))
+        .header("Authorization", "Bearer " + key)
+        .build();
+    HttpResponse<String> response = HTTP.send(request, HttpResponse.BodyHandlers.ofString());
+    return response.statusCode() == 200 ? response.body() : null;
+  }
+
+  private Citator() {}
+}
+```
+
+- **Where it lives:** a `public static final` field of a class in a `tools`
+  package. The indexer loads the class and takes the tools its static fields
+  hold. A tool built in a method, or held by an instance field, is never
+  found.
+- **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 records `input(…)` and `output(…)` name. A record's
+  components are the object's properties, by their Jackson names
+  (`@JsonProperty("canonicalCite")` renames one). Unknown properties are
+  refused unless the type says `@JsonIgnoreProperties(ignoreUnknown = true)`.
+  The input must be an **object**: a model calls a tool with an object of
+  arguments.
+
+  | In Java | In the schema |
+  |---|---|
+  | `String`, `int`/`long`, `double`/`BigDecimal`, `boolean` | `string`, `integer`, `number`, `boolean` |
+  | `@Nullable T`, `Optional<T>` | not required; `null` allowed |
+  | `@JsonProperty(defaultValue = "1")` | `default: 1`, not required; the service fills it in |
+  | `List<T>`, `Set<T>`, `T[]`; `Map<String, T>` | `array`; `object` with `additionalProperties` |
+  | an enum; `UUID`, `Instant`, `LocalDate`, `URI` | `enum`; `string` with its `format` |
+  | `@JsonPropertyDescription` | `description` |
+  | `@Size`, `@Min`, `@Max`, `@Pattern`, `@Email`, `@NotBlank`, `@Positive`, … | the matching keywords |
+
+  A type that can't be a schema (a recursive record, a map with non-string
+  keys) is a file error naming the property. When a type can't say it, pass
+  the schema itself, `input(Map.of("type", "object", …))`, and the handler
+  gets a `Map`.
+- **Handler:** `(input, ctx) -> output`. It may throw. It runs on a thread of
+  its own, so blocking I/O is fine. A handler built on futures uses
+  `asyncHandler((input, ctx) -> stage)` and returns a `CompletionStage`; 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. The handler's thread is interrupted too,
+  so a blocking wait ends. A loop checks `isCancelled()` or calls
+  `throwIfCancelled()`. Work started elsewhere (a request, a job) stops with
+  `onCancel(action)`.
+- `ctx.secrets()`: the secrets the tool declares (below). 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: `System.getenv("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`; `MAVEN_ARGS` and `MAVEN_OPTS` reach Maven
+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: 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 (your app's logger, `System.err`) goes to the pack
+  service's output (`kindgi dev` shows it as `[pack] …`), never into a
+  result.
+
+## Other declarations
+
+**`mutating(false)`** declares a tool read-only: it changes nothing outside
+itself (a lookup, a search, a calculation). A dry run
+(`./kindgiw runs start --dry-run`) runs it. Leave it unset 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`. They are recorded for policy and
+review, so declare what the tool really does.
+
+Java has 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; `new ToolContext(…)` builds one with secrets:
+
+```java
+ToolContext ctx = new ToolContext("t-test", "run-test", null, null, null,
+    Map.of(), Map.of("CITATOR_KEY", "test-key-of-twenty-chars"), Map.of(), Map.of(), new Cancellation());
+Greet.Output out = Greet.TOOL.call(new Greet.Input("Ada", "Hi"), ctx);
+```
+
+A Java test can't set an environment variable, so a handler that reads one
+(`CITATOR_URL`) and calls a service is tested through the method it calls,
+with a stub server:
+
+```java
+// src/test/java/acme/VerifyCitationTest.java
+package acme;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+
+import acme.tools.VerifyCitation;
+import com.sun.net.httpserver.HttpServer;
+import java.net.InetSocketAddress;
+import org.junit.jupiter.api.Test;
+
+class VerifyCitationTest {
+  @Test
+  void anUnknownCitationIsNotFound() throws Exception {
+    HttpServer citator = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0);
+    citator.createContext("/lookup", exchange -> {
+      exchange.sendResponseHeaders(404, -1);
+      exchange.close();
+    });
+    citator.start();
+    try {
+      String url = "http://127.0.0.1:" + citator.getAddress().getPort();
+      assertFalse(VerifyCitation.verify(new VerifyCitation.Input("1 U.S. 1", "US"), "test-key", url).found());
+    } finally {
+      citator.stop(0);
+    }
+  }
+}
+```
+
+`./mvnw test` runs the tests (`*Test.java`, `*IT.java` and anything under
+`src/test/` are never indexed). To see the schemas Kindgi derives:
+
+```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 .
+```
+
+## Wiring the tool onto an agent
+
+Pass the `Tool`, which pins that tool's version:
+
+```java
+Agent.define("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 with Maven, 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 that isn't a `static final` field.** An instance field, a local
+   variable or a method's return value is never indexed.
+3. **A public class in a `tools` package that defines no tool.** It's a file
+   error, so a forgotten `static` can't drop a tool silently. Make a helper
+   package-private, or a record, an enum or an interface.
+4. **No description.** The model can't tell when to call the tool.
+5. **Reading `ctx.env()` or `ctx.config()`, or an undeclared secret.** The
+   first two are empty, and `ctx.secrets()` holds only what `needsSpec`
+   declares. Use `System.getenv` for the rest.
+6. **A non-object input** (`input(String.class)`). The input is a record, a
+   bean, or an object schema.
+7. **A class the tool uses with `test` or `provided` scope.** It works under
+   `kindgi dev` and fails in the image, which copies the runtime classpath
+   only. Use `compile` or `runtime` scope.
+8. **A read-only tool without `mutating(false)`.** A dry run stops at it, and
+   an approval gate asks before it on first use.
+9. **`mutating(false)` on a tool that writes.** A dry run then runs it for
+   real.
+10. **A Jackson module registered only in code, on your own `ObjectMapper`.**
+    kindgi-pack finds modules as `findAndRegisterModules()` does, through
+    `META-INF/services`. Declare it there, or the tool's input and schema
+    won't see it.
+
+## When the framework itself is the problem
+
+If the bug is in Kindgi or kindgi-pack (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-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.1.5-rc.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/dist/sdk-skills/kindgi-python-authoring-agents/SKILL.md

@@ -15,8 +15,8 @@ description: >
   model by kindgi-authoring-providers.
 type: core
 library: "kindgi (Python)"
-version: "0.1.3"
-sdk_version: "0.1.4-rc.5"
+version: "0.1.5"
+sdk_version: "0.1.5-rc.0"
 pack_languages: [python]
 sources:
   - sdks/python/src/kindgi/pack/define.py
@@ -132,9 +132,9 @@ brief_writer = Agent(
   instructions.
 - **`preferred_provider`** / **`preferred_model`** — soft hints: the
   router prefers that provider id (e.g. `"anthropic"`) and/or model name
-  (e.g. `"claude-haiku-4-5"`) when they satisfy the capabilities. To
+  (e.g. `"claude-sonnet-5-5"`) when they satisfy the capabilities. To
   *require* a model, put it in the capability:
-  `{"needs": [{"feature": "tool-use"}, {"models": {"allow": ["claude-haiku-4-5"]}}]}`.
+  `{"needs": [{"feature": "tool-use"}, {"models": {"allow": ["claude-sonnet-5-5"]}}]}`.
 - **`conversation_policy`** — `{"historyLimit": n}` caps the prior
   messages loaded; `hitl` configures approval gates. Absent = the full
   history, no gates. A tenant's `hitl` policy can tighten the gates
@@ -158,7 +158,25 @@ 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"]`.
+- **`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/dist/sdk-skills/kindgi-python-authoring-flows/SKILL.md

@@ -17,7 +17,7 @@ description: >
 type: core
 library: "kindgi (Python)"
 version: "0.1.2"
-sdk_version: "0.1.4-rc.5"
+sdk_version: "0.1.5-rc.0"
 pack_languages: [python]
 sources:
   - sdks/python/src/kindgi/pack/define.py