@kindgi/sdk 0.1.4 → 0.1.5

package/dist/client.d.ts

@@ -15,6 +15,12 @@ export type { KindgiClient } from '@kindgi/client';
  * browser, pass `apiUrl` and `auth`. `@kindgi/client`'s `createClient` is
  * the explicit form underneath.
  *
+ * The options are found on first use, not here: a module-scope
+ * `const kindgi = createClient()` is safe to import where the runtime's
+ * settings aren't set, as a production build (`next build`) imports every
+ * module. When they're missing, the first use (`kindgi.runs`, …) throws
+ * the error that says what to set; once they're set, the next use works.
+ *
  * @example
  * ```ts
  * import { createClient } from '@kindgi/sdk/client';
@@ -28,6 +34,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;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,OAAO,CAAC,aAAa,CAAM,GAAG,YAAY,CA6B/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

@@ -36,6 +36,12 @@ import { resolveClientOptions } from './runtime-config.js';
  * browser, pass `apiUrl` and `auth`. `@kindgi/client`'s `createClient` is
  * the explicit form underneath.
  *
+ * The options are found on first use, not here: a module-scope
+ * `const kindgi = createClient()` is safe to import where the runtime's
+ * settings aren't set, as a production build (`next build`) imports every
+ * module. When they're missing, the first use (`kindgi.runs`, …) throws
+ * the error that says what to set; once they're set, the next use works.
+ *
  * @example
  * ```ts
  * import { createClient } from '@kindgi/sdk/client';
@@ -44,12 +50,41 @@ import { resolveClientOptions } from './runtime-config.js';
  * ```
  */
 export function createClient(options = {}) {
-    return createKindgiClient(resolveClientOptions(options));
+    let client;
+    // A failed lookup isn't kept: the env may be set by the next use.
+    const resolved = () => {
+        client ??= createKindgiClient(resolveClientOptions(options));
+        return client;
+    };
+    return new Proxy({}, {
+        get(_target, key) {
+            // Never resolve to answer whether the client is a promise (`await`,
+            // `return` from an async function), or for a symbol a tool inspects.
+            if (client === undefined && (key === 'then' || typeof key === 'symbol'))
+                return undefined;
+            return Reflect.get(resolved(), key);
+        },
+        // A write (a test swapping a resource) is a use: it lands on the client.
+        // A property defined non-configurable (`defineProperty`'s default) throws:
+        // a proxy can't hold one its target doesn't. Define it `configurable: true`.
+        set: (_target, key, value) => Reflect.set(resolved(), key, value),
+        defineProperty: (_target, key, descriptor) => Reflect.defineProperty(resolved(), key, descriptor),
+        deleteProperty: (_target, key) => Reflect.deleteProperty(resolved(), key),
+        has: (_target, key) => key in resolved(),
+        ownKeys: () => Reflect.ownKeys(resolved()),
+        getOwnPropertyDescriptor(_target, key) {
+            const descriptor = Reflect.getOwnPropertyDescriptor(resolved(), key);
+            // The target holds none of the client's fields, so none may be reported fixed.
+            return descriptor === undefined ? undefined : { ...descriptor, configurable: true };
+        },
+    });
 }
 // ---- Error surface ----
 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;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,YAAY,CAAC,UAAkC,EAAE;IAC/D,IAAI,MAAgC,CAAC;IACrC,kEAAkE;IAClE,MAAM,QAAQ,GAAG,GAAiB,EAAE;QAClC,MAAM,KAAK,kBAAkB,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC,CAAC;QAC7D,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;IACF,OAAO,IAAI,KAAK,CAAC,EAAkB,EAAE;QACnC,GAAG,CAAC,OAAO,EAAE,GAAG;YACd,oEAAoE;YACpE,qEAAqE;YACrE,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,GAAG,KAAK,MAAM,IAAI,OAAO,GAAG,KAAK,QAAQ,CAAC;gBAAE,OAAO,SAAS,CAAC;YAC1F,OAAO,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,GAAG,CAAC,CAAC;QACtC,CAAC;QACD,yEAAyE;QACzE,2EAA2E;QAC3E,6EAA6E;QAC7E,GAAG,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC;QACjE,cAAc,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,EAAE,CAC3C,OAAO,CAAC,cAAc,CAAC,QAAQ,EAAE,EAAE,GAAG,EAAE,UAAU,CAAC;QACrD,cAAc,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,cAAc,CAAC,QAAQ,EAAE,EAAE,GAAG,CAAC;QACzE,GAAG,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,QAAQ,EAAE;QACxC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QAC1C,wBAAwB,CAAC,OAAO,EAAE,GAAG;YACnC,MAAM,UAAU,GAAG,OAAO,CAAC,wBAAwB,CAAC,QAAQ,EAAE,EAAE,GAAG,CAAC,CAAC;YACrE,+EAA+E;YAC/E,OAAO,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,UAAU,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;QACtF,CAAC;KACF,CAAC,CAAC;AACL,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",
+  "version": "0.1.5",
   "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",
-    "@kindgi/client": "0.1.4",
-    "@kindgi/crypto": "0.1.4",
-    "@kindgi/flow": "0.1.4",
-    "@kindgi/guardrails": "0.1.4",
-    "@kindgi/handler-runtime": "0.1.4",
-    "@kindgi/schema": "0.1.4",
-    "@kindgi/tools": "0.1.4",
-    "@kindgi/types": "0.1.4"
+    "@kindgi/agents": "0.1.5",
+    "@kindgi/client": "0.1.5",
+    "@kindgi/crypto": "0.1.5",
+    "@kindgi/flow": "0.1.5",
+    "@kindgi/guardrails": "0.1.5",
+    "@kindgi/handler-runtime": "0.1.5",
+    "@kindgi/schema": "0.1.5",
+    "@kindgi/tools": "0.1.5",
+    "@kindgi/types": "0.1.5"
   },
   "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.4"
+version: "0.4.5"
 sdk_version: "0.0.0"
 pack_languages: [node]
 sources:
@@ -160,6 +160,34 @@ 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.
+  `same-user` memory (facts, recall or `remember`) is the run's end user's:
+  pass `participantId` on every run. A run without one reads and keeps
+  none (its result warns `memory-needs-participant`), never the memory of
+  the user a key acts for, who may serve many people.
+- **`memory`** — `{ remember: { types, 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

@@ -23,9 +23,9 @@ description: >
   kindgi-getting-started.
 type: core
 library: "@kindgi/sdk"
-version: "0.9.8"
+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
@@ -41,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.
@@ -76,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
@@ -131,8 +133,9 @@ credential on argv.
 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
 ```
-Don't pin `claude-haiku-4-5`: Anthropic retires it on or after 2026-10-15,
-and a turn routed to it then fails; `claude-haiku-5-5` replaces it. Each
+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.
@@ -164,12 +167,15 @@ providers: [
 preset = "anthropic"
 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
@@ -535,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
 
@@ -550,7 +557,8 @@ 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
@@ -649,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
@@ -686,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
@@ -716,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

@@ -12,7 +12,7 @@ description: >
   authoring agents is covered by kindgi-authoring-agents.
 type: core
 library: "@kindgi/sdk"
-version: "0.4.4"
+version: "0.4.5"
 sdk_version: "0.0.0"
 pack_languages: [node]
 sources:
@@ -115,6 +115,16 @@ The handler gets the **parsed** input, typed `z.infer` of `input` (Zod's output
 
 The output side is the reverse: the advertised output schema requires every field, defaulted ones included. Return them all.
 
+### Logging from the handler
+
+`ctx.log` is a logger bound to the call: its records carry the run's ids, the tool's id and the trace id. It has `info`, `warn`, `error`, `debug` and `trace`, each `(message, fields?)`. The pack service sets it; a context your own code builds (a test's) may not, so write `ctx.log?.`:
+
+```ts
+ctx.log?.info('refund issued', { orderId, amountCents });
+```
+
+Put values in `fields`, never in the message. Log ids, amounts and outcomes, never what a person typed (a refund's reason, a message, an address): the log is read by whoever operates the runtime, not only by the person the data is about. Docs: https://docs.kindgi.com/v0.1/guides/tools/write-a-tool/#log-from-a-tool
+
 ### Configuration and secrets
 
 A secret that belongs to the tenant — an API key a customer gives you — is declared, and read from `ctx.secrets`:
@@ -132,6 +142,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
@@ -176,6 +212,15 @@ export default defined.value;
 
 So declare `mutating: false` on every tool that only reads, and never on one that writes.
 
+A tool that writes also says what it writes, in `effects`, beside `mutating: true`:
+
+```ts
+  effects: [{ kind: 'writes', resource: 'acme:refunds' }],
+  mutating: true,
+```
+
+The kinds are `reads`, `writes`, `deletes`, `network`, `spawns-run`, `emits-event`, `external-side-effect` and `sensitive-data-egress` (`EFFECT_KINDS` in `@kindgi/tools`); `defineTool` refuses any other. `resource` is free text naming what the tool touches. A read-only tool keeps `effects: []`.
+
 ## Tool id convention
 
 `<pack-id>.<tool-name>` — kebab-case, dot-namespaced. The `<pack-id>`
@@ -210,6 +255,25 @@ range at run start. Compatible tool updates (patch, minor) reach the
 agent without editing agent source; breaking updates (major) require
 the agent-author to opt in.
 
+## Testing a tool
+
+Put a tool's tests beside it, `tools/<tool>/index.test.ts`. Discovery skips `*.test.*` and `*.spec.*` files (`.ts`, `.js`, `.mjs`, `.cjs`), so the indexer never loads a test as a primitive: don't move tests elsewhere to keep them out. `invokeTool(tool, input, ctx)` from `@kindgi/sdk/define` calls the tool the way Kindgi does, schemas included, and returns a `Result`. Its `ctx` needs a `tenantId` and an `abortSignal` (`ToolContext` in `@kindgi/tools`); the rest is optional. vitest doesn't typecheck, so a context missing them still passes the test: run `tsc --noEmit` too.
+
+```ts
+import { invokeTool } from '@kindgi/sdk/define';
+import type { TenantId } from '@kindgi/sdk/types';
+
+const ctx = { tenantId: 'test' as TenantId, abortSignal: new AbortController().signal };
+// add `env: { STORE_URL: '…' }` for a tool that reads a declared env value
+const result = await invokeTool(lookupOrder, { orderId: 'ord_1001' }, ctx);
+```
+
+`kindgi test` runs the pack's tests with vitest (`vitest run`; `--watch` keeps watching).
+
+## Shared code
+
+Code several tools share (schemas, a client, helpers) goes outside `tools/`, for example in `lib/` beside it. Discovery loads every `.ts`, `.js` and `.mjs` file under `tools/` (tests aside) as a primitive, so a helper there fails the index. Don't put it in the app's own source either: import the app's functions from where they are, and keep what's Kindgi's in the pack's folder.
+
 ## Wiring the tool onto an agent
 
 Agents reference tools via `ToolRef[]`, NOT `string[]`. Each entry is

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