@kindgi/sdk 0.1.0 → 0.1.2

package/README.md

@@ -54,10 +54,7 @@ point for JSON coming off disk / network.
 import { createClient } from '@kindgi/sdk/client';
 import type { AgentId } from '@kindgi/sdk/types';
 
-const client = createClient({
-  apiUrl: process.env.KINDGI_API_URL!,
-  auth: { kind: 'apiToken', token: process.env.KINDGI_API_TOKEN! },
-});
+const client = createClient();
 
 const run = await client.runs.start({
   agent: 'acme.drafting' as AgentId,
@@ -65,9 +62,32 @@ const run = await client.runs.start({
 });
 ```
 
-Re-exports:
+`createClient()` finds the runtime by itself. Every option is optional:
+
+- `apiUrl` and `auth` come from `KINDGI_API_URL` and `KINDGI_API_TOKEN`;
+- in development, when those aren't set, from the running `kindgi dev`
+  (the nearest `.kindgirc.json`), with a one-time warning to put them in
+  your env file (`.env` / `.env.local`);
+- a token that doesn't match the running `kindgi dev`'s for the same URL
+  (after `kindgi dev --reset`) is warned about once.
+
+Production (`NODE_ENV` or `KINDGI_ENV` = `production`) never reads
+`.kindgirc.json`: the env or explicit options must say. Explicit options
+always win, field by field:
+
+```ts
+const client = createClient({
+  apiUrl: 'https://kindgi.internal.acme.com',
+  auth: { kind: 'apiToken', token: await secrets.get('kindgi-api-token') },
+});
+```
+
+In a browser, pass `apiUrl` and `auth` to `@kindgi/client`'s `createClient`
+(the explicit client underneath).
+
+Exports:
 
-- `createClient`, `KindgiClient`.
+- `createClient` (above), `KindgiClient`.
 - Every resource client type — `AgentsClient`, `RunsClient`, `ToolsClient`,
   `ApprovalsClient`, `SupervisorClient`, `ProposalsClient`, `ObservationsClient`,
   `FlowsClient`, `GuardrailsClient`, `ConversationsClient`, `MemoryClient`,

package/dist/client.d.ts

@@ -1,23 +1,28 @@
+import type { ClientOptions, KindgiClient } from '@kindgi/client';
+export type { KindgiClient } from '@kindgi/client';
 /**
- * `@kindgi/sdk/client` — client callsite surface.
+ * A client for the app's Kindgi runtime. Every option is optional:
  *
- * Re-exports `createClient` plus every resource-client type, the error
- * surface, transport primitives, and streaming helpers from the
- * `@kindgi/client` package (`sdks/typescript/` in this repository).
- * Names preserved verbatim.
+ * - `apiUrl` and `auth` come from `KINDGI_API_URL` and `KINDGI_API_TOKEN`;
+ * - outside production, when those aren't set, from the running
+ *   `kindgi dev` (the nearest `.kindgirc.json`), with a one-time warning to
+ *   put them in the app's env file;
+ * - a token that doesn't match the running `kindgi dev`'s for the same
+ *   `apiUrl` (after `kindgi dev --reset`) is warned about once.
  *
- * This sub-path intentionally does NOT re-export the branded ID types
- * (`AgentId`, `RunId`, etc.) that `@kindgi/client` also happens to
- * surface — those live in `@kindgi/sdk/types` to keep the flat barrel
- * (`import { ... } from '@kindgi/sdk'`) collision-free.
+ * Production (`NODE_ENV` or `KINDGI_ENV` = `production`) never reads
+ * `.kindgirc.json`: there, the env or explicit options must say. In a
+ * browser, pass `apiUrl` and `auth`. `@kindgi/client`'s `createClient` is
+ * the explicit form underneath.
  *
- * Callsite examples target
- * `import { createClient } from '@kindgi/sdk/client'`.
+ * @example
+ * ```ts
+ * import { createClient } from '@kindgi/sdk/client';
  *
- * @module @kindgi/sdk/client
+ * const kindgi = createClient();
+ * ```
  */
-export { createClient } from '@kindgi/client';
-export type { KindgiClient } from '@kindgi/client';
+export declare function createClient(options?: Partial<ClientOptions>): KindgiClient;
 export type { AdapterConfigureInput, AdapterFilter, AdapterTestInput, AdaptersClient, AddMembershipInput, AgentsClient, ApplyProposalInput, ApprovalFilter, ApprovalsClient, ArtifactFilter, ArtifactsClient, AuditClient, AuditExportInput, BatchDecideInput, BudgetsClient, CapabilitiesClient, CapabilityFilter, ClientOptions, CompleteTokenInput, ConversationFilter, ConversationsClient, CostClient, DecideInput, DraftProposalsInput, EventsClient, FactsClient, FlowFilter, FlowsClient, FlowValidateResult, GuardrailFilter, GuardrailsClient, LogsClient, McpClient, McpEndpointFilter, McpEndpointsClient, TeamMembershipsClient, MemoryClient, MessageFilter, ObservationFilter, ObservationsClient, OrgsClient, PackFilter, PacksClient, PageFilter, PatternsInput, PoliciesClient, PolicyListFilter, PolicyVersionsFilter, ProposalDryRunInput, ProposalListInput, ProposalsClient, ProvenanceClient, ProvenanceExportInput, ProviderFilter, ProvidersClient, ReflectReviewInput, RegistryClient, RegistryFilter, ResumeRunInput, ReviewerFilter, ReviewersClient, RollbackProposalInput, Run, RunsClient, SchedulesClient, SessionsClient, StartRunInput, SubmitForReviewInput, SubscriptionsClient, SupervisorClient, ListTeamsFilter, TeamsClient, TenantClient, TenantConfigClient, TokenFilter, TokensClient, ReinstateToolVersionResult, ToolFilter, ToolVersionFilter, ToolsClient, Transport, TransportRequest, UsageClient, UsageSummaryInput, UserFilter, UsersClient, WebhooksClient, WithdrawProposalInput, } from '@kindgi/client';
 export { KindgiApiError, fromWire, notImplementedInPreview, notYetWired } from '@kindgi/client';
 export type { AuthError, ConflictError, GuardrailViolation, GuardrailViolationError, InvalidRequestError, NetworkError, NotFoundError, NotImplementedInPreviewError, NotYetWiredError, RateLimitedError, ServerError, KindgiError, } from '@kindgi/client';

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGnD,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"}
+{"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"}

package/dist/client.js

@@ -19,7 +19,33 @@
  * @module @kindgi/sdk/client
  */
 // ---- Client factory + top-level shape ----
-export { createClient } from '@kindgi/client';
+import { createClient as createKindgiClient } from '@kindgi/client';
+import { resolveClientOptions } from './runtime-config.js';
+/**
+ * A client for the app's Kindgi runtime. Every option is optional:
+ *
+ * - `apiUrl` and `auth` come from `KINDGI_API_URL` and `KINDGI_API_TOKEN`;
+ * - outside production, when those aren't set, from the running
+ *   `kindgi dev` (the nearest `.kindgirc.json`), with a one-time warning to
+ *   put them in the app's env file;
+ * - a token that doesn't match the running `kindgi dev`'s for the same
+ *   `apiUrl` (after `kindgi dev --reset`) is warned about once.
+ *
+ * Production (`NODE_ENV` or `KINDGI_ENV` = `production`) never reads
+ * `.kindgirc.json`: there, the env or explicit options must say. In a
+ * browser, pass `apiUrl` and `auth`. `@kindgi/client`'s `createClient` is
+ * the explicit form underneath.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from '@kindgi/sdk/client';
+ *
+ * const kindgi = createClient();
+ * ```
+ */
+export function createClient(options = {}) {
+    return createKindgiClient(resolveClientOptions(options));
+}
 // ---- Error surface ----
 export { KindgiApiError, fromWire, notImplementedInPreview, notYetWired } from '@kindgi/client';
 // ---- Streaming helpers (SSE parser + resume) ----

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,EAAE,MAAM,gBAAgB,CAAC;AA+F9C,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"}
+{"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"}

package/dist/runtime-config.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Where an app's client finds its Kindgi runtime when `createClient` is
+ * called without `apiUrl` / `auth`:
+ *
+ *   1. `KINDGI_API_URL` and `KINDGI_API_TOKEN` from the environment;
+ *   2. outside production, the running `kindgi dev`, from the nearest
+ *      `.kindgirc.json` at or above the working directory (it records the
+ *      runtime's `apiUrl` and the dev `token`), with a one-time warning to
+ *      put them in the app's env file;
+ *   3. otherwise, an error that says what to set.
+ *
+ * Production (`NODE_ENV` or `KINDGI_ENV` set to `production`) never reads
+ * `.kindgirc.json`. Whatever the source, a token that differs from the
+ * running `kindgi dev`'s for the same `apiUrl` (the stale token after
+ * `kindgi dev --reset`) is warned about once.
+ *
+ * Node only: the file is read through `process.getBuiltinModule`, never a
+ * static `node:` import, so the module stays safe to bundle for browsers,
+ * where only explicit options apply.
+ */
+import type { ClientOptions } from '@kindgi/client';
+/** The file `kindgi dev` writes in the pack directory. */
+export declare const DEV_RUNTIME_FILE = ".kindgirc.json";
+/** What a client needs from a running `kindgi dev`. */
+export interface DevRuntime {
+    readonly apiUrl: string;
+    readonly token: string;
+    /** The `.kindgirc.json` it came from. */
+    readonly path: string;
+}
+/** Where the lookup runs: the process's own environment by default (tests pass their own). */
+export interface RuntimeConfigContext {
+    readonly env: Readonly<Record<string, string | undefined>>;
+    /** The directory the `.kindgirc.json` search starts from. */
+    readonly cwd: string | undefined;
+    readonly warn: (message: string) => void;
+}
+export declare function defaultContext(): RuntimeConfigContext;
+export declare function isProduction(env: RuntimeConfigContext['env']): boolean;
+/**
+ * The client options with every missing field resolved (see the module
+ * comment). Throws when no `apiUrl` or no token can be found.
+ */
+export declare function resolveClientOptions(options: Partial<ClientOptions>, context?: RuntimeConfigContext): ClientOptions;
+/**
+ * The running `kindgi dev`'s `apiUrl` and `token`, from the nearest
+ * `.kindgirc.json` at or above `from`; `undefined` when there's none, it
+ * can't be read, or the runtime can't read files (a browser).
+ */
+export declare function findDevRuntime(from: string | undefined): DevRuntime | undefined;
+/** Tests only: forget which warnings were printed. */
+export declare function resetWarningsForTests(): void;
+//# sourceMappingURL=runtime-config.d.ts.map

package/dist/runtime-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-config.d.ts","sourceRoot":"","sources":["../src/runtime-config.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAc,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEhE,0DAA0D;AAC1D,eAAO,MAAM,gBAAgB,mBAAmB,CAAC;AAEjD,uDAAuD;AACvD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,8FAA8F;AAC9F,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC3D,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAC1C;AAYD,wBAAgB,cAAc,IAAI,oBAAoB,CAOrD;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,oBAAoB,CAAC,KAAK,CAAC,GAAG,OAAO,CAEtE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,EAC/B,OAAO,GAAE,oBAAuC,GAC/C,aAAa,CAqDf;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAU/E;AA+BD,sDAAsD;AACtD,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C"}

package/dist/runtime-config.js

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/** The file `kindgi dev` writes in the pack directory. */
+export const DEV_RUNTIME_FILE = '.kindgirc.json';
+const ENV_FILE_HINT = 'your env file (.env / .env.local)';
+const warned = new Set();
+function warnOnce(context, key, message) {
+    if (warned.has(key))
+        return;
+    warned.add(key);
+    context.warn(`[kindgi] ${message}`);
+}
+export function defaultContext() {
+    const proc = typeof process === 'undefined' ? undefined : process;
+    return {
+        env: proc?.env ?? {},
+        cwd: typeof proc?.cwd === 'function' ? proc.cwd() : undefined,
+        warn: (message) => console.warn(message),
+    };
+}
+export function isProduction(env) {
+    return env.NODE_ENV === 'production' || env.KINDGI_ENV === 'production';
+}
+/**
+ * The client options with every missing field resolved (see the module
+ * comment). Throws when no `apiUrl` or no token can be found.
+ */
+export function resolveClientOptions(options, context = defaultContext()) {
+    const { env } = context;
+    const dev = isProduction(env) ? undefined : findDevRuntime(context.cwd);
+    let apiUrl = options.apiUrl ?? nonEmpty(env.KINDGI_API_URL);
+    let auth = options.auth ??
+        (nonEmpty(env.KINDGI_API_TOKEN) !== undefined
+            ? { kind: 'apiToken', token: env.KINDGI_API_TOKEN }
+            : undefined);
+    if ((apiUrl === undefined || auth === undefined) && dev !== undefined) {
+        const used = [];
+        if (apiUrl === undefined) {
+            apiUrl = dev.apiUrl;
+            used.push('KINDGI_API_URL');
+        }
+        if (auth === undefined) {
+            auth = { kind: 'apiToken', token: dev.token };
+            used.push('KINDGI_API_TOKEN');
+        }
+        warnOnce(context, `fallback:${dev.path}`, `Using the running kindgi dev from ${dev.path} for ${used.join(' and ')}. Set them in ${ENV_FILE_HINT}, and in production, where there's no ${DEV_RUNTIME_FILE}.`);
+    }
+    if (apiUrl === undefined || auth === undefined) {
+        const missing = [
+            ...(apiUrl === undefined ? ['KINDGI_API_URL'] : []),
+            ...(auth === undefined ? ['KINDGI_API_TOKEN'] : []),
+        ];
+        throw new Error(`createClient(): ${missing.join(' and ')} ${missing.length === 1 ? "isn't" : "aren't"} set. Set ${missing.length === 1 ? 'it' : 'them'} in ${ENV_FILE_HINT}, or pass { apiUrl, auth }.${isProduction(env)
+            ? ''
+            : ` In development, run \`kindgi dev\` in the app: it writes them to ${DEV_RUNTIME_FILE}, which the client reads.`}`);
+    }
+    if (dev !== undefined && auth.kind === 'apiToken' && auth.token !== dev.token) {
+        if (sameUrl(apiUrl, dev.apiUrl)) {
+            warnOnce(context, `stale:${dev.path}:${dev.token}`, `The API token doesn't match the running kindgi dev's (${dev.path}). After \`kindgi dev --reset\` the token changes: copy the new one into ${ENV_FILE_HINT}.`);
+        }
+    }
+    return { ...options, apiUrl, auth };
+}
+/**
+ * The running `kindgi dev`'s `apiUrl` and `token`, from the nearest
+ * `.kindgirc.json` at or above `from`; `undefined` when there's none, it
+ * can't be read, or the runtime can't read files (a browser).
+ */
+export function findDevRuntime(from) {
+    if (from === undefined)
+        return undefined;
+    const fs = builtin('node:fs');
+    const path = builtin('node:path');
+    if (fs === undefined || path === undefined)
+        return undefined;
+    for (let dir = from;; dir = path.dirname(dir)) {
+        const candidate = path.join(dir, DEV_RUNTIME_FILE);
+        if (fs.existsSync(candidate))
+            return readDevRuntime(fs, candidate);
+        if (path.dirname(dir) === dir)
+            return undefined;
+    }
+}
+function readDevRuntime(fs, file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        const apiUrl = parsed.apiUrl;
+        const token = parsed.token;
+        if (typeof apiUrl !== 'string' || apiUrl === '' || typeof token !== 'string' || token === '') {
+            return undefined;
+        }
+        return { apiUrl, token, path: file };
+    }
+    catch {
+        return undefined;
+    }
+}
+function builtin(id) {
+    const proc = typeof process === 'undefined' ? undefined : process;
+    const get = proc
+        ?.getBuiltinModule;
+    return typeof get === 'function' ? get.call(proc, id) : undefined;
+}
+function nonEmpty(value) {
+    return value === undefined || value === '' ? undefined : value;
+}
+function sameUrl(a, b) {
+    return a.replace(/\/+$/, '') === b.replace(/\/+$/, '');
+}
+/** Tests only: forget which warnings were printed. */
+export function resetWarningsForTests() {
+    warned.clear();
+}
+//# sourceMappingURL=runtime-config.js.map

package/dist/runtime-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-config.js","sourceRoot":"","sources":["../src/runtime-config.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindgi/sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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": {
@@ -18,27 +18,33 @@
   "exports": {
     "./define": {
       "types": "./dist/define.d.ts",
-      "import": "./dist/define.js"
+      "import": "./dist/define.js",
+      "default": "./dist/define.js"
     },
     "./client": {
       "types": "./dist/client.d.ts",
-      "import": "./dist/client.js"
+      "import": "./dist/client.js",
+      "default": "./dist/client.js"
     },
     "./types": {
       "types": "./dist/types.d.ts",
-      "import": "./dist/types.js"
+      "import": "./dist/types.js",
+      "default": "./dist/types.js"
     },
     "./webhooks": {
       "types": "./dist/webhooks.d.ts",
-      "import": "./dist/webhooks.js"
+      "import": "./dist/webhooks.js",
+      "default": "./dist/webhooks.js"
     },
     "./build": {
       "types": "./dist/build.d.ts",
-      "import": "./dist/build.js"
+      "import": "./dist/build.js",
+      "default": "./dist/build.js"
     },
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     },
     "./package.json": "./package.json"
   },
@@ -49,15 +55,23 @@
     "README.md"
   ],
   "dependencies": {
-    "@kindgi/agents": "0.1.0",
-    "@kindgi/client": "0.1.0",
-    "@kindgi/crypto": "0.1.0",
-    "@kindgi/flow": "0.1.0",
-    "@kindgi/guardrails": "0.1.0",
-    "@kindgi/handler-runtime": "0.1.0",
-    "@kindgi/schema": "0.1.0",
-    "@kindgi/tools": "0.1.0",
-    "@kindgi/types": "0.1.0"
+    "@kindgi/agents": "0.1.2",
+    "@kindgi/client": "0.1.2",
+    "@kindgi/crypto": "0.1.2",
+    "@kindgi/flow": "0.1.2",
+    "@kindgi/guardrails": "0.1.2",
+    "@kindgi/handler-runtime": "0.1.2",
+    "@kindgi/schema": "0.1.2",
+    "@kindgi/tools": "0.1.2",
+    "@kindgi/types": "0.1.2"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/node": "^22.10.5",
@@ -67,7 +81,7 @@
     "vitest": "^2.1.8"
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.12.0"
   },
   "publishConfig": {
     "access": "public",

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

@@ -12,7 +12,7 @@ description: >
   kindgi-authoring-guardrails.
 type: core
 library: "@kindgi/sdk"
-version: "0.4.1"
+version: "0.4.2"
 sdk_version: "0.0.0"
 pack_languages: [node]
 sources:
@@ -237,8 +237,7 @@ concerns, not author-time.
 
 - Type surface: `hover any @kindgi/sdk/define export` in your editor
   for full JSDoc.
-- Companion docs: `pnpm --filter @kindgi/sdk exec typedoc` regenerates
-  markdown API docs at `packages/sdk/docs/`.
+- API reference: https://docs.kindgi.com/v0.1/reference/typescript/sdk/kindgi/sdk/define/ (every `define*` spec, field by field).
 - Common patterns: the `sample` template's `agents/echo-agent`
   demonstrates the smallest tool-calling shape.
 

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

@@ -13,7 +13,7 @@ description: >
   kindgi-authoring-agents.
 type: core
 library: "@kindgi/sdk"
-version: "0.1.1"
+version: "0.1.2"
 sdk_version: "0.0.0"
 pack_languages: [node]
 sources:
@@ -189,9 +189,11 @@ the condition is true. Conditions are JSON:
 | `and` `or` | `{ op, children: [...] }` |
 | `not` | `{ op, child }` |
 
-Each operand is `{ literal: … }` or `{ path: … }`. A comparison whose
-path doesn't resolve is **false**, `ne` included. So to branch on "not
-billing", write `not` around the `eq` (as above), not `ne`.
+Each operand is `{ literal: … }` or `{ path: … }`. When a path doesn't
+resolve, `eq`, `lt`, `lte`, `gt` and `gte` are false and `ne` is true. So
+for the "otherwise" branch, write `not` around the condition (as above),
+rather than a second comparison: it covers exactly what the first edge
+doesn't.
 
 **Joining branches.** A node with several incoming edges runs once every
 one of them is decided and at least one fired. In the example, `reply`
@@ -212,7 +214,7 @@ A node with several incoming edges ignores them.
 ## Inputs and the output
 
 `inputMapping` maps each key to a `{ literal }` or a `{ path }`. Paths are
-dot-separated, with no array indexing, rooted at:
+dot-separated (a number segment indexes an array: `items.0.sku`), rooted at:
 - `runInput.…`: the input the run was started with;
 - `nodeOutputs.<nodeId>.…`: a step's output. For an agent step, add
   `.output.<field>` to read its typed answer;
@@ -269,9 +271,10 @@ the output), not on every save.
 1. **Building a flow without asking what goes in and comes out.** The
    pack's `echo-flow` proves the runtime works. It isn't a template for
    the user's flow.
-2. **`ne` on a path that may be missing, to mean "otherwise".** A missing
-   path makes every comparison false, so neither branch fires and
-   everything after is skipped. Use `not` around the positive condition.
+2. **A second comparison for "otherwise".** On a path that may be
+   missing, `eq` is false and `ne` is true, and `lt`/`gt` are both false,
+   so a hand-written opposite can miss a case or overlap. Use `not` around
+   the positive condition: it covers exactly what the first edge doesn't.
 3. **Reading an agent step's answer at `nodeOutputs.<step>.<field>`.**
    The typed answer is under `.output`: `nodeOutputs.<step>.output.<field>`.
    An agent without an `output` schema has only `text`.

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

@@ -15,7 +15,7 @@ description: >
   kindgi-authoring-agents.
 type: core
 library: "@kindgi/sdk"
-version: "0.3.5"
+version: "0.3.6"
 sdk_version: "0.0.0"
 pack_languages: [node]
 sources:
@@ -107,11 +107,17 @@ How the pack tooling reads this file:
   `configZod`, `configSchema` or `configJsonSchema`, or a top-level
   `configZod` / `configSchema`), and the declaration's `config` — what
   the check runs with. It does not record `description`, `budget` or
-  `judgeCapabilities`.
+  `judgeCapabilities`. It checks `config` (none counts as `{}`) against
+  the config schema: a config that doesn't fit, or a required field with
+  no default left out, is a file error naming where, and `kindgi build`
+  refuses the pack.
 - The **pack service** loads the same module to run the check. It uses
   the module's `evaluate` export, or the `default` / `check` export when
   that is a function or has an `evaluate` method — here, the named
-  `check` export.
+  `check` export. A `defineCheck` check's `evaluate` gets the config its
+  schema resolves: the schema's defaults applied (a guardrail that
+  declares no config gets them all), and a config that doesn't fit
+  refused, naming where.
 
 ## Validating a declaration in-process
 
@@ -167,7 +173,10 @@ available to the runtime that evaluates it.
 - **`config`** — the check's parameters, validated against the check's
   `configSchema` by `defineGuardrail`. In a pack, the declaration's
   `config` goes into the index and the check runs with it; without one
-  it runs with `{}`. `evaluate` receives the config as declared —
+  it runs with `{}`. A declaration a pack file default-exports isn't run
+  through `defineGuardrail`, so nothing validates its `config`: keep it
+  valid against the schema yourself. `evaluate` receives the config as
+  declared —
   schema defaults are not filled in — so handle absent optional fields.
 - **`action.on-violation`** — `'halt'`, `'retry'` (with
   `retry.maxAttempts`, 1–10), `'escalate'` (with `escalateTo`),
@@ -177,7 +186,9 @@ available to the runtime that evaluates it.
   any other action are reported in `AgentTurnResult.violations` and the
   turn completes. The action handlers in `@kindgi/guardrails`
   (`retryHandler`, `escalateHandler`, `compensateHandler`, …) record the
-  intent for callers that act on it.
+  intent for callers that act on it. 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'` (the default) /
   `'critical'`. Orthogonal to `action`: logs and dashboards group by
   severity; execution follows the action. A `log-only` guardrail can
@@ -236,8 +247,9 @@ guardrails: ['acme.no-fabricated-quotes'],
 
 At the start of each turn, the runtime resolves these ids against the
 guardrails available to the run. An id that isn't registered fails the
-turn with `unresolved-guardrail`, so register the guardrail before an
-agent references it.
+turn before the model is called (`Error [invalid-request]: Agent "…"
+references guardrails not in the registry: <id>`), so register the
+guardrail before an agent references it.
 
 ## Changing a guardrail
 
@@ -277,7 +289,7 @@ ready for the stricter enforcement.
 - Type surface: hover any `@kindgi/sdk/define` export for full JSDoc;
   `Guardrail`, `defineGuardrail` and the built-in checks are in
   `@kindgi/guardrails`.
-- Companion docs: `pnpm --filter @kindgi/sdk exec typedoc`.
+- API reference: https://docs.kindgi.com/v0.1/reference/typescript/sdk/kindgi/sdk/define/
 - Built-in check implementations: `packages/guardrails/src/checks.ts`.
 
 ## When the framework itself is the problem

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

@@ -22,7 +22,7 @@ description: >
   kindgi-getting-started.
 type: core
 library: "@kindgi/sdk"
-version: "0.9.1"
+version: "0.9.2"
 sdk_version: "0.0.0"
 pack_languages: [node, python]
 sources:
@@ -492,15 +492,12 @@ into one entry per model (`metadata.models[]`), filters the resulting
 tenant policy), then sorts survivors in this order:
 
 1. **Preferred provider / model.** Tuples matching the agent's
-   `preferredProvider` (and `preferredModel`, when the `Agent` object
-   carries one) are promoted to the front.
+   `preferredProvider` and `preferredModel` are promoted to the front.
      - Both set → promote the exact tuple.
      - Only `preferredModel` set → promote any provider exposing that model.
      - Only `preferredProvider` set → promote every model of that provider.
-   `defineAgent` accepts `preferredProvider` but not `preferredModel`
-   (`DefineAgentSpec` has no such field), so agents built with it can
-   only express a provider preference here. A Python `Agent` takes
-   both (`preferred_provider=`, `preferred_model=`).
+   `defineAgent` takes both (`preferredProvider`, `preferredModel`), and
+   so does a Python `Agent` (`preferred_provider=`, `preferred_model=`).
 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
@@ -597,7 +594,11 @@ 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. Confirm valid ids with `kindgi adapters list`.
+   the registration fails. 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
+   the id each preset uses.
 
 1. **`envName` mismatch between the setter (`kindgi secrets set` or `env set`) and `provider.json`.**
    Both writers use `--env=<name>` (default `local`): `local` is 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.1"
+version: "0.4.4"
 sdk_version: "0.0.0"
 pack_languages: [node]
 sources:
@@ -108,7 +108,7 @@ A handler must return a Promise; one with nothing to `await` can return `Promise
 The handler gets the **parsed** input, typed `z.infer` of `input` (Zod's output type):
 
 - **Defaults.** A `.default()` field is optional to the caller, the model included. The tool's advertised schema doesn't list it as required, and the handler always gets a value.
-- **Transforms and refinements.** `.transform()` results and `.refine()` checks apply before the handler runs. A failed refinement comes back as `input-validation-failed`, with the field's path.
+- **Transforms and refinements.** `.transform()` results and `.refine()` checks apply before the handler runs. A failed refinement comes back as `input-validation-failed`.
 - **Extra keys.** A plain `z.object` accepts them and strips them. Use `z.strictObject` to reject them.
 - **JSON-Schema-authored tools** get each property's `default` filled in the same way.
 
@@ -268,13 +268,34 @@ run start via `semver.maxSatisfying`. No implicit `:latest`.
    changes (breaking schema shape, semantic behavior), not when you
    save. See the "Iterating on a tool" section above.
 
+9. **A package a tool imports, listed only in `devDependencies`.** The
+   deployed pack installs the app's production dependencies only, so the
+   import works under `kindgi dev` and fails in the image. When a tool
+   imports a new package (an ORM client such as `@prisma/client`, an API
+   SDK), check that the app's `package.json` lists it under
+   `dependencies`. Build-time tools (the `prisma` CLI, `typescript`) stay
+   in `devDependencies`. `kindgi dev` warns as soon as a tool imports one
+   ("⚠ The pack imports @prisma/client (in kindgi/tools/…), which
+   package.json lists only in devDependencies: …"), and `kindgi build`
+   refuses the pack until it moves.
+10. **A tool that needs the app's install scripts in the image.** The
+    image installs with scripts off, so the app's `postinstall` /
+    `prepare` (`prisma generate`, husky) don't run there; `kindgi build`
+    lists them ("✓ The app's own install scripts don't run in the image:
+    …"). A tool that uses Prisma's client then fails the build ("@prisma/client
+    did not initialize yet"). Add `prisma({ schema: 'prisma/schema.prisma' })`
+    (from `@kindgi/sdk/build`; add `config: 'prisma.config.ts'` when the app
+    has one) to `image.extensions` in `kindgi.config.ts`. Other generate
+    steps: `defineBuildExtension({ name, contextFiles, postInstall: [{ bin, args }] })`.
+    Debian packages: `image.systemPackages`. Placeholder env for those steps:
+    `image.buildEnv` (never secrets).
+
 ## References
 
 - Type surface: `hover any @kindgi/sdk/define export` in your editor
   for full JSDoc — every field on `DefineToolSpec` / `ToolManifest`
   documents purpose, when to set it, and gotchas.
-- Companion docs: `pnpm --filter @kindgi/sdk exec typedoc` regenerates
-  markdown API docs at `packages/sdk/docs/`.
+- API reference: https://docs.kindgi.com/v0.1/reference/typescript/sdk/kindgi/sdk/define/ (every `define*` spec, field by field).
 - Common patterns: check the `sample` template (`kindgi init
   --template=sample`) for working examples of both authoring modes.
 

package/skills/kindgi-getting-started/SKILL.md

@@ -14,7 +14,7 @@ description: >
   primitive.
 type: core
 library: "@kindgi/sdk"
-version: "0.3.2"
+version: "0.3.5"
 sdk_version: "0.0.0"
 pack_languages: [node]
 ---
@@ -70,7 +70,9 @@ pnpm install          # or the app's own package manager
 
 This adds `kindgi.config.ts` and a `kindgi/` folder beside the app's code,
 and never creates env files: `kindgi dev` reads the app's own `.env` /
-`.env.local`.
+`.env.local`. A package a tool imports must be in the app's `dependencies`,
+not `devDependencies`: the deployed pack installs production dependencies
+only (see `kindgi-authoring-tools`).
 
 Either way, `init` adds `@kindgi/sdk` and `@kindgi/cli` to the project's
 `package.json`, so the project runs the `kindgi` it pins — never a global
@@ -95,22 +97,28 @@ needs on first run), indexes the pack, registers every primitive, and
 re-registers on every save. The banner prints the API URL, the seeded
 bearer token, and (if the console is bundled) the `/console/` URL.
 
-The local runtime includes a built-in `demo.echo-agent` you can hit to
-verify the harness before authoring anything.
+Until a model provider is registered, agents answer with `dev-echo`, a
+stand-in that calls the agent's first tool with `{"message": <userMessage>}`
+and replies with what the tool returned. It checks the wiring only: it can't
+fill in any other tool input or produce a typed `output` (that turn fails
+with `output-schema-violation`). Register a provider
+(`kindgi-authoring-providers`) before building a real agent.
 
 ## First run
 
 From a second terminal, with `cd my-pack`:
 
 ```bash
-pnpm exec kindgi runs start --agent=demo.echo-agent --input='{"userMessage":"hi"}'
+pnpm exec kindgi runs start --agent=my-pack.echo-agent --input='{"userMessage":"hi"}'
 ```
 
+`my-pack.echo-agent` is the agent the `sample` template ships (`<pack-id>.echo-agent`);
+a `minimal` pack has no agent until you write one.
+
 The CLI reads `.kindgirc.json` (auto-written by `kindgi dev`) for the
 API URL + token, so second-terminal commands work without flags.
 
-Once you author your own agent, replace `demo.echo-agent` with your
-own id.
+Once you author your own agent, run it by its own id.
 
 ## Layout
 
@@ -153,6 +161,48 @@ Most of the setup is automatable, but two require your knowledge:
   registered — `kindgi providers register --preset=anthropic` with the
   key in `.env`; see `kindgi-authoring-providers`.
 
+## Your app and Kindgi's data
+
+When the app keeps something a run did (a ticket a flow triaged, an answer
+an agent gave), its own row stores the run's id, in a column such as
+`kindgi_run_id`. The app starts the run and reads the rest through the API,
+server side, with `createClient()` from `@kindgi/sdk/client`:
+
+```ts
+import { createClient } from '@kindgi/sdk/client';
+
+const kindgi = createClient(); // KINDGI_API_URL + KINDGI_API_TOKEN
+const run = await kindgi.runs.start({
+  flow: 'my-pack.triage-ticket',
+  input: { ticketId },
+  options: { wait: false }, // the run id now; run.finished tells you when it ends
+});
+// save run.id as the ticket's kindgi_run_id
+```
+
+
+- **Status, output, timing:** `kindgi.runs.get(runId)`
+  (`GET /v1/runs/{runId}`); status and timing only: `kindgi.runs.progress(runId)`.
+- **The audit, step by step:** `kindgi.runs.journal(runId)`
+  (`GET /v1/runs/{runId}/journal`).
+- **Where an agent's answer came from:** `kindgi.provenance.get(runId)`
+  (`GET /v1/provenance/{runId}`). A flow run has none of its own: each agent
+  step's `step.completed` entry in the flow's journal names its turn's run
+  (`payload.output.runId`).
+- **When a run finished:** the `run.finished` webhook (the run's id and
+  outcome, no output; then `runs.get`), not polling.
+
+Show it in the app's own UI. **Never:**
+
+- **query Kindgi's database**, even on the app's own Postgres server, and
+  never map its tables into the app's ORM. Its schema is private and changes
+  with every release (migrations only go forward), row-level security guards
+  every tenant query, and a runtime Kindgi hosts gives no database access.
+- **link users to Kindgi's console** or any Kindgi UI for this data.
+
+To keep a copy (reporting, search), pull it through the API into the app's
+own tables. Docs: https://docs.kindgi.com/v0.1/guides/runs/show-runs-in-your-app/
+
 ## References
 
 - Full CLI surface: `kindgi --help`.

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

@@ -16,7 +16,7 @@ description: >
   kindgi-python-authoring-agents.
 type: core
 library: "kindgi (Python)"
-version: "0.1.0"
+version: "0.1.1"
 sdk_version: "0.0.0"
 pack_languages: [python]
 sources:
@@ -200,9 +200,11 @@ the condition is true. Conditions are dicts:
 | `and` `or` | `{"op", "children": [...]}` |
 | `not` | `{"op", "child"}` |
 
-Each operand is `{"literal": …}` or `{"path": …}`. A comparison whose
-path doesn't resolve is **false**, `ne` included. So to branch on "not
-billing", write `not` around the `eq` (as above), not `ne`. A condition
+Each operand is `{"literal": …}` or `{"path": …}`. When a path doesn't
+resolve, `eq`, `lt`, `lte`, `gt` and `gte` are false and `ne` is true. So
+for the "otherwise" branch, write `not` around the condition (as above),
+rather than a second comparison: it covers exactly what the first edge
+doesn't. A condition
 used twice is easiest as a module-level constant (`IS_BILLING`).
 
 **Joining branches.** A node with several incoming edges runs once every
@@ -227,7 +229,7 @@ A node with several incoming edges ignores them.
 Its keys are the tool's input **as it travels**: a pydantic field's name,
 or its alias if it has one (a `customer_id` field is the key
 `customer_id`; with `alias="customerId"`, it's `customerId`). Paths are
-dot-separated, with no array indexing, rooted at:
+dot-separated (a number segment indexes an array: `items.0.sku`), rooted at:
 - `runInput.…`: the input the run was started with;
 - `nodeOutputs.<nodeId>.…`: a step's output. For an agent step, add
   `.output.<field>` to read its typed answer;
@@ -289,9 +291,10 @@ the output), not on every save.
 1. **Building a flow without asking what goes in and comes out.** The
    pack's `echo_flow` proves the runtime works. It isn't a template for
    the user's flow.
-2. **`ne` on a path that may be missing, to mean "otherwise".** A missing
-   path makes every comparison false, so neither branch fires and
-   everything after is skipped. Use `not` around the positive condition.
+2. **A second comparison for "otherwise".** On a path that may be
+   missing, `eq` is false and `ne` is true, and `lt`/`gt` are both false,
+   so a hand-written opposite can miss a case or overlap. Use `not` around
+   the positive condition: it covers exactly what the first edge doesn't.
 3. **Reading an agent step's answer at `nodeOutputs.<step>.<field>`.**
    The typed answer is under `.output`: `nodeOutputs.<step>.output.<field>`.
    An agent without `output=` has only `text`.

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

@@ -14,7 +14,7 @@ description: >
   kindgi-python-authoring-tools.
 type: core
 library: "kindgi (Python)"
-version: "0.1.0"
+version: "0.1.1"
 sdk_version: "0.0.0"
 pack_languages: [python]
 sources:
@@ -106,7 +106,9 @@ def no_fabricated_quotes(config: Config, trace: RunTrace) -> CheckResult:
   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.
+  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), `"critical"`.
   Independent of the action: dashboards group by severity, execution
   follows the action.
@@ -147,8 +149,9 @@ brief_writer = Agent(..., guardrails=[no_fabricated_quotes])
 ```
 
 The `Guardrail` object (or its id). `kindgi dev` registers the pack's
-guardrails; an agent naming an id with no registered guardrail fails
-its turn (`unresolved-guardrail`).
+guardrails; an agent naming an id with no registered guardrail fails the
+turn before the model is called (`Error [invalid-request]: Agent "…"
+references guardrails not in the registry: <id>`).
 
 ## Common mistakes
 
@@ -158,8 +161,8 @@ its turn (`unresolved-guardrail`).
 2. **Snake_case keys in `config=`.** It is keyed like the wire — the
    model's aliases (`{"minLookups": 2}`), not the field names.
 3. **Both `on_violation=` and `action=`, or neither** — `DefinitionError`.
-4. **Expecting retries from `halt`.** `halt` stops the turn; use
-   `action={"on-violation": "retry", …}` for another attempt.
+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.** Not available; keep checks pure.
 6. **Raising for a broken rule.** Return `CheckResult(passed=False,
    reason=…)`; an exception is an evaluation error, not a violation.

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.0"
+version: "0.1.1"
 sdk_version: "0.0.0"
 pack_languages: [python]
 sources:
@@ -290,6 +290,12 @@ removed field, a narrower type — not on every save.
    and an agent's tool approval gate asks before it on first use.
 10. **`mutating=False` on a tool that writes.** A dry run then runs it
     for real.
+11. **A package a tool imports, only in a dev group.** The deployed pack
+    installs without dev dependencies (`uv sync --no-dev`, or Poetry's
+    main group only), so the import works under `kindgi dev` and fails in
+    the image. Put what tools import in `[project].dependencies` (in a
+    Poetry 1 app, `[tool.poetry.dependencies]`); test and build tools stay
+    in dev groups.
 
 ## When the framework itself is the problem
 

package/skills/kindgi-python-getting-started/SKILL.md

@@ -14,7 +14,7 @@ description: >
   kindgi-python-authoring-agents; models by kindgi-authoring-providers.
 type: core
 library: "kindgi (Python)"
-version: "0.1.0"
+version: "0.1.3"
 sdk_version: "0.0.0"
 pack_languages: [python]
 sources:
@@ -26,7 +26,7 @@ sources:
 # Getting started with Kindgi in Python
 
 > **Running `kindgi`:** a Python pack has no Node project, so the
-> `kindgi` CLI (a Node 22+ program) is the one on `PATH`. Python
+> `kindgi` CLI (a Node 22.12+ program) is the one on `PATH`. Python
 > commands run in the pack's environment: `uv run …`.
 
 ## What a pack is
@@ -90,7 +90,9 @@ name (`from acme.text import normalize`); inside `kindgi/`, import the pack's
 modules relatively. Don't add an `__init__.py` to `kindgi/` — the folder
 would then shadow the `kindgi` package. `kindgi dev` reads the app's `.env`
 / `.env.local` — keys already there reach the tools as environment
-variables.
+variables. A package a tool imports must be in the app's main dependencies,
+not a dev group: the deployed pack installs without dev dependencies (see
+`kindgi-python-authoring-tools`).
 
 ## Layout of the template
 
@@ -180,6 +182,37 @@ for event in client.runs.stream(str(run.id)):
 `AsyncKindgi` is the asyncio twin. `kindgi dev` prints the URL and the
 token; `.kindgirc.json` in the pack holds them for the CLI.
 
+## Your app and Kindgi's data
+
+When the app keeps something a run did (a ticket a flow triaged, an answer
+an agent gave), its own row stores the run's id, in a column such as
+`kindgi_run_id` (`run = client.runs.start(flow=…, input=…, options={"wait": False})`,
+then `run.id`). The app reads the rest through the API, server side, with
+`Kindgi()` from `kindgi.client`:
+
+- **Status, output, timing:** `client.runs.get(run_id)`
+  (`GET /v1/runs/{runId}`); status and timing only: `client.runs.progress(run_id)`.
+- **The audit, step by step:** `client.runs.journal(run_id).data`
+  (`GET /v1/runs/{runId}/journal`).
+- **Where an agent's answer came from:** `client.provenance.get(run_id)`
+  (`GET /v1/provenance/{runId}`). A flow run has none of its own: each agent
+  step's `step.completed` entry in the flow's journal names its turn's run
+  (`entry.payload["output"]["runId"]`).
+- **When a run finished:** the `run.finished` webhook (the run's id and
+  outcome, no output; then `runs.get`), not polling.
+
+Show it in the app's own UI. **Never:**
+
+- **query Kindgi's database**, even on the app's own Postgres server, and
+  never map its tables into the app's ORM (SQLAlchemy, Django models). Its
+  schema is private and changes with every release (migrations only go
+  forward), row-level security guards every tenant query, and a runtime
+  Kindgi hosts gives no database access.
+- **link users to Kindgi's console** or any Kindgi UI for this data.
+
+To keep a copy (reporting, search), pull it through the API into the app's
+own tables. Docs: https://docs.kindgi.com/v0.1/guides/runs/show-runs-in-your-app/
+
 ## Build an image
 
 `kindgi build --env=<name>` (an `[tool.kindgi.environments.<name>]`

package/src/client.ts

@@ -21,9 +21,39 @@
  */
 
 // ---- Client factory + top-level shape ----
-export { createClient } from '@kindgi/client';
+import { createClient as createKindgiClient } from '@kindgi/client';
+import type { ClientOptions, KindgiClient } from '@kindgi/client';
+
+import { resolveClientOptions } from './runtime-config.js';
+
 export type { KindgiClient } from '@kindgi/client';
 
+/**
+ * A client for the app's Kindgi runtime. Every option is optional:
+ *
+ * - `apiUrl` and `auth` come from `KINDGI_API_URL` and `KINDGI_API_TOKEN`;
+ * - outside production, when those aren't set, from the running
+ *   `kindgi dev` (the nearest `.kindgirc.json`), with a one-time warning to
+ *   put them in the app's env file;
+ * - a token that doesn't match the running `kindgi dev`'s for the same
+ *   `apiUrl` (after `kindgi dev --reset`) is warned about once.
+ *
+ * Production (`NODE_ENV` or `KINDGI_ENV` = `production`) never reads
+ * `.kindgirc.json`: there, the env or explicit options must say. In a
+ * browser, pass `apiUrl` and `auth`. `@kindgi/client`'s `createClient` is
+ * the explicit form underneath.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from '@kindgi/sdk/client';
+ *
+ * const kindgi = createClient();
+ * ```
+ */
+export function createClient(options: Partial<ClientOptions> = {}): KindgiClient {
+  return createKindgiClient(resolveClientOptions(options));
+}
+
 // ---- Resource client types + per-resource input shapes ----
 export type {
   AdapterConfigureInput,

package/src/runtime-config.ts

@@ -0,0 +1,180 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Where an app's client finds its Kindgi runtime when `createClient` is
+ * called without `apiUrl` / `auth`:
+ *
+ *   1. `KINDGI_API_URL` and `KINDGI_API_TOKEN` from the environment;
+ *   2. outside production, the running `kindgi dev`, from the nearest
+ *      `.kindgirc.json` at or above the working directory (it records the
+ *      runtime's `apiUrl` and the dev `token`), with a one-time warning to
+ *      put them in the app's env file;
+ *   3. otherwise, an error that says what to set.
+ *
+ * Production (`NODE_ENV` or `KINDGI_ENV` set to `production`) never reads
+ * `.kindgirc.json`. Whatever the source, a token that differs from the
+ * running `kindgi dev`'s for the same `apiUrl` (the stale token after
+ * `kindgi dev --reset`) is warned about once.
+ *
+ * Node only: the file is read through `process.getBuiltinModule`, never a
+ * static `node:` import, so the module stays safe to bundle for browsers,
+ * where only explicit options apply.
+ */
+
+import type { AuthConfig, ClientOptions } from '@kindgi/client';
+
+/** The file `kindgi dev` writes in the pack directory. */
+export const DEV_RUNTIME_FILE = '.kindgirc.json';
+
+/** What a client needs from a running `kindgi dev`. */
+export interface DevRuntime {
+  readonly apiUrl: string;
+  readonly token: string;
+  /** The `.kindgirc.json` it came from. */
+  readonly path: string;
+}
+
+/** Where the lookup runs: the process's own environment by default (tests pass their own). */
+export interface RuntimeConfigContext {
+  readonly env: Readonly<Record<string, string | undefined>>;
+  /** The directory the `.kindgirc.json` search starts from. */
+  readonly cwd: string | undefined;
+  readonly warn: (message: string) => void;
+}
+
+const ENV_FILE_HINT = 'your env file (.env / .env.local)';
+
+const warned = new Set<string>();
+
+function warnOnce(context: RuntimeConfigContext, key: string, message: string): void {
+  if (warned.has(key)) return;
+  warned.add(key);
+  context.warn(`[kindgi] ${message}`);
+}
+
+export function defaultContext(): RuntimeConfigContext {
+  const proc = typeof process === 'undefined' ? undefined : process;
+  return {
+    env: proc?.env ?? {},
+    cwd: typeof proc?.cwd === 'function' ? proc.cwd() : undefined,
+    warn: (message) => console.warn(message),
+  };
+}
+
+export function isProduction(env: RuntimeConfigContext['env']): boolean {
+  return env.NODE_ENV === 'production' || env.KINDGI_ENV === 'production';
+}
+
+/**
+ * The client options with every missing field resolved (see the module
+ * comment). Throws when no `apiUrl` or no token can be found.
+ */
+export function resolveClientOptions(
+  options: Partial<ClientOptions>,
+  context: RuntimeConfigContext = defaultContext(),
+): ClientOptions {
+  const { env } = context;
+  const dev = isProduction(env) ? undefined : findDevRuntime(context.cwd);
+
+  let apiUrl = options.apiUrl ?? nonEmpty(env.KINDGI_API_URL);
+  let auth: AuthConfig | undefined =
+    options.auth ??
+    (nonEmpty(env.KINDGI_API_TOKEN) !== undefined
+      ? { kind: 'apiToken', token: env.KINDGI_API_TOKEN as string }
+      : undefined);
+
+  if ((apiUrl === undefined || auth === undefined) && dev !== undefined) {
+    const used: string[] = [];
+    if (apiUrl === undefined) {
+      apiUrl = dev.apiUrl;
+      used.push('KINDGI_API_URL');
+    }
+    if (auth === undefined) {
+      auth = { kind: 'apiToken', token: dev.token };
+      used.push('KINDGI_API_TOKEN');
+    }
+    warnOnce(
+      context,
+      `fallback:${dev.path}`,
+      `Using the running kindgi dev from ${dev.path} for ${used.join(' and ')}. Set them in ${ENV_FILE_HINT}, and in production, where there's no ${DEV_RUNTIME_FILE}.`,
+    );
+  }
+
+  if (apiUrl === undefined || auth === undefined) {
+    const missing = [
+      ...(apiUrl === undefined ? ['KINDGI_API_URL'] : []),
+      ...(auth === undefined ? ['KINDGI_API_TOKEN'] : []),
+    ];
+    throw new Error(
+      `createClient(): ${missing.join(' and ')} ${missing.length === 1 ? "isn't" : "aren't"} set. Set ${missing.length === 1 ? 'it' : 'them'} in ${ENV_FILE_HINT}, or pass { apiUrl, auth }.${
+        isProduction(env)
+          ? ''
+          : ` In development, run \`kindgi dev\` in the app: it writes them to ${DEV_RUNTIME_FILE}, which the client reads.`
+      }`,
+    );
+  }
+
+  if (dev !== undefined && auth.kind === 'apiToken' && auth.token !== dev.token) {
+    if (sameUrl(apiUrl, dev.apiUrl)) {
+      warnOnce(
+        context,
+        `stale:${dev.path}:${dev.token}`,
+        `The API token doesn't match the running kindgi dev's (${dev.path}). After \`kindgi dev --reset\` the token changes: copy the new one into ${ENV_FILE_HINT}.`,
+      );
+    }
+  }
+
+  return { ...options, apiUrl, auth };
+}
+
+/**
+ * The running `kindgi dev`'s `apiUrl` and `token`, from the nearest
+ * `.kindgirc.json` at or above `from`; `undefined` when there's none, it
+ * can't be read, or the runtime can't read files (a browser).
+ */
+export function findDevRuntime(from: string | undefined): DevRuntime | undefined {
+  if (from === undefined) return undefined;
+  const fs = builtin<typeof import('node:fs')>('node:fs');
+  const path = builtin<typeof import('node:path')>('node:path');
+  if (fs === undefined || path === undefined) return undefined;
+  for (let dir = from; ; dir = path.dirname(dir)) {
+    const candidate = path.join(dir, DEV_RUNTIME_FILE);
+    if (fs.existsSync(candidate)) return readDevRuntime(fs, candidate);
+    if (path.dirname(dir) === dir) return undefined;
+  }
+}
+
+function readDevRuntime(fs: typeof import('node:fs'), file: string): DevRuntime | undefined {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8')) as Record<string, unknown>;
+    const apiUrl = parsed.apiUrl;
+    const token = parsed.token;
+    if (typeof apiUrl !== 'string' || apiUrl === '' || typeof token !== 'string' || token === '') {
+      return undefined;
+    }
+    return { apiUrl, token, path: file };
+  } catch {
+    return undefined;
+  }
+}
+
+function builtin<T>(id: string): T | undefined {
+  const proc = typeof process === 'undefined' ? undefined : process;
+  const get = (proc as { getBuiltinModule?: (id: string) => unknown } | undefined)
+    ?.getBuiltinModule;
+  return typeof get === 'function' ? (get.call(proc, id) as T | undefined) : undefined;
+}
+
+function nonEmpty(value: string | undefined): string | undefined {
+  return value === undefined || value === '' ? undefined : value;
+}
+
+function sameUrl(a: string, b: string): boolean {
+  return a.replace(/\/+$/, '') === b.replace(/\/+$/, '');
+}
+
+/** Tests only: forget which warnings were printed. */
+export function resetWarningsForTests(): void {
+  warned.clear();
+}