@kindgi/cli 0.1.4 → 0.1.5-rc.0

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

@@ -0,0 +1,209 @@
+---
+name: kindgi-java-authoring-guardrails
+description: >
+  Covers writing guardrails (safety checks on an agent's turn) for a Kindgi
+  pack in Java (`com.kindgi:kindgi-pack`): `Guardrail.define(id)` as a
+  `public static final` field, a `(config, trace)` check returning a
+  `CheckResult`, `RunTrace`, config records and the values a check runs
+  with, actions (halt / retry / escalate / log-only / compensate), severity
+  and scope, unit tests with `evaluate`, and wiring a guardrail onto an
+  agent. Load this whenever you are authoring or editing code in a Java
+  pack's guardrails packages (a pack whose `kindgi.config.json` says
+  `"language": "java"`), defining a check, or wiring a guardrail onto an
+  agent. Java agents are covered by kindgi-java-authoring-agents, Java tools
+  by kindgi-java-authoring-tools.
+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/Guardrail.java
+  - sdks/java/kindgi-pack/src/main/java/com/kindgi/pack/RunTrace.java
+---
+
+# Authoring Kindgi guardrails 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>`. Maven runs as
+> `./mvnw`.
+>
+> Java support is in preview: tested and supported, but the API may still
+> change in 0.1.6 without the usual deprecation period.
+
+A **guardrail** is a rule an agent's turn must satisfy: a **check** (a
+function over the turn's trace) plus an **action** (what happens when it
+fails). In a Java pack it is a `public static final Guardrail<C>` field of a
+class in a `guardrails` package. For an agent turn, the runtime evaluates
+every guardrail the agent lists once, on the final answer, before it is
+stored.
+
+Ask what the rule should catch before writing one. The sample
+`response-not-empty` guardrail is a demonstration, not a template.
+
+## A guardrail
+
+```java
+// src/main/java/acme/guardrails/Citations.java
+package acme.guardrails;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.kindgi.pack.CheckResult;
+import com.kindgi.pack.Guardrail;
+import jakarta.validation.constraints.Min;
+import java.util.Map;
+
+/** acme.no-fabricated-quotes: an answer that quotes case law looked the citations up. */
+public final class Citations {
+  public record Config(@JsonProperty(defaultValue = "1") @Min(0) int minLookups) {}
+
+  public static final Guardrail<Config> NO_FABRICATED_QUOTES = Guardrail.define("acme.no-fabricated-quotes")
+      .name("No fabricated quotations")
+      .onViolation("halt")
+      .severity("critical")
+      .config(Config.class)
+      // What the check runs with, keyed as on the wire.
+      .set("config", Map.of("minLookups", 2))
+      .check((config, trace) -> {
+        long lookups = trace.toolCalls().stream()
+            .map(call -> (Map<?, ?>) call)
+            .filter(call -> "acme.verify-citation".equals(call.get("toolName")))
+            .count();
+        return lookups >= config.minLookups()
+            ? CheckResult.pass()
+            : CheckResult.fail("Only " + lookups + " citation lookups (need " + config.minLookups() + "+).");
+      });
+
+  private Citations() {}
+}
+```
+
+- **The check** is `(config, trace) -> CheckResult`: `CheckResult.pass()`
+  or `CheckResult.fail(reason)`. A failed result's reason is what the
+  violation reports, so make it say what was wrong. A check built on futures
+  uses `asyncCheck` and returns a `CompletionStage<CheckResult>`.
+- **`trace`** is a `RunTrace`:
+  - `output()`: the final answer's text;
+  - `userInput()`;
+  - `toolCalls()`: each a map with `toolId`, `toolName`, `arguments`;
+  - `toolResults()`: each with `toolCallId`, `output`;
+  - `modelCalls()`;
+  - `mode()`: `runtime` or `ci`;
+  - `runId()`, `tenantId()`;
+  - `raw()`: the trace as sent, with any field a newer runtime adds.
+- **`config(Type.class)`** is the config's type. Its schema is derived as a
+  tool input's is, and the service binds the values to it. A
+  `@JsonProperty(defaultValue = …)` is the value when none is given.
+  `configSchema(Map)` gives a schema instead; the config is then a `Map`.
+- **`set("config", Map.of(…))`** holds the values the check runs with,
+  keyed as on the wire. They go into the index, and the service checks them
+  against the schema before every evaluation. Without them the check runs
+  with `{}` and the defaults. So give every field a default: a required
+  field with no value fails every evaluation (`input-validation-failed`).
+- An exception thrown from the check fails the evaluation (`handler-throw`).
+  For a rule that isn't met, return `CheckResult.fail(…)`.
+- A check gets no model and no provider: it can't call an LLM. Keep it a
+  pure function of the trace (fast, deterministic, free).
+
+## `Guardrail.define(id)`
+
+- **`id`:** `<pack-id>.<guardrail-name>`, kebab-case. Name the rule as a
+  positive assertion: `no-fabricated-quotes`, `response-not-empty`.
+- **`onViolation(action)`:** `halt`, `retry`, `escalate`, `log-only` or
+  `compensate`. For one that needs settings, pass the whole object instead,
+  with `action(Map.of("on-violation", "retry", "retry", Map.of("maxAttempts", 2)))`.
+  The same goes for `escalateTo` and `compensateWith` (a tool id). The
+  builder refuses a check with neither.
+  - In an agent turn, a failed `halt` guardrail fails the turn
+    (`guardrail-violation`), and the answer is not stored.
+  - Any other action reports the failure in the turn result's `violations`,
+    and the turn completes.
+  - In 0.1 the runtime acts only on `halt`: `retry`, `escalate` and
+    `compensate` are recorded on the violation, with no second attempt,
+    escalation or compensating call.
+- **`severity`:** `info`, `warn`, `error` (default) or `critical`. It's
+  independent of the action: dashboards group by severity, and execution
+  follows the action.
+- **`set("scope", Map.of("when", "runtime-only"))`:** when the guardrail
+  applies: `always`, `ci-only` or `runtime-only`, narrowed by `agents`,
+  `flows` and `tenants` lists.
+- **`name`:** a display name. **`checkId`:** defaults to the id.
+- **`kind`:** `zero-llm`, the default: a check over the trace, which is what
+  a pack writes.
+- `set("sandbox" | "limits" | "network", …)` are recorded in the index.
+
+## Testing
+
+`evaluate` runs the check with the config as given, with no schema check
+and no defaults. An async check is awaited.
+
+```java
+// src/test/java/acme/CitationsTest.java
+package acme;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import acme.guardrails.Citations;
+import com.kindgi.pack.RunTrace;
+import java.util.List;
+import java.util.Map;
+import org.junit.jupiter.api.Test;
+
+class CitationsTest {
+  @Test
+  void noLookupsFails() throws Exception {
+    RunTrace trace = new RunTrace(Map.of("output", "As held in Smith v. Jones…"));
+    assertFalse(Citations.NO_FABRICATED_QUOTES.evaluate(new Citations.Config(1), trace).passed());
+  }
+
+  @Test
+  void enoughLookupsPass() throws Exception {
+    Map<String, Object> lookup = Map.of("toolName", "acme.verify-citation", "arguments", Map.of());
+    RunTrace trace = new RunTrace(Map.of("toolCalls", List.of(lookup, lookup)));
+    assertTrue(Citations.NO_FABRICATED_QUOTES.evaluate(new Citations.Config(2), trace).passed());
+  }
+}
+```
+
+`new RunTrace(Map)` takes the trace as the runtime sends it, camelCase keys
+included.
+
+## Wiring onto an agent
+
+```java
+Agent.define("acme.brief-writer")
+    // …
+    .guardrail(Citations.NO_FABRICATED_QUOTES)
+```
+
+Pass the `Guardrail`, or its id (`.guardrail("acme.no-fabricated-quotes")`).
+`kindgi dev` registers the pack's guardrails. An agent that names an id with
+no registered guardrail fails the turn before the model is called
+(`Agent "…" references guardrails not in the registry: <id>`).
+
+## Common mistakes
+
+1. **A required config field with no value.** Without `set("config", …)`,
+   the check runs with `{}`. Give the field a default
+   (`@JsonProperty(defaultValue = "1")`), or the guardrail its values.
+2. **`set("config", …)` keyed by Java names.** It's keyed like the wire: the
+   record's Jackson names.
+3. **No `onViolation` or `action`.** The builder refuses the check.
+4. **Expecting another attempt.** `halt` stops the turn, and in 0.1 `retry`
+   doesn't run the turn again: it's only recorded.
+5. **Calling a model from the check.** That isn't available: keep checks
+   pure.
+6. **Throwing for a broken rule.** Return `CheckResult.fail(…)`. An
+   exception is an evaluation error, not a violation.
+7. **A guardrail that isn't a `static final` field**, or a public class in
+   a `guardrails` package that defines none (a file error). A helper there
+   is package-private, or a record, an enum or an interface.
+
+## When the framework itself is the problem
+
+If the bug is in Kindgi or kindgi-pack (a trace field missing, a misleading
+error) and not in the check, load `kindgi-framework-feedback` and file it
+with `./kindgiw feedback write`.

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`.