@kindgi/sdk 0.0.0-bootstrap.0 → 0.1.1

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/dist/types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `@kindgi/sdk/types` — branded IDs, framework-wide result envelope,
+ * pagination, refs, temporal + version primitives.
+ *
+ * Re-exports types from `@kindgi/types` under their own names. These
+ * are the workspace-wide identifiers callers pass across the SDK
+ * boundary.
+ *
+ * The /types sub-path is where branded identifiers live in the public
+ * facade.
+ *
+ * @module @kindgi/sdk/types
+ */
+export type { BlobRef, Brand, ContentHash, Cursor, DatasetRef, DurationMs, ErrOf, Filter, IsoDuration, OkOf, Page, Result, SchemaMajor, Semver, SignatureValue, Timestamp, VersionedRef, } from '@kindgi/types';
+export type { AgentId, ApiTokenId, ApprovalId, ArtifactId, AuditBundleId, ComplianceEvidenceId, ConversationId, DatasetId, EdgeId, EventId, FactId, FixProposalId, FlowId, InstallationId, GuardrailId, KeyId, LogEntryId, NodeId, ObservationId, OrgId, PackId, PolicyId, ProjectId, ProvenanceId, ProviderId, ReviewerId, RunId, ScheduleId, SessionId, SigningKeyId, SubscriptionId, SupervisorId, TeamId, TenantId, ThreadId, ToolId, TriggerId, UserId, WaitTokenId, WebhookDeliveryId, WebhookId, } from '@kindgi/types';
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AAEH,YAAY,EACV,OAAO,EACP,KAAK,EACL,WAAW,EACX,MAAM,EACN,UAAU,EACV,UAAU,EACV,KAAK,EACL,MAAM,EACN,WAAW,EACX,IAAI,EACJ,IAAI,EACJ,MAAM,EACN,WAAW,EACX,MAAM,EACN,cAAc,EACd,SAAS,EACT,YAAY,GACb,MAAM,eAAe,CAAC;AAQvB,YAAY,EACV,OAAO,EACP,UAAU,EACV,UAAU,EACV,UAAU,EACV,aAAa,EACb,oBAAoB,EACpB,cAAc,EACd,SAAS,EACT,MAAM,EACN,OAAO,EACP,MAAM,EACN,aAAa,EACb,MAAM,EACN,cAAc,EACd,WAAW,EACX,KAAK,EACL,UAAU,EACV,MAAM,EACN,aAAa,EACb,KAAK,EACL,MAAM,EACN,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,UAAU,EACV,UAAU,EACV,KAAK,EACL,UAAU,EACV,SAAS,EACT,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,MAAM,EACN,SAAS,EACT,MAAM,EACN,WAAW,EACX,iBAAiB,EACjB,SAAS,GACV,MAAM,eAAe,CAAC"}

package/dist/types.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC"}

package/dist/webhooks.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `@kindgi/sdk/webhooks` — receiving Kindgi's webhooks. Server only: it
+ * uses `node:crypto`, so it stays out of `/client` (browser-safe) and the
+ * flat barrel.
+ *
+ * Re-exports the Standard Webhooks helpers from `@kindgi/crypto`:
+ * `verifyWebhook` for a receiver, `generateWebhookSecret` for the secret an
+ * app registers by name, and `signWebhook` / `webhookHeaders` to test a
+ * receiver.
+ *
+ * @module @kindgi/sdk/webhooks
+ */
+export { DEFAULT_WEBHOOK_TOLERANCE_SECONDS, generateWebhookSecret, isStrongWebhookSecret, signWebhook, verifyWebhook, WEBHOOK_HEADERS, WEBHOOK_SECRET_MIN_BYTES, WEBHOOK_SECRET_PREFIX, webhookHeaders, } from '@kindgi/crypto';
+export type { SignWebhookInput, VerifyWebhookFailure, VerifyWebhookInput, VerifyWebhookResult, WebhookRequestHeaders, } from '@kindgi/crypto';
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,iCAAiC,EACjC,qBAAqB,EACrB,qBAAqB,EACrB,WAAW,EACX,aAAa,EACb,eAAe,EACf,wBAAwB,EACxB,qBAAqB,EACrB,cAAc,GACf,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC"}

package/dist/webhooks.js

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * `@kindgi/sdk/webhooks` — receiving Kindgi's webhooks. Server only: it
+ * uses `node:crypto`, so it stays out of `/client` (browser-safe) and the
+ * flat barrel.
+ *
+ * Re-exports the Standard Webhooks helpers from `@kindgi/crypto`:
+ * `verifyWebhook` for a receiver, `generateWebhookSecret` for the secret an
+ * app registers by name, and `signWebhook` / `webhookHeaders` to test a
+ * receiver.
+ *
+ * @module @kindgi/sdk/webhooks
+ */
+export { DEFAULT_WEBHOOK_TOLERANCE_SECONDS, generateWebhookSecret, isStrongWebhookSecret, signWebhook, verifyWebhook, WEBHOOK_HEADERS, WEBHOOK_SECRET_MIN_BYTES, WEBHOOK_SECRET_PREFIX, webhookHeaders, } from '@kindgi/crypto';
+//# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,iCAAiC,EACjC,qBAAqB,EACrB,qBAAqB,EACrB,WAAW,EACX,aAAa,EACb,eAAe,EACf,wBAAwB,EACxB,qBAAqB,EACrB,cAAc,GACf,MAAM,gBAAgB,CAAC"}

package/package.json

@@ -1,7 +1,91 @@
 {
   "name": "@kindgi/sdk",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Placeholder so a trusted publisher can be attached. Releases are published from https://github.com/kindgi/kindgi-sdk with provenance; use 0.1.0 or later.",
+  "version": "0.1.1",
+  "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": { "type": "git", "url": "git+https://github.com/kindgi/kindgi-sdk.git" }
-}
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kindgi/kindgi-sdk.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://github.com/kindgi/kindgi-sdk/tree/main/packages/sdk#readme",
+  "bugs": {
+    "url": "https://github.com/kindgi/kindgi-sdk/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./define": {
+      "types": "./dist/define.d.ts",
+      "import": "./dist/define.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    },
+    "./webhooks": {
+      "types": "./dist/webhooks.d.ts",
+      "import": "./dist/webhooks.js"
+    },
+    "./build": {
+      "types": "./dist/build.d.ts",
+      "import": "./dist/build.js"
+    },
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "skills",
+    "README.md"
+  ],
+  "dependencies": {
+    "@kindgi/agents": "0.1.1",
+    "@kindgi/client": "0.1.1",
+    "@kindgi/crypto": "0.1.1",
+    "@kindgi/flow": "0.1.1",
+    "@kindgi/guardrails": "0.1.1",
+    "@kindgi/handler-runtime": "0.1.1",
+    "@kindgi/schema": "0.1.1",
+    "@kindgi/tools": "0.1.1",
+    "@kindgi/types": "0.1.1"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "typedoc": "^0.28.20",
+    "typedoc-plugin-markdown": "^4.13.1",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "docs": "typedoc",
+    "clean": "rm -rf dist docs *.tsbuildinfo"
+  }
+}

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

@@ -0,0 +1,252 @@
+---
+name: kindgi-authoring-agents
+description: >
+  Covers writing agents for a Kindgi pack with @kindgi/sdk:
+  defining agents via defineAgent, tool wiring with ToolRef versioning,
+  guardrail references, conversation policy, turn budgets, LLM
+  capability declarations, and prompt template variables. Load this
+  whenever you are authoring or editing code inside a pack's agents/
+  directory, defining an agent, or when the user asks to add, modify,
+  or refactor an agent. Authoring tools is covered by
+  kindgi-authoring-tools; authoring guardrails is covered by
+  kindgi-authoring-guardrails.
+type: core
+library: "@kindgi/sdk"
+version: "0.4.2"
+sdk_version: "0.0.0"
+pack_languages: [node]
+sources:
+  - packages/agents/src/types.ts
+  - packages/agents/src/define.ts
+---
+
+# Authoring Kindgi agents
+
+> **Running `kindgi`:** the CLI is a devDependency of the project (`@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 …`. Commands below are written `kindgi …` for brevity.
+
+An **agent** is a versioned LLM-powered orchestrator: instructions (a
+prompt template), a declared set of tools it can call, capability
+declarations for the LLM provider, guardrails that gate its outputs,
+and optional multi-turn conversation policy. Agents live at
+`agents/<name>/index.ts` inside a pack.
+
+## Ask before building
+
+Requests like "add an agent" / "create an agent" / "I need an agent"
+are conversation openers, not tickets. Before writing any file, ask:
+
+- **What should the agent DO?** The purpose is the load-bearing thing.
+  Everything else derives from it.
+- **Which tools does it need?** New tools, or reuses of existing?
+- **Multi-turn or one-shot?** Conversation history changes the shape.
+- **Any specific guardrails?** Safety rules the agent must respect.
+
+The pack's existing agents are examples that prove the framework runs
+end-to-end. They are NOT the shape you imitate unless the user
+explicitly asks for that. Inferring purpose from surrounding pack
+shape is how confident, wrong code gets shipped.
+
+## Minimal agent
+
+```ts
+// agents/brief-writer/index.ts
+import { defineAgent } from '@kindgi/sdk/define';
+import type { AgentId, Semver } from '@kindgi/sdk/types';
+
+const defined = defineAgent({
+  id: 'acme.brief-writer' as AgentId,
+  version: '0.1.0' as Semver,
+  name: 'Brief Writer',
+  description:
+    'Drafts appellate briefs from a case file. Cites precedents; escalates novel legal questions.',
+  instructions:
+    'You are drafting a brief in {{ jurisdiction }}. The user provides the case facts; you produce a Section IV argument citing at least two precedents. Use `acme.verify-citation` on every cite before including it. Refuse to fabricate citations — always call the tool.',
+  capabilities: [{ needs: [{ feature: 'tool-use' as const }] }],
+  tools: [
+    { id: 'acme.verify-citation', version: '^0.1.0' },
+    { id: 'acme.fetch-precedent', version: '^0.1.0' },
+  ],
+  retrieval: [],
+  guardrails: ['acme.no-fabricated-quotes'],
+  parameters: [
+    { name: 'jurisdiction', type: 'string', required: true },
+  ],
+  conversationPolicy: { historyLimit: 20 },
+  budget: { maxSteps: 8, maxCostUsd: 0.5, maxWallMs: 60_000 },
+});
+
+if (defined.kind === 'err') {
+  throw new Error(`acme.brief-writer failed to compile: ${defined.error.message}`);
+}
+
+export default defined.value;
+```
+
+## Field-by-field
+
+- **`id`** — `<pack-id>.<agent-name>` (kebab-case, dot-namespaced).
+  Enforced.
+- **`version`** — Semver. Runs pin to a specific version; upgrading
+  the agent doesn't retroactively rewrite in-flight conversations.
+- **`instructions`** — LiquidJS template. `{{ variable }}` substitutes
+  from `parameters` or framework auto-vars (`today`, `now`, `agent.*`,
+  `conversation.*`). Rendered with `strictVariables: true` — unresolved
+  references fail loudly at invoke time. Frame instructions like a
+  competent employee brief: what the agent does, what tools to prefer,
+  what to refuse, what quality bar to hit.
+- **`capabilities`** — declares the resource kinds the agent needs at
+  runtime. `{feature: 'tool-use'}` is standard for tool-calling
+  agents. The router picks the concrete LLM provider at turn time.
+- **`tools`** — `readonly ToolRef[]`, NOT `string[]`. Each entry is
+  `{id, version}` where `version` is an npm-style semver **range**
+  (`'^0.1.0'`, `'~1.2.3'`, `'>=1.0.0 <2.0.0'`). Empty array = chat-only
+  agent.
+- **`guardrails`** — array of guardrail `id` strings. Resolved at turn
+  start against the guardrails bound for the run (the tenant's
+  registered guardrails). If a guardrail id isn't registered, the turn
+  fails with `unresolved-guardrail`. Guardrails are evaluated once per
+  turn, on the final response before it is stored — a blocking
+  (`halt`) violation fails the turn and the response is never written
+  to the conversation.
+- **`parameters`** — typed inputs the caller supplies at invoke time.
+  UI builds a "configure agent" form from these; runtime validates
+  each required parameter is provided.
+- **`preferredProvider`** — optional soft hint. When set to a
+  `ProviderMetadata.id` (e.g. `'anthropic'`, `'groq'`), the router
+  prefers that provider when at least one of its models satisfies the
+  agent's `capabilities.needs` + tenant policy. Falls back to normal
+  capability-based selection when the preferred provider is
+  unregistered or filtered out.
+- **`preferredModel`** — optional soft hint at the model level: set to
+  a `ModelInfo.name` (e.g. `'gemini-2.5-pro'`), the router prefers
+  `(provider, model)` tuples whose model matches. To require a model
+  rather than prefer it, add a hard requirement to the capability:
+  `capabilities: [{ needs: [{ feature: 'tool-use' }, { models: { allow: ['gemini-2.5-pro'] } }] }]`.
+- **`conversationPolicy`** — optional. Absent = each turn loads the
+  conversation's full history and no HITL gates apply. `historyLimit`
+  caps how many prior messages are loaded; `hitl` configures approval
+  gates (a turn-count gate and per-tool gates). A tenant's `hitl`
+  policy can tighten these — a shorter approval timeout, a higher
+  reviewer role, a stricter gate for a tool — never loosen them.
+- **`budget`** — per-turn ceiling. `maxSteps` caps model-call cycles
+  (default 8); `maxCostUsd` caps model spend; `maxWallMs` caps wall
+  time (default 120 000). Exceeding steps or cost fails the turn with
+  `budget-exceeded`; running out of wall time aborts it
+  (`agent-turn-aborted`, reason `timeout`).
+
+- **`output`** — optional typed result: `{ schema, name?, maxRepairs? }`
+  (JSON Schema, or Zod). The final answer must be JSON matching
+  `schema` (a fenced JSON block is accepted). An answer that doesn't fit
+  goes back to the model with the problems listed, up to `maxRepairs`
+  times (default 1); then the turn fails with `output-schema-violation`.
+  The parsed answer is the turn result's `output`, and in a flow
+  `nodeOutputs.<step>.output.<field>`. A Zod `.default()` field must be
+  in the answer: downstream steps read every field.
+- **`toolErrors`** — optional: what the turn does when a tool call
+  fails. The failure goes back to the model as the call's result (what
+  failed and why) so it can correct the call, up to `maxRetries` times
+  per turn (default 1), for the kinds in `retryOn` (default
+  `['invalid-arguments', 'unknown-tool']`, failures where nothing ran).
+  Add `'tool-error'` to retry a tool that ran and failed — only when
+  retrying it is safe (a mutating tool may have changed something before
+  failing). Each retry costs a step against `budget.maxSteps`. Past the
+  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.
+
+## What a turn receives
+
+- **Run directly** (`kindgi runs start --agent=… --input='{…}'`, or
+  `POST /v1/runs { agent, input }`), the input is `{ userMessage,
+  conversationId?, participantId?, parameters? }`:
+  - `userMessage` is the turn's message;
+  - `conversationId` continues a conversation;
+  - `parameters` fills the agent's `parameters` (string, number or
+    boolean values).
+- **As a flow step** (`{ kind: 'agent', ref: 'acme.brief-writer' }`), the
+  agent gets the step's input in two ways:
+  - as **structured input**, which the instructions read as
+    `{{ input.caseFacts }}`;
+  - as the user message (the input as JSON).
+
+  The step's `config.parameters` fills `parameters`, and `config.version`
+  pins a version. With a typed `output`, the flow reads the answer at
+  `nodeOutputs.<step>.output.<field>`. See `kindgi-authoring-flows`.
+
+`{{ input.* }}` is set only in a flow step, so an agent that reads it
+belongs in a flow. Rendering is strict: a direct run of such an agent
+fails when its instructions render.
+
+## Iterating on an agent
+
+Edit `agents/<name>/index.ts`, save. The next `kindgi runs start`
+sees the change — new instructions, new tool bindings, new
+capabilities, new preferredProvider, new budget. No version bump,
+no restart. Source is truth in dev.
+
+The `version` field is a **semver contract for humans reading the
+source** — it declares what conversations pinned to this agent can
+rely on. Bump because you're breaking that contract (removed a
+parameter, tightened the instructions in a user-visible way,
+switched to an incompatible provider policy), not because you saved
+the file. If you're iterating on the prompt, leave version alone.
+
+**When version matters:** conversations persist their `agentVersion`
+at start and pin resume-across-turn to that version. `kindgi deploy`
+publishes to a durable production registry that enforces the
+immutable `(id, version)` contract. Both surfaces are deploy-time
+concerns, not author-time.
+
+## Common mistakes
+
+1. **Adding an agent without asking what it should do.** The most
+   common failure mode. "Add an agent" without a stated purpose gets
+   answered by imitating the shape of the pack's example agent. Ask
+   first.
+
+2. **`tools: ['id-string']`** — `tools` is `ToolRef[]`, so TypeScript
+   rejects bare strings, and `defineAgent` returns `invalid-agent` for
+   one that slips through (plain JavaScript, a cast). Use
+   `[{id: 'acme.x', version: '^0.1.0'}]`.
+
+3. **Referencing guardrails that aren't registered.** If
+   `agent.guardrails` contains an id the tenant has no guardrail for
+   (registered via `POST /v1/guardrails`, a deploy, or `kindgi dev`),
+   turn setup fails with `unresolved-guardrail`. Either author the
+   guardrail first or drop it from the agent's list.
+
+4. **Un-declared `{{ variable }}` in instructions.** LiquidJS renders
+   with `strictVariables: true` — a reference to `{{ jurisdiction }}`
+   that isn't in `parameters` OR an auto-var throws at invoke time.
+   Either add it to `parameters` or use a framework auto-var.
+
+5. **Empty `capabilities`.** `defineAgent` rejects an empty
+   `capabilities` array (`invalid-agent`) — the turn routes its first
+   capability to pick a model. Declare
+   `[{needs: [{feature: 'tool-use' as const}]}]` (or the matching
+   feature set for your use case).
+
+6. **Missing `Result` unwrap.** `defineAgent` returns `Result<Agent,
+   InvalidAgentError>`. Always check `defined.kind === 'err' && throw`
+   so a broken agent fails at module load.
+
+## References
+
+- Type surface: `hover any @kindgi/sdk/define export` in your editor
+  for full JSDoc.
+- 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.
+
+## When the framework itself is the problem
+
+If you diagnose that the bug lives in Kindgi/`@kindgi/sdk` itself (SDK
+type drift, wire schema silently dropping a field like
+`preferredProvider`, router picking the wrong provider, misleading
+error message, CLI friction) — not in the pack's own code — load the
+`kindgi-framework-feedback` skill and file a structured report with
+`kindgi feedback write`. That diagnostic is high-signal input the
+maintainers can act on; don't let it disappear into the transcript.