@kindgi/cli 0.0.0-bootstrap.0 → 0.1.0

package/dist/templates/python/guardrails/response_not_empty.py.tmpl

@@ -0,0 +1,27 @@
+"""{{PACK_ID}}.response-not-empty — a zero-LLM guardrail: the run's answer has content."""
+
+from pydantic import BaseModel, Field
+
+from kindgi import CheckResult, RunTrace, guardrail
+
+
+class Config(BaseModel):
+    min_length: int = Field(1, alias="minLength", ge=0)
+
+
+@guardrail(
+    id="{{PACK_ID}}.response-not-empty",
+    name="Response is non-empty",
+    check_id="{{PACK_ID}}.checks.response-not-empty",
+    on_violation="halt",
+    severity="error",
+    scope={"when": "runtime-only"},
+)
+def response_not_empty(config: Config, trace: RunTrace) -> CheckResult:
+    text = (trace.output or "").strip()
+    if len(text) < config.min_length:
+        return CheckResult(
+            passed=False,
+            reason=f"Response too short: {len(text)} chars, expected >= {config.min_length}.",
+        )
+    return CheckResult(passed=True)

package/dist/templates/python/pyproject.toml.tmpl

@@ -0,0 +1,42 @@
+[project]
+name = "{{PACK_NAME}}"
+version = "{{PACK_VERSION}}"
+description = "A Kindgi pack — scaffolded by `kindgi init --template=python`."
+requires-python = ">=3.11"
+dependencies = [{{KINDGI_REQUIREMENT}}]
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+# The uv versions this pack works with: `kindgi build` installs it with the
+# uv in Kindgi's image, which reads the uv.lock they write.
+[tool.uv]
+required-version = "{{UV_REQUIRED_VERSION}}"
+{{KINDGI_PYTHON_SOURCE}}
+# The pack: what `kindgi dev`, `kindgi build` and `python -m kindgi.pack` read.
+[tool.kindgi.pack]
+id = "{{PACK_ID}}"
+version = "{{PACK_VERSION}}"
+description = "A sample Kindgi pack in Python — two tools, one guardrail, one agent, one flow."
+
+# Optional — the defaults are shown.
+# [tool.kindgi.discovery]
+# tools = "tools/**/*.py"
+# guardrails = "guardrails/**/*.py"
+# agents = "agents/**/*.py"
+# flows = "flows/**/*.py"
+
+# [tool.kindgi.dev]
+# python = ["uv", "run", "python"]   # default: .venv/bin/python, else python3
+# envFiles = [".env", ".env.local"]
+
+# One block per deploy target; `kindgi build --env=<name>` reads it.
+# [tool.kindgi.environments.staging]
+# endpoint = "https://api.staging.example.com"
+# build = "http://localhost:4001"
+# tenantId = "tenant-your-org-staging"
+# signingKey = "~/.kindgi/keys/staging.pem"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

package/dist/templates/python/tests/test_tools.py.tmpl

@@ -0,0 +1,22 @@
+"""The pack's tools and guardrail, called directly — `uv run pytest`."""
+
+from kindgi import RunTrace
+from tools.echo import EchoInput, echo
+from tools.greet import GreetInput, greet
+
+from guardrails.response_not_empty import Config, response_not_empty
+
+
+def test_echo_round_trips_the_message() -> None:
+    out = echo(EchoInput(message="hello"))
+    assert out.echo == "hello"
+    assert out.character_count == 5
+
+
+def test_greet_uses_the_default_greeting() -> None:
+    assert greet(GreetInput(name="Ada")).message == "Hello, Ada!"
+
+
+def test_an_empty_answer_fails_the_guardrail() -> None:
+    trace = RunTrace(run_id="r", tenant_id="t", output="  ")
+    assert not response_not_empty(Config(), trace).passed

package/dist/templates/python/tools/echo.py.tmpl

@@ -0,0 +1,27 @@
+"""{{PACK_ID}}.echo — echoes the message back with a UTC timestamp and its length."""
+
+from datetime import UTC, datetime
+
+from pydantic import BaseModel, Field
+
+from kindgi import tool
+
+
+class EchoInput(BaseModel):
+    message: str = Field(min_length=1, max_length=500)
+
+
+class Echo(BaseModel):
+    echo: str
+    echoed_at: str = Field(alias="echoedAt")
+    character_count: int = Field(alias="characterCount", ge=0)
+
+
+@tool(id="{{PACK_ID}}.echo")
+def echo(input: EchoInput) -> Echo:
+    """Echoes the caller-provided message with a UTC timestamp and character count."""
+    return Echo(
+        echo=input.message,
+        echoedAt=datetime.now(UTC).isoformat(),
+        characterCount=len(input.message),
+    )

package/dist/templates/python/tools/greet.py.tmpl

@@ -0,0 +1,20 @@
+"""{{PACK_ID}}.greet — greets a named recipient."""
+
+from pydantic import BaseModel, Field
+
+from kindgi import tool
+
+
+class GreetInput(BaseModel):
+    name: str = Field(min_length=1, max_length=100)
+    greeting: str = Field("Hello", min_length=1, max_length=50)
+
+
+class Greeting(BaseModel):
+    message: str
+
+
+@tool(id="{{PACK_ID}}.greet")
+def greet(input: GreetInput) -> Greeting:
+    """Formats a greeting for the named recipient."""
+    return Greeting(message=f"{input.greeting}, {input.name}!")

package/dist/templates/sample/.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+.kindgi/
+.kindgirc.json
+*.tsbuildinfo
+.env
+.env.local
+.DS_Store

package/dist/templates/sample/.nvmrc

@@ -0,0 +1 @@
+22

package/dist/templates/sample/AGENTS.md

@@ -0,0 +1,23 @@
+# AGENTS.md
+
+This directory is a Kindgi pack. Author primitives via
+`@kindgi/sdk` — `defineTool`, `defineAgent`, `defineCheck`,
+`defineFlow`. Every export ships with JSDoc; hover them for
+field-level docs. Iterate with `kindgi dev`; `kindgi --help` lists
+the full CLI.
+
+Agents answer through a model provider. `kindgi dev` gives a new pack
+`dev-echo`, a fallback that calls the first tool and replies
+"Tool responded: …" while no other provider fits. For Claude:
+`kindgi providers register --preset=anthropic` (the key in `.env`
+first); other providers and per-agent model choice:
+`.claude/skills/kindgi-authoring-providers/SKILL.md`.
+
+## For Claude Code sessions
+
+When you diagnose a framework bug (something in Kindgi itself, not in
+this pack's code), append an entry to `FEEDBACK.md` at the pack root
+via `kindgi feedback write` — see
+`.claude/skills/kindgi-framework-feedback/SKILL.md`. Mark items fixed
+by adding a `> **Fixed:** <note>` line right after their header; the
+file is a plain markdown list you edit directly.

package/dist/templates/sample/README.md.tmpl

@@ -0,0 +1,85 @@
+# {{PACK_NAME}}
+
+A sample Kindgi pack — scaffolded by `kindgi init --template=sample`.
+
+Two tools (`echo`, `greet`), one guardrail (`response-not-empty`), one
+agent that uses both tools + the guardrail, and one flow that stitches
+the two tools into a workflow. It is compile-time-valid and ready to
+run with `kindgi dev`.
+
+## Layout
+
+```
+{{PACK_NAME}}/
+├── kindgi.config.ts                       # pack id + version + discovery patterns
+├── package.json                              # depends on @kindgi/sdk + zod
+├── tsconfig.json
+├── tools/
+│   ├── echo/index.ts                         # defineTool — Zod-authored echo
+│   └── greet/index.ts                        # defineTool — Zod-authored greeting
+├── guardrails/
+│   └── response-not-empty/index.ts           # defineCheck — response has content
+├── agents/
+│   └── echo-agent/index.ts                   # defineAgent — uses both tools + guardrail
+└── flows/
+    └── echo-flow/index.ts                    # Flow — greet tool → echo agent step → declared output
+```
+
+## Run
+
+```sh
+pnpm install
+pnpm typecheck                                # verify the pack compiles
+kindgi dev                                 # runs the Kindgi runtime (Docker) + hot-reloads this pack
+```
+
+`kindgi dev` bundles every primitive under the four folders above,
+runs their code in a local pack service, starts the Kindgi runtime as a
+Docker container (with a local Postgres), registers this pack, and
+re-registers on every file save.
+
+## Use a real model
+
+`kindgi dev` gives a new pack `dev-echo`, a fallback provider that calls the
+first tool and replies "Tool responded: …" — it answers only while no other
+provider fits. To use Claude, with `kindgi dev` running, from another terminal:
+
+```sh
+kindgi secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt; writes .env.local
+kindgi providers register --preset=anthropic                      # Opus 5.5, Sonnet 5.5, Haiku 4.5
+```
+
+Claude takes over from dev-echo on the next turn; nothing to restart.
+`--models=claude-haiku-4-5` registers one model only; `kindgi providers
+presets` lists the presets (Gemini on Vertex AI too). Picking a model per
+agent, and other providers: `.claude/skills/kindgi-authoring-providers/SKILL.md`.
+
+## The four primitives (one file each)
+
+| Kind | File | What it shows |
+|---|---|---|
+| Tool | `tools/echo/index.ts` | `defineTool` with Zod input/output; no `needs`; `effects: []`. |
+| Tool | `tools/greet/index.ts` | Second Zod-authored tool — takes a name, returns a greeting. |
+| Tool | `tools/fetch-httpbin/index.ts` | `defineTool({spec: {kind: 'http'}})` — declarative HTTP call, no imperative handler code. Hits httpbin.org so it works without credentials. |
+| Guardrail | `guardrails/response-not-empty/index.ts` | `defineCheck` — zero-LLM check that a response payload is non-empty. |
+| Agent | `agents/echo-agent/index.ts` | `defineAgent` — pulls in the local tools + the guardrail; uses `capabilities` for model routing. |
+| Flow | `flows/echo-flow/index.ts` | `defineFlow` — a tool step fed from the run input, an agent step, a declared `output`. Run: `kindgi runs start --flow={{PACK_ID}}.echo-flow --input='{"name":"Ada"}'`. |
+
+## Extend
+
+Add more primitives following the same folder convention. `defineTool` +
+`defineCheck` + `defineAgent` all come from `@kindgi/sdk/define`:
+
+```ts
+import { defineTool, defineCheck, defineAgent, defineFlow } from '@kindgi/sdk/define';
+import { z } from 'zod';
+```
+
+Every `define*` export ships with JSDoc — hover it in your editor for
+field-level docs.
+
+## Note on `@kindgi/sdk` versioning
+
+This template pins `@kindgi/sdk: "workspace:*"` because the SDK is not
+yet published to npm. Until it is, add the pack to a pnpm workspace that
+contains the Kindgi packages (`pnpm-workspace.yaml`).

package/dist/templates/sample/agents/echo-agent/index.ts.tmpl

@@ -0,0 +1,34 @@
+// {{PACK_ID}}.echo-agent — pulls in both tools + the response-not-empty
+// guardrail. The agent shape is pure metadata; every field is either a
+// primitive or a reference to a registered substrate object.
+
+import { defineAgent } from '@kindgi/sdk/define';
+import type { AgentId, GuardrailId, Semver } from '@kindgi/sdk/types';
+
+const defined = defineAgent({
+  id: '{{PACK_ID}}.echo-agent' as AgentId,
+  version: '{{PACK_VERSION}}' as Semver,
+  name: 'Echo Agent',
+  description:
+    'Uses the pack\'s echo + greet tools; the response-not-empty guardrail guards the output.',
+  instructions:
+    'For each user message: if the user sends a name, invoke `{{PACK_ID}}.greet` with it. Otherwise invoke `{{PACK_ID}}.echo` with the message text. Quote the tool result verbatim in your reply.',
+  capabilities: [{ needs: [{ feature: 'tool-use' as const }] }],
+  tools: [
+    { id: '{{PACK_ID}}.echo', version: '{{PACK_VERSION}}' },
+    { id: '{{PACK_ID}}.greet', version: '{{PACK_VERSION}}' },
+  ],
+  retrieval: [],
+  guardrails: ['{{PACK_ID}}.response-not-empty' as GuardrailId],
+  parameters: [],
+  conversationPolicy: { historyLimit: 10 },
+  budget: { maxSteps: 4, maxCostUsd: 0.1, maxWallMs: 15_000 },
+});
+
+if (defined.kind === 'err') {
+  throw new Error(
+    `{{PACK_ID}}.echo-agent failed to compile: ${defined.error.message}`,
+  );
+}
+
+export default defined.value;

package/dist/templates/sample/flows/echo-flow/index.ts.tmpl

@@ -0,0 +1,59 @@
+// {{PACK_ID}}.echo-flow — greets a name with the greet tool, then hands
+// the greeting to the echo agent as an agent step, and returns both.
+//
+// It shows the parts most flows use:
+//   - a tool step whose input is mapped from the run input
+//     (`inputMapping` — `runInput.name`);
+//   - an agent step: the agent runs one turn as a child run, gets the
+//     step's input as structured input (`{{ input.text }}` in its
+//     instructions) and as its message, and its answer is
+//     `nodeOutputs.respond.text` (`.output.<field>` with a typed `output`);
+//   - a declared `output`, checked against its schema.
+// The kindgi-authoring-flows skill covers branches, loops and the rest.
+//
+// Run it:  kindgi runs start --flow={{PACK_ID}}.echo-flow --input='{"name":"Ada"}'
+
+import { defineFlow } from '@kindgi/sdk/define';
+
+const defined = defineFlow({
+  id: '{{PACK_ID}}.echo-flow',
+  version: '{{PACK_VERSION}}',
+  name: 'Echo Flow',
+  description: 'Greets a name, then has the echo agent respond to the greeting.',
+  nodes: [
+    {
+      id: 'greet',
+      kind: 'tool',
+      ref: '{{PACK_ID}}.greet',
+      inputMapping: { name: { path: 'runInput.name' } },
+    },
+    {
+      id: 'respond',
+      kind: 'agent',
+      ref: '{{PACK_ID}}.echo-agent',
+      inputMapping: { text: { path: 'nodeOutputs.greet.message' } },
+    },
+  ],
+  edges: [
+    { id: 'e-start', from: '$start', to: 'greet' },
+    { id: 'e-respond', from: 'greet', to: 'respond' },
+    { id: 'e-end', from: 'respond', to: '$end' },
+  ],
+  output: {
+    mapping: {
+      greeting: { path: 'nodeOutputs.greet.message' },
+      reply: { path: 'nodeOutputs.respond.text' },
+    },
+    schema: {
+      type: 'object',
+      properties: { greeting: { type: 'string' }, reply: { type: 'string' } },
+      required: ['greeting', 'reply'],
+    },
+  },
+});
+
+if (defined.kind === 'err') {
+  throw new Error(`{{PACK_ID}}.echo-flow failed to compile: ${defined.error.message}`);
+}
+
+export default defined.value;

package/dist/templates/sample/guardrails/response-not-empty/index.ts.tmpl

@@ -0,0 +1,50 @@
+// {{PACK_ID}}.response-not-empty — zero-LLM guardrail that fails when the
+// run's final `output` is empty or whitespace-only. Cheap, deterministic,
+// replayable — the preferred kind of guardrail.
+//
+// The module exports a guardrail object literal whose `check` sub-object
+// carries an inline `evaluate` handler. The indexer picks up `action` +
+// `kind` at the top level; the runtime registers the inline check at
+// boot.
+
+import { defineCheck } from '@kindgi/sdk/define';
+import { z } from 'zod';
+
+const ConfigSchema = z.object({
+  minLength: z.number().int().min(0).default(1),
+});
+
+const check = defineCheck({
+  id: '{{PACK_ID}}.checks.response-not-empty',
+  kind: 'zero-llm',
+  configSchema: ConfigSchema,
+  evaluate: async (config, trace) => {
+    const output = trace.output;
+    const text = typeof output === 'string' ? output.trim() : '';
+    if (text.length < config.minLength) {
+      return {
+        passed: false,
+        reason: `Response too short: got ${text.length} chars, expected >= ${config.minLength}.`,
+      };
+    }
+    return { passed: true };
+  },
+});
+
+const guardrail = {
+  id: '{{PACK_ID}}.response-not-empty',
+  name: 'Response is non-empty',
+  kind: 'zero-llm' as const,
+  check: {
+    id: check.id,
+    evaluate: check.evaluate,
+    ...(check.validateConfig !== undefined && { validateConfig: check.validateConfig }),
+  },
+  configSchema: check.configJsonSchema,
+  action: { 'on-violation': 'halt' } as const,
+  severity: 'error' as const,
+  scope: { when: 'runtime-only' as const },
+};
+
+export default guardrail;
+export { check };

package/dist/templates/sample/kindgi.config.ts.tmpl

@@ -0,0 +1,41 @@
+// Kindgi pack config — scaffolded by `kindgi init --template=sample`.
+
+const config = {
+  pack: {
+    id: '{{PACK_ID}}',
+    version: '{{PACK_VERSION}}',
+    description: 'A sample Kindgi pack — two tools, one guardrail, one agent, one flow.',
+  },
+  discovery: {
+    tools: 'tools/**/*.ts',
+    guardrails: 'guardrails/**/*.ts',
+    agents: 'agents/**/*.ts',
+    flows: 'flows/**/*.ts',
+  },
+  // ---------------------------------------------------------------
+  // Environments — one entry per deploy target. `kindgi build`
+  // reads `.build`, `.registry`, `.signingKey`, `.tenantId` for the
+  // chosen env; `kindgi deploy` reads `.endpoint`.
+  //
+  // Fill these in when you're ready to push a build. Local
+  // `kindgi dev` does NOT read this block.
+  // ---------------------------------------------------------------
+  environments: {
+    staging: {
+      endpoint: 'https://api.staging.example.com',
+      build: 'http://localhost:8787', // your Kindgi build server
+      registry: 'ghcr.io/your-org',
+      signingKey: '~/.kindgi/keys/staging.pem',
+      tenantId: 'tenant-your-org-staging',
+    },
+    production: {
+      endpoint: 'https://api.example.com',
+      build: 'https://build.example.com',
+      registry: 'ghcr.io/your-org',
+      signingKey: '~/.kindgi/keys/production.pem',
+      tenantId: 'tenant-your-org-production',
+    },
+  },
+} as const;
+
+export default config;

package/dist/templates/sample/package.json.tmpl

@@ -0,0 +1,25 @@
+{
+  "name": "{{PACK_NAME}}",
+  "version": "{{PACK_VERSION}}",
+  "private": true,
+  "description": "Kindgi pack — scaffolded by `kindgi init --template=sample`. Two tools, one guardrail, one agent, one flow.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@kindgi/sdk": "workspace:*",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@kindgi/cli": "workspace:*",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.0"
+  }
+}

package/dist/templates/sample/pnpm-workspace.yaml

@@ -0,0 +1,6 @@
+# pnpm 12+ reads settings from this file, not from `package.json`'s
+# `pnpm` block. `allowBuilds` grants postinstall permission to
+# specific dependencies — esbuild ships a native binary via
+# postinstall that the vitest transform pipeline depends on.
+allowBuilds:
+  esbuild: true

package/dist/templates/sample/tools/echo/index.test.ts.tmpl

@@ -0,0 +1,31 @@
+// {{PACK_ID}}.echo — smoke test verifying the tool compiles + the
+// handler returns the expected shape. Scaffolded by `kindgi init`
+// so `kindgi test` has something to run out of the box.
+
+import { describe, expect, test } from 'vitest';
+
+import type { ToolContext } from '@kindgi/sdk/define';
+import type { TenantId } from '@kindgi/sdk/types';
+
+import echo from './index.js';
+
+function makeCtx(): ToolContext {
+  return {
+    tenantId: '00000000-0000-0000-0000-000000000001' as TenantId,
+    abortSignal: new AbortController().signal,
+  };
+}
+
+describe('{{PACK_ID}}.echo', () => {
+  test('compiles with the expected id', () => {
+    expect(echo.id).toBe('{{PACK_ID}}.echo');
+  });
+
+  test('handler round-trips the message + count', async () => {
+    if (echo.handler === undefined) throw new Error('handler missing');
+    const out = await echo.handler({ message: 'hello' }, makeCtx());
+    expect(out.echo).toBe('hello');
+    expect(out.characterCount).toBe(5);
+    expect(typeof out.echoedAt).toBe('string');
+  });
+});

package/dist/templates/sample/tools/echo/index.ts.tmpl

@@ -0,0 +1,37 @@
+// {{PACK_ID}}.echo — echoes the caller-provided message back with a UTC
+// timestamp. Zod-authored — the wire form is JSON Schema, converted at
+// author time by `defineTool`.
+
+import { defineTool } from '@kindgi/sdk/define';
+import type { ToolId } from '@kindgi/sdk/types';
+import { z } from 'zod';
+
+const EchoInput = z.object({
+  message: z.string().min(1).max(500),
+});
+
+const EchoOutput = z.object({
+  echo: z.string(),
+  echoedAt: z.string(),
+  characterCount: z.number().int().nonnegative(),
+});
+
+const defined = defineTool({
+  id: '{{PACK_ID}}.echo' as ToolId,
+  description: 'Echoes the caller-provided message with a UTC timestamp + character count.',
+  version: '{{PACK_VERSION}}',
+  input: EchoInput,
+  output: EchoOutput,
+  effects: [],
+  handler: async (input) => ({
+    echo: input.message,
+    echoedAt: new Date().toISOString(),
+    characterCount: input.message.length,
+  }),
+});
+
+if (defined.kind === 'err') {
+  throw new Error(`{{PACK_ID}}.echo failed to compile: ${defined.error.message}`);
+}
+
+export default defined.value;

package/dist/templates/sample/tools/fetch-httpbin/index.ts.tmpl

@@ -0,0 +1,60 @@
+// {{PACK_ID}}.fetch-httpbin — declarative tool example (spec form).
+//
+// Uses `defineTool({spec: {kind: 'http', ...}})` — no imperative
+// handler code. The runtime synthesizes the fetch call from the
+// spec at register time. Handler receives validated input; URL
+// template placeholders substitute from that input.
+//
+// This tool hits httpbin.org (a free HTTP debugging service) so
+// it works without any secret configuration. For a real API with
+// authentication, add:
+//
+//     authorization: {
+//       kind: 'bearer',
+//       secretRef: { envName: 'local', name: 'MY_TOKEN' },
+//     },
+//
+// The runtime resolves the secret on every call from its secrets
+// store, in the env the ref names — under `kindgi dev`, env `local`
+// is your `.env` / `.env.local`. A secret it can't find fails the
+// call with `secret-unavailable`, naming it.
+
+import { defineTool } from '@kindgi/sdk/define';
+import type { ToolId } from '@kindgi/sdk/types';
+import { z } from 'zod';
+
+const FetchInput = z.object({
+  path: z.string().regex(/^[a-z0-9\-\/]+$/, 'lowercase path segments only'),
+});
+
+const FetchOutput = z
+  .object({
+    url: z.string(),
+    origin: z.string().optional(),
+    headers: z.record(z.string(), z.string()).optional(),
+    args: z.record(z.string(), z.string()).optional(),
+  })
+  .passthrough();
+
+const defined = defineTool({
+  id: '{{PACK_ID}}.fetch-httpbin' as ToolId,
+  description:
+    'Fetch a path from httpbin.org (an HTTP request debugging service). Useful for testing the framework declarative-tool primitive end-to-end without needing real API credentials.',
+  version: '{{PACK_VERSION}}',
+  input: FetchInput,
+  output: FetchOutput,
+  effects: [{ kind: 'reads', resource: 'external:httpbin.org' }],
+  spec: {
+    kind: 'http',
+    method: 'GET',
+    urlTemplate: 'https://httpbin.org/{path}',
+    headers: [{ name: 'Accept', value: 'application/json' }],
+    timeoutMs: 10_000,
+  },
+});
+
+if (defined.kind === 'err') {
+  throw new Error(`{{PACK_ID}}.fetch-httpbin failed to compile: ${defined.error.message}`);
+}
+
+export default defined.value;

package/dist/templates/sample/tools/greet/index.ts.tmpl

@@ -0,0 +1,35 @@
+// {{PACK_ID}}.greet — greets a named recipient. Second Zod-authored tool
+// alongside `echo` to show how a pack composes multiple primitives. It is
+// read-only (`mutating: false`), so it also runs in a dry run.
+
+import { defineTool } from '@kindgi/sdk/define';
+import type { ToolId } from '@kindgi/sdk/types';
+import { z } from 'zod';
+
+const GreetInput = z.object({
+  name: z.string().min(1).max(100),
+  greeting: z.string().min(1).max(50).default('Hello'),
+});
+
+const GreetOutput = z.object({
+  message: z.string(),
+});
+
+const defined = defineTool({
+  id: '{{PACK_ID}}.greet' as ToolId,
+  description: 'Formats a greeting for the named recipient.',
+  version: '{{PACK_VERSION}}',
+  input: GreetInput,
+  output: GreetOutput,
+  effects: [],
+  mutating: false,
+  handler: async (input) => ({
+    message: `${input.greeting}, ${input.name}!`,
+  }),
+});
+
+if (defined.kind === 'err') {
+  throw new Error(`{{PACK_ID}}.greet failed to compile: ${defined.error.message}`);
+}
+
+export default defined.value;