@kindgi/sdk 0.1.5-rc.0 → 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';

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,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"}
+{"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,7 +50,34 @@ 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';

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,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"}
+{"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.5-rc.0",
+  "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.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"
+    "@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

@@ -174,6 +174,10 @@ export default defined.value;
   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

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`:
@@ -202,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>`
@@ -236,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-python-authoring-agents/SKILL.md

@@ -169,6 +169,10 @@ brief_writer = Agent(
   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"]`.
+  `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": ["acme.preference"], "scope":
   "same-user", "keepDays": 30}}` gives the turn the built-in tool
   `kindgi_remember` (name it exactly so in the instructions). The model

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

@@ -14,7 +14,7 @@ description: >
   kindgi-python-getting-started.
 type: core
 library: "kindgi (Python)"
-version: "0.1.2"
+version: "0.1.3"
 sdk_version: "0.0.0"
 pack_languages: [python]
 sources:
@@ -121,6 +121,14 @@ def verify_citation(citation: Citation, ctx: ToolContext) -> Verdict:
   (`kindgi env set NAME <value> --scope=project:<id> --env=<env>`).
   Strings, and not secret. Empty from an older runtime.
 - `ctx.config` — **reserved, empty today**.
+- `ctx.log` — a logger bound to the call (its records carry the run's ids,
+  the tool's id and the trace id): `ctx.log.info("refund issued",
+  {"orderId": order_id, "amountCents": amount_cents})`, or the fields as
+  keywords. Values go in the 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.
+  `ToolContext.for_test(…)` logs nothing unless you pass it `log=`. Docs:
+  https://docs.kindgi.com/v0.1/guides/tools/write-a-tool/#log-from-a-tool
 
 ## Configuration and secrets
 

package/src/client.ts

@@ -43,6 +43,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';
@@ -51,7 +57,34 @@ export type { KindgiClient } from '@kindgi/client';
  * ```
  */
 export function createClient(options: Partial<ClientOptions> = {}): KindgiClient {
-  return createKindgiClient(resolveClientOptions(options));
+  let client: KindgiClient | undefined;
+  // A failed lookup isn't kept: the env may be set by the next use.
+  const resolved = (): KindgiClient => {
+    client ??= createKindgiClient(resolveClientOptions(options));
+    return client;
+  };
+  return new Proxy({} as KindgiClient, {
+    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 };
+    },
+  });
 }
 
 // ---- Resource client types + per-resource input shapes ----