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

package/dist/client.d.ts

@@ -28,6 +28,8 @@ export { KindgiApiError, fromWire, notImplementedInPreview, notYetWired } from '
 export type { AuthError, ConflictError, GuardrailViolation, GuardrailViolationError, InvalidRequestError, NetworkError, NotFoundError, NotImplementedInPreviewError, NotYetWiredError, RateLimitedError, ServerError, KindgiError, } from '@kindgi/client';
 export { readSse, unwrapSseData } from '@kindgi/client';
 export type { SseEvent, SseReadOptions } from '@kindgi/client';
+export { verifySignedExport } from '@kindgi/client';
+export type { ExportSigningKey, SignedExportEnvelope, SignedExportVerification, VerifySignedExportOptions, } from '@kindgi/client';
 export { followRun, subscribeToRun } from '@kindgi/client';
 export type { FollowRunOptions, RunProgress, RunProgressEvent, SubscribeToRunOptions, } from '@kindgi/client';
 export { comparisonOf } from '@kindgi/client';

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAIlE,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,OAAO,CAAC,aAAa,CAAM,GAAG,YAAY,CAE/E;AAGD,YAAY,EACV,qBAAqB,EACrB,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,cAAc,EACd,eAAe,EACf,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,UAAU,EACV,WAAW,EACX,mBAAmB,EACnB,YAAY,EACZ,WAAW,EACX,UAAU,EACV,WAAW,EACX,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,UAAU,EACV,SAAS,EACT,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,kBAAkB,EAClB,UAAU,EACV,UAAU,EACV,WAAW,EACX,UAAU,EACV,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,qBAAqB,EACrB,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,cAAc,EACd,cAAc,EACd,eAAe,EACf,qBAAqB,EACrB,GAAG,EACH,UAAU,EACV,eAAe,EACf,cAAc,EACd,aAAa,EACb,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,YAAY,EACZ,kBAAkB,EAClB,WAAW,EACX,YAAY,EACZ,0BAA0B,EAC1B,UAAU,EACV,iBAAiB,EACjB,WAAW,EACX,SAAS,EACT,gBAAgB,EAChB,WAAW,EACX,iBAAiB,EACjB,UAAU,EACV,WAAW,EACX,cAAc,EACd,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,uBAAuB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAChG,YAAY,EACV,SAAS,EACT,aAAa,EACb,kBAAkB,EAClB,uBAAuB,EACvB,mBAAmB,EACnB,YAAY,EACZ,aAAa,EACb,4BAA4B,EAC5B,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,WAAW,GACZ,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACxD,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAG/D,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,YAAY,EACV,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAIlE,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,OAAO,CAAC,aAAa,CAAM,GAAG,YAAY,CAE/E;AAGD,YAAY,EACV,qBAAqB,EACrB,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,cAAc,EACd,eAAe,EACf,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,UAAU,EACV,WAAW,EACX,mBAAmB,EACnB,YAAY,EACZ,WAAW,EACX,UAAU,EACV,WAAW,EACX,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,UAAU,EACV,SAAS,EACT,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,kBAAkB,EAClB,UAAU,EACV,UAAU,EACV,WAAW,EACX,UAAU,EACV,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,qBAAqB,EACrB,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,cAAc,EACd,cAAc,EACd,eAAe,EACf,qBAAqB,EACrB,GAAG,EACH,UAAU,EACV,eAAe,EACf,cAAc,EACd,aAAa,EACb,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,YAAY,EACZ,kBAAkB,EAClB,WAAW,EACX,YAAY,EACZ,0BAA0B,EAC1B,UAAU,EACV,iBAAiB,EACjB,WAAW,EACX,SAAS,EACT,gBAAgB,EAChB,WAAW,EACX,iBAAiB,EACjB,UAAU,EACV,WAAW,EACX,cAAc,EACd,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,uBAAuB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAChG,YAAY,EACV,SAAS,EACT,aAAa,EACb,kBAAkB,EAClB,uBAAuB,EACvB,mBAAmB,EACnB,YAAY,EACZ,aAAa,EACb,4BAA4B,EAC5B,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,WAAW,GACZ,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACxD,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAG/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,YAAY,EACV,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,gBAAgB,CAAC"}

package/dist/client.js

@@ -50,6 +50,8 @@ export function createClient(options = {}) {
 export { KindgiApiError, fromWire, notImplementedInPreview, notYetWired } from '@kindgi/client';
 // ---- Streaming helpers (SSE parser + resume) ----
 export { readSse, unwrapSseData } from '@kindgi/client';
+// ---- Signed exports: check one where it's read ----
+export { verifySignedExport } from '@kindgi/client';
 // ---- Following a run (browser-safe: a page follows a run with a public token) ----
 export { followRun, subscribeToRun } from '@kindgi/client';
 // ---- Comparisons (a test set compared with a version): the typed result ----

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC;;;;;;;;;;;;;;;;;GAiBG;AAEH,6CAA6C;AAC7C,OAAO,EAAE,YAAY,IAAI,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAGpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAI3D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,YAAY,CAAC,UAAkC,EAAE;IAC/D,OAAO,kBAAkB,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC,CAAC;AAC3D,CAAC;AA8FD,0BAA0B;AAC1B,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,uBAAuB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAgBhG,oDAAoD;AACpD,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGxD,qFAAqF;AACrF,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAQ3D,+EAA+E;AAC/E,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC;;;;;;;;;;;;;;;;;GAiBG;AAEH,6CAA6C;AAC7C,OAAO,EAAE,YAAY,IAAI,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAGpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAI3D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,YAAY,CAAC,UAAkC,EAAE;IAC/D,OAAO,kBAAkB,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC,CAAC;AAC3D,CAAC;AA8FD,0BAA0B;AAC1B,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,uBAAuB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAgBhG,oDAAoD;AACpD,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGxD,sDAAsD;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAQpD,qFAAqF;AACrF,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAQ3D,+EAA+E;AAC/E,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindgi/sdk",
-  "version": "0.1.4-rc.5",
+  "version": "0.1.5-rc.0",
   "description": "@kindgi/sdk — the authoring SDK for Kindgi™. Facade over the individual @kindgi/* packages + @kindgi/client. Unifies pack authoring (defineTool / defineCheck / defineAgent / defineFlow) and client callsites (createClient) behind three sub-paths: /define, /client, /types. Re-export facade; zero behavior.",
   "license": "Apache-2.0",
   "repository": {
@@ -55,15 +55,15 @@
     "README.md"
   ],
   "dependencies": {
-    "@kindgi/agents": "0.1.4-rc.5",
-    "@kindgi/client": "0.1.4-rc.5",
-    "@kindgi/crypto": "0.1.4-rc.5",
-    "@kindgi/flow": "0.1.4-rc.5",
-    "@kindgi/guardrails": "0.1.4-rc.5",
-    "@kindgi/handler-runtime": "0.1.4-rc.5",
-    "@kindgi/schema": "0.1.4-rc.5",
-    "@kindgi/tools": "0.1.4-rc.5",
-    "@kindgi/types": "0.1.4-rc.5"
+    "@kindgi/agents": "0.1.5-rc.0",
+    "@kindgi/client": "0.1.5-rc.0",
+    "@kindgi/crypto": "0.1.5-rc.0",
+    "@kindgi/flow": "0.1.5-rc.0",
+    "@kindgi/guardrails": "0.1.5-rc.0",
+    "@kindgi/handler-runtime": "0.1.5-rc.0",
+    "@kindgi/schema": "0.1.5-rc.0",
+    "@kindgi/tools": "0.1.5-rc.0",
+    "@kindgi/types": "0.1.5-rc.0"
   },
   "peerDependencies": {
     "zod": "^4.0.0"

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

@@ -12,7 +12,7 @@ description: >
   kindgi-authoring-guardrails.
 type: core
 library: "@kindgi/sdk"
-version: "0.4.3"
+version: "0.4.5"
 sdk_version: "0.0.0"
 pack_languages: [node]
 sources:
@@ -125,10 +125,10 @@ export default defined.value;
   capability-based selection when the preferred provider is
   unregistered or filtered out.
 - **`preferredModel`** — optional soft hint at the model level: set to
-  a `ModelInfo.name` (e.g. `'gemini-2.5-pro'`), the router prefers
+  a `ModelInfo.name` (e.g. `'gemini-3.8-flash'`), the router prefers
   `(provider, model)` tuples whose model matches. To require a model
   rather than prefer it, add a hard requirement to the capability:
-  `capabilities: [{ needs: [{ feature: 'tool-use' }, { models: { allow: ['gemini-2.5-pro'] } }] }]`.
+  `capabilities: [{ needs: [{ feature: 'tool-use' }, { models: { allow: ['gemini-3.8-flash'] } }] }]`.
 - **`conversationPolicy`** — optional. Absent = each turn loads the
   conversation's full history and no HITL gates apply. `historyLimit`
   caps how many prior messages are loaded; `hitl` configures approval
@@ -160,6 +160,30 @@ export default defined.value;
   retries the turn fails as before, with `toolRetries` on the error. A
   tenant's `tool-errors` policy can lower these (fewer retries, fewer
   kinds), never raise them.
+- **`retrieval`** — what the agent reads from memory before each turn.
+  Empty = no memory. Each intent is
+  `{ types: ['acme.preference'], scope, mode?, limit? }`, with `scope`
+  one of `'same-user'`, `'same-conversation'`, `'same-project'`,
+  `'tenant'` (always within what the run may see), and `mode` absent
+  (newest first), `'keyword'`, `'semantic'` or `'both'`. Retrieved 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']` (its own earlier
+  answers come back marked unverified). `same-segment`/`same-project`
+  recall other people's conversations, and publishing warns.
+- **`memory`** — `{ remember: { types, scope, keepDays? } }` gives the
+  turn the built-in tool `kindgi_remember` (name it exactly so in the
+  instructions; built-ins have no dots). The model picks the type, the
+  text, an optional `key` and an expiry; never the scope. A fact wider
+  than one person, or text that reads like an instruction, waits for a
+  person's approval. Remembering is a tool call, so use a model with
+  reliable tool calling. `{ instructionTypes: ['acme.policy'] }` turns a
+  retrieved, verified fact of those types into an instruction
+  ("Policies (verified)"). See
+  https://docs.kindgi.com/v0.1/guides/agents/give-an-agent-memory/.
 
 ## What a turn receives
 

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

@@ -15,7 +15,7 @@ description: >
   kindgi-authoring-agents.
 type: core
 library: "@kindgi/sdk"
-version: "0.3.6"
+version: "0.3.8"
 sdk_version: "0.0.0"
 pack_languages: [node]
 sources:
@@ -55,7 +55,11 @@ before the response is stored.
 - **Built-in checks** (`BUILT_IN_CHECK_IDS` in `@kindgi/guardrails`):
   `must-cite`, `never-call-tool`, `max-tool-calls`, `output-matches`,
   `tool-order`, `required-substring`, `forbidden-substring`. A guardrail
-  can name one of these instead of shipping its own check.
+  can name one of these (`check: 'forbidden-substring'`) instead of
+  shipping its own check, and the runtime runs the built-in. Their ids
+  are reserved: a pack that ships its own check under one is refused
+  (`reserved-check-id`), so name yours `<pack>.checks.<name>`. See
+  "Using a built-in check" below for each one's `config`.
 
 `@kindgi/sdk` exports `defineCheck` but no helper for the guardrail
 itself: a pack file default-exports the declaration as a plain object.
@@ -119,6 +123,46 @@ How the pack tooling reads this file:
   declares no config gets them all), and a config that doesn't fit
   refused, naming where.
 
+## Using a built-in check
+
+Name the built-in as the guardrail's `check`, give its `config`, and ship
+no check implementation:
+
+```ts
+// guardrails/no-guarantees/index.ts
+export default {
+  id: 'acme.no-guarantees',
+  name: 'Never promise a guarantee',
+  kind: 'zero-llm',
+  check: 'forbidden-substring',
+  config: { patterns: ['guaranteed', 'we promise'] },
+  action: { 'on-violation': 'halt' },
+  severity: 'error',
+};
+```
+
+Each built-in's `config` (tool lists hold tool ids, as in
+`acme.fetch-precedent`; a setting without `?` is required):
+
+| Check | Fails when | `config` |
+| --- | --- | --- |
+| `must-cite` | the answer is empty, or has fewer than `minCitations` matches of `sourcePattern` | `minCitations?: integer ≥ 1` (1), `sourcePattern?: string` (a regex; `[…]`-style citations by default) |
+| `never-call-tool` | the turn called any tool in `tools` | `tools: (string \| { id, version? })[]`, one or more |
+| `max-tool-calls` | the turn made more than `max` tool calls | `max?: integer ≥ 0` (10) |
+| `output-matches` | the answer doesn't match `pattern` (with `negate: true`, it does) | `pattern: string` (a regex), `flags?: string` (letters `dgimsuyv`), `negate?: boolean` |
+| `tool-order` | the tools in `sequence` weren't called in that order (others may come between) | `sequence: string[]`, one or more |
+| `required-substring` | the answer is empty, or lacks any of `patterns` | `patterns: string[]`, one or more non-empty (plain text), `caseSensitive?: boolean` (false) |
+| `forbidden-substring` | the answer contains any of `patterns` | `patterns: string[]`, one or more non-empty (plain text), `caseSensitive?: boolean` (false) |
+
+A config the check doesn't take is refused: a required setting left out,
+the wrong type, a setting the check doesn't know, or a regex that doesn't
+compile. Registering it answers `422 guardrail-config-invalid` (each
+problem in `details.issues`); deploying a pack with one fails with
+`deployment-validation-failed`; one that still reaches a turn is a check
+that can't run (`invalid-check-config`), so a `halt` guardrail stops the
+turn. Each built-in's JSON Schema is its registered check's
+`configSchema`.
+
 ## Validating a declaration in-process
 
 `defineGuardrail(spec, checks)` from `@kindgi/guardrails` validates a

package/skills/kindgi-authoring-mcp-servers/SKILL.md

@@ -17,9 +17,9 @@ description: >
   `kindgi secrets set` flow.
 type: core
 library: "@kindgi/sdk"
-version: "0.3.0"
+version: "0.3.2"
 sdk_version: "0.0.0"
-pack_languages: [node, python]
+pack_languages: [node, python, java, scala]
 ---
 
 # Wiring an MCP server for a Kindgi pack
@@ -28,7 +28,8 @@ pack_languages: [node, python]
 > (`@kindgi/cli`), not a global command. Run it through the project's
 > package manager — `pnpm exec kindgi …`, `npx --no kindgi …` (npm),
 > `yarn kindgi …` or `bun run kindgi …`. A Python pack (`[tool.kindgi]` in
-> `pyproject.toml`) has no Node project: run the `kindgi` on `PATH`.
+> `pyproject.toml`) has no Node project: run the `kindgi` on `PATH`. A Java
+> or Scala pack (`kindgi.config.json`) runs the CLI it pins: `./kindgiw …`.
 > Commands below are written `kindgi …` for brevity.
 
 If the user has an external resource (Postgres DB, GitHub org, Notion
@@ -89,7 +90,8 @@ Three moving parts:
    (`"command": "pnpm", "args": ["exec", "kindgi", "mcp-launch", …]`;
    npm: `npx --no kindgi …`) — never a global `kindgi`, never a
    download. A Python pack has no Node project, so its entries run the
-   `kindgi` on `PATH` (`"command": "kindgi", "args": ["mcp-launch", …]`).
+   `kindgi` on `PATH` (`"command": "kindgi", "args": ["mcp-launch", …]`). A
+   Java or Scala pack's run the CLI it pins (`"command": "./kindgiw"`).
    The file is safe to commit — it references secrets by NAME, not
    value.
 3. **The launcher** — `kindgi mcp-launch` is what the coding agent

package/skills/kindgi-authoring-providers/SKILL.md

@@ -5,8 +5,9 @@ description: >
   can actually call a real model. Covers four paths — hosted via
   Anthropic native adapter, Gemini on Vertex AI (Google Application
   Default Credentials, no API key), hosted via the OpenAI-compat adapter
-  (works with OpenAI + Groq + Together + Fireworks + OpenRouter +
-  Ollama + vLLM + any other OpenAI-compatible endpoint), and local
+  (works with OpenAI, Groq, self-hosted vLLM and Ollama, and any other
+  OpenAI-compatible endpoint, a hosted gateway such as OpenRouter
+  included), and local
   via the in-process ONNX adapter — plus the credential flow (in
   `kindgi dev` the key lives in the project's env files — `.env`, then
   `.env.local` — added by hand or with `kindgi secrets set`'s no-echo
@@ -22,9 +23,9 @@ description: >
   kindgi-getting-started.
 type: core
 library: "@kindgi/sdk"
-version: "0.9.5"
+version: "0.9.11"
 sdk_version: "0.0.0"
-pack_languages: [node, python]
+pack_languages: [node, python, java, scala]
 sources:
   - packages/adapters/model-anthropic/src/provider.ts
   - packages/adapters/model-gemini/src/provider.ts
@@ -40,7 +41,8 @@ sources:
 > (`@kindgi/cli`), not a global command. Run it through the project's
 > package manager — `pnpm exec kindgi …`, `npx --no kindgi …` (npm),
 > `yarn kindgi …` or `bun run kindgi …`. A Python pack (`[tool.kindgi]` in
-> `pyproject.toml`) has no Node project: run the `kindgi` on `PATH`.
+> `pyproject.toml`) has no Node project: run the `kindgi` on `PATH`. A Java
+> or Scala pack (`kindgi.config.json`) runs the CLI it pins: `./kindgiw …`.
 > Commands below are written `kindgi …` for brevity.
 
 An **agent** is a versioned declaration; it needs a **provider** to run.
@@ -75,8 +77,9 @@ Three moving parts:
 1. **API key on disk** — in `kindgi dev` (environment `local`) the dotenv
    secret binding reads the project's own env files: `.env`, then
    `.env.local` on top (change the list with `dev.envFiles` in
-   `kindgi.config.ts`, or `envFiles` under `[tool.kindgi.dev]` in a Python
-   pack's `pyproject.toml`). A key already in the app's `.env` just works.
+   `kindgi.config.ts`, `envFiles` under `[tool.kindgi.dev]` in a Python
+   pack's `pyproject.toml`, or `dev.envFiles` in a Java or Scala pack's
+   `kindgi.config.json`). A key already in the app's `.env` just works.
    `kindgi secrets set` (interactive, no-echo) writes `.env.local`. For
    non-sensitive values (log levels, region names, feature flags),
    `kindgi env set NAME VALUE --env=local` writes the same file with a
@@ -106,7 +109,11 @@ yours.
 ## Path A — Hosted, native Anthropic
 
 Best fidelity to Anthropic's API (prompt caching, latest models, tool
-use, structured output). Requires an `ANTHROPIC_API_KEY`.
+use). Requires an `ANTHROPIC_API_KEY`.
+
+A model's `structured-output` feature is a routing label: the model can
+follow a JSON schema natively, but Kindgi's typed outputs use instructions,
+then parse, check against the schema and repair, on every provider.
 
 **Step 1 — set the key:**
 ```sh
@@ -123,9 +130,19 @@ credential on argv.
 
 **Step 2 — register it, from the preset:**
 ```sh
-kindgi providers register --preset=anthropic                          # Opus 5.5, Sonnet 5.5, Haiku 4.5
-kindgi providers register --preset=anthropic --models=claude-haiku-4-5  # just one
+kindgi providers register --preset=anthropic                          # Opus 5.5, Sonnet 5.5 (default), Haiku 5.5, Haiku 4.5
+kindgi providers register --preset=anthropic --models=claude-sonnet-5-5  # just one
 ```
+Before pinning a Claude model, check its status on Anthropic's model
+deprecations page (https://platform.claude.com/docs/en/about-claude/model-deprecations): a turn routed to a retired model fails. Prefer the
+preset's default. Each
+preset names a default model (`metadata.defaultModel`, marked `(default)`
+when it registers), which an agent with no preference gets. A preset
+registered before 0.1.4 has none: unregister it and register it again.
+The Claude 5.5 and GPT-6 models take no `temperature` (`"sampling": false`:
+the call goes without it, with a `sampling-unsupported` warning), and a
+model's `thinking` says how it thinks; thinking counts against
+`maxOutputTokens` and bills as output.
 The preset carries the models, context windows, output limits and current
 prices (`kindgi providers presets` lists the presets and when their prices
 were checked); `--max-output-tokens=<n>` sets another output limit. In a pack it refuses until the key is in the pack's env files —
@@ -139,8 +156,8 @@ needs under `kindgi dev`:
 ```ts
 // in kindgi.config.ts
 providers: [
-  { preset: 'anthropic', models: ['claude-haiku-4-5'] },   // key ANTHROPIC_API_KEY, from the env files
-  { preset: 'gemini', project: 'acme-gcp', models: ['gemini-2.5-flash'] },
+  { preset: 'anthropic', models: ['claude-sonnet-5-5'] },  // key ANTHROPIC_API_KEY, from the env files
+  { preset: 'gemini', project: 'acme-gcp', models: ['gemini-3.8-flash'] },
   { spec: { /* the provider.json body below */ } },
 ],
 ```
@@ -148,14 +165,17 @@ providers: [
 # in pyproject.toml: one table per provider, same keys
 [[tool.kindgi.providers]]
 preset = "anthropic"
-models = ["claude-haiku-4-5"]
+models = ["claude-sonnet-5-5"]
 ```
+In a Java or Scala pack's `kindgi.config.json`, the same keys:
+`"providers": [{"preset": "anthropic", "models": ["claude-sonnet-5-5"]}]`.
 - A preset entry takes `models`, `project`, `secret` (the key's name, in place
-  of the preset's) and `maxOutputTokens`, spelled the same in `pyproject.toml`;
+  of the preset's) and `maxOutputTokens`, spelled the same in `pyproject.toml`
+  and `kindgi.config.json`;
   a `spec` entry is a `--spec` body. A
   key is always a secret's name (`secret_ref`); a credential in
   `adapter_config` is refused.
-- Each boot prints `Providers from kindgi.config.ts:` with one line each:
+- Each boot prints `Providers from kindgi.config.ts:` (the pack's config file) with one line each:
   `registered`, `unchanged`, `registered again (changed in kindgi.config.ts)`,
   `unregistered (no longer in kindgi.config.ts)`, or ⚠ `not registered: <KEY>
   is not in .env, .env.local` (set the key, then restart: the config isn't
@@ -167,7 +187,7 @@ models = ["claude-haiku-4-5"]
   providers with `kindgi providers register`.
 
 **Step 2 (by hand) — write `provider.json`** at the pack root. One connection,
-three models — matches how the Anthropic SDK actually works (the API
+two models — matches how the Anthropic SDK actually works (the API
 key is per-vendor; the model is per-call):
 ```json
 {
@@ -194,16 +214,6 @@ key is per-vendor; the model is per-call):
           "completionUsdPer1kTokens": 0.01
         },
         "description": "Balanced performance/cost."
-      },
-      {
-        "name": "claude-haiku-4-5",
-        "contextWindow": 200000,
-        "features": ["tool-use"],
-        "cost": {
-          "promptUsdPer1kTokens": 0.001,
-          "completionUsdPer1kTokens": 0.005
-        },
-        "description": "Fastest and cheapest — routing, classification, simple calls."
       }
     ],
     "description": "Anthropic Claude via native adapter."
@@ -261,9 +271,9 @@ Works with **any** OpenAI-compatible endpoint. Same adapter, different
 | Groq | `https://api.groq.com/openai/v1` |
 | Together | `https://api.together.xyz/v1` |
 | Fireworks | `https://api.fireworks.ai/inference/v1` |
-| OpenRouter | `https://openrouter.ai/api/v1` |
 | DeepSeek | `https://api.deepseek.com/v1` |
 | LiteLLM proxy | `http://localhost:4000/v1` |
+| OpenRouter (a hosted gateway) | `https://openrouter.ai/api/v1` |
 
 The connection carries the `baseURL` (in `adapter_config`);
 each endpoint is a separate provider row because each has its own API
@@ -485,24 +495,16 @@ outside Google Cloud: put a service-account key (its JSON) in a secret
     "region": "global",
     "models": [
       {
-        "name": "gemini-2.5-pro",
+        "name": "gemini-3.8-flash",
         "contextWindow": 1048576,
-        "features": ["tool-use"],
+        "features": ["tool-use", "structured-output", "long-context"],
         "maxOutputTokens": 65536,
-        "cost": {
-          "promptUsdPer1kTokens": 0.00125,
-          "completionUsdPer1kTokens": 0.01,
-          "longContext": {
-            "thresholdTokens": 200000,
-            "promptUsdPer1kTokens": 0.0025,
-            "completionUsdPer1kTokens": 0.015
-          }
-        }
+        "cost": { "promptUsdPer1kTokens": 0.00075, "completionUsdPer1kTokens": 0.00375 }
       },
       {
-        "name": "gemini-2.5-flash",
+        "name": "gemini-3.5-flash-lite",
         "contextWindow": 1048576,
-        "features": ["tool-use"],
+        "features": ["tool-use", "structured-output", "long-context"],
         "maxOutputTokens": 65536,
         "cost": { "promptUsdPer1kTokens": 0.0003, "completionUsdPer1kTokens": 0.0025 }
       }
@@ -517,11 +519,17 @@ outside Google Cloud: put a service-account key (its JSON) in a secret
 - `metadata.region` is the Vertex location: `global`, or a region such as
   `us-central1` or `northamerica-northeast1` when data must stay in one
   place. `unspecified` means `global`. Different locations are different
-  provider rows.
+  provider rows. Check that the location serves the model: Gemini 3.8 Flash
+  isn't served from `us-central1`.
+- Don't register `gemini-2.5-pro` or `gemini-2.5-flash`: Vertex AI retires
+  both on 2026-10-20.
 - Rates are per 1K tokens, from Google's published pricing; check them
-  before relying on budgets. Thinking tokens bill as output.
-  `longContext` switches the whole call to the higher rates past the
-  threshold; `cachedPromptMultiplier` (default 0.25) prices cached
+  before relying on budgets. Thinking tokens bill as output, and Gemini 3.8
+  Flash thinks by default. `gemini-3.8-flash`'s rates above are Google's
+  launch price, through 2026-12-31 ($0.0015 / $0.0075 from 2027-01-01).
+  `longContext` (`{ thresholdTokens, promptUsdPer1kTokens,
+  completionUsdPer1kTokens }` in a model's `cost`) switches the whole call
+  to the higher rates past the threshold; `cachedPromptMultiplier` (default 0.25) prices cached
   prompt tokens.
 
 **Step 3 — register and check:**
@@ -533,7 +541,8 @@ Or skip step 2: `kindgi providers register --preset=gemini --project=<your-gcp-p
 registers both models above.
 Then pin it from an agent with `preferredProvider: 'gemini'` (and a model
 with `preferredModel`; in Python, `preferred_provider="gemini"` and
-`preferred_model=…`), or let the router pick by capability.
+`preferred_model=…`; in Java, `.set("preferredProvider", "gemini")`), or let
+the router pick by capability.
 
 ## How the router picks between multiple providers + models
 
@@ -548,13 +557,16 @@ tenant policy), then sorts survivors in this order:
      - Only `preferredModel` set → promote any provider exposing that model.
      - Only `preferredProvider` set → promote every model of that provider.
    `defineAgent` takes both (`preferredProvider`, `preferredModel`), and
-   so does a Python `Agent` (`preferred_provider=`, `preferred_model=`).
+   so does a Python `Agent` (`preferred_provider=`, `preferred_model=`) and
+   a Java `Agent.define(…)` (`set("preferredProvider", …)`).
 2. **`capability.prefer[]` weights.** If the agent's capability
    declares `prefer: [{feature: 'thinking', weight: 3}, ...]`, tuples
    with matching model features (or provider attributes) get higher
    scores. Sorted by summed score, descending.
-3. **Deterministic lexical tiebreak.** When scores tie, tuples sort by
-   `(providerId, modelName)` alphabetically — replay-safe and stable.
+3. **Deterministic tiebreak.** When scores tie, tuples sort by provider
+   id, then the provider's `defaultModel` before its other models, then
+   model name — replay-safe and stable. A provider without a
+   `defaultModel` falls back to its first model by name.
 
 **Practical rule:** preferences are soft — they rank, they don't
 exclude. To guarantee which model runs, make it a hard requirement in
@@ -645,7 +657,8 @@ defineAgent({
    be the FULL npm package name of the adapter — `"@kindgi/adapter-model-anthropic"`,
    NOT `"anthropic"`. Adapters are registered with the runtime under
    their full package names, and a short name matches none of them, so
-   the registration fails. The model adapters are
+   registering is refused: the runtime has no adapter by that name
+   (`✗ /adapter_id: …`). The model adapters are
    `@kindgi/adapter-model-anthropic`, `@kindgi/adapter-model-gemini`,
    `@kindgi/adapter-model-openai-compat` and
    `@kindgi/adapter-model-in-process`; `kindgi providers presets` shows
@@ -682,8 +695,9 @@ defineAgent({
    Then re-register.
 
 6. **Key not found by the runtime.** `kindgi dev` reads the env files
-   at the PACK ROOT (the directory with `kindgi.config.ts`, or a Python
-   pack's `pyproject.toml` with `[tool.kindgi]`) — `.env` and
+   at the PACK ROOT (the directory with `kindgi.config.ts`, a Python
+   pack's `pyproject.toml` with `[tool.kindgi]`, or a Java or Scala pack's
+   `kindgi.config.json`) — `.env` and
    `.env.local`, or whatever `dev.envFiles` lists; the boot log prints
    which files it found. A `KINDGI_`-prefixed name is Kindgi runtime
    config and never resolves as a secret. Outside `kindgi dev`, the
@@ -712,6 +726,21 @@ defineAgent({
    that names nothing registered, and the tenant's policy. `kindgi
    providers list` shows what is registered.
 
+10. **A setting the adapter can't use.** Registering checks the spec
+    against its adapter (no network call, no key read) and refuses what
+    it can't use: `422 provider-config-invalid`, nothing stored, one line
+    per problem with its JSON-pointer path:
+    ```text
+    Error [invalid-request]: Provider "ollama" doesn't fit adapter @kindgi/adapter-model-openai-compat: adapter_config.api must be one of responses, chat-completions.
+      ✗ /adapter_config/api: adapter_config.api must be one of responses, chat-completions.
+    ```
+    Fix each `✗` line's setting and register again. A key the adapter
+    needs is checked too (`✗ /secret_ref: …`); whether the key works, or
+    the endpoint answers, isn't (the first turn finds out). A
+    registration stored before 0.1.5 wasn't checked: `kindgi doctor`
+    names its problems (`GET /v1/providers/<id>/check`); unregister it
+    and register it again.
+
 ## Verifying end-to-end
 
 ```sh

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

@@ -132,6 +132,32 @@ const defined = defineTool({
 
 The runtime resolves every declared secret on every call, for the call's tenant, in its env (`KINDGI_ENV`; in `kindgi dev`, `local`: the pack's `.env` and `.env.local`). It checks each value against its schema, and fails the call, naming the secret, when one is missing or doesn't match. Every declared secret is required, so in a runtime call `ctx.secrets` holds them all; it's optional in the type because a unit test builds its own context and passes `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 `needsSpec.env`, read from `ctx.env`:
+
+```ts
+const defined = defineTool({
+  // …id, description, version, input, output, effects…
+  needsSpec: {
+    env: {
+      ORDERS_BASE_URL: { type: 'string', pattern: '^https://' },
+      ORDERS_REGION: { type: 'string', enum: ['eu', 'us'], default: 'eu' },
+    },
+  },
+  handler: async ({ orderId }, ctx) => ({
+    url: `${ctx.env?.ORDERS_BASE_URL}/${ctx.env?.ORDERS_REGION}/orders/${orderId}`,
+  }),
+});
+```
+
+- **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 (`needsSpec.secrets`), never an env value.
+- **In a unit test:** pass `env: { … }` in the context `invokeTool` gets.
+
 Everything else comes from the process environment: `process.env.CITATOR_URL`. The pack service runs with the pack's env files in `kindgi dev`, and with the container's environment in an image. Declare the names your code reads in `kindgi.config.ts`, `env: { required: ['CITATOR_URL'], optional: [...] }`: a deployment injects exactly those, a pack service missing a required one isn't ready and says which, and `kindgi dev` warns about it. Values per environment go in `environments.<name>.env`, secrets only as references.
 
 ## Declarative HTTP spec

package/skills/kindgi-framework-feedback/SKILL.md

@@ -14,9 +14,9 @@ description: >
   diagnostic output into durable input for framework improvement.
 type: core
 library: "@kindgi/sdk"
-version: "0.4.0"
+version: "0.4.2"
 sdk_version: "0.0.0"
-pack_languages: [node, python]
+pack_languages: [node, python, java, scala]
 ---
 
 # Capturing framework feedback
@@ -25,7 +25,8 @@ pack_languages: [node, python]
 > (`@kindgi/cli`), not a global command. Run it through the project's
 > package manager — `pnpm exec kindgi …`, `npx --no kindgi …` (npm),
 > `yarn kindgi …` or `bun run kindgi …`. A Python pack (`[tool.kindgi]` in
-> `pyproject.toml`) has no Node project: run the `kindgi` on `PATH`.
+> `pyproject.toml`) has no Node project: run the `kindgi` on `PATH`. A Java
+> or Scala pack (`kindgi.config.json`) runs the CLI it pins: `./kindgiw …`.
 > Commands below are written `kindgi …` for brevity.
 
 You just spent time diagnosing a Kindgi-framework issue. That diagnostic