@kindgi/cli 0.0.0-bootstrap.0 → 0.1.0

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

@@ -0,0 +1,240 @@
+---
+name: kindgi-python-getting-started
+description: >
+  Getting a Python Kindgi pack running: what a pack is, scaffolding one
+  (`kindgi init <name> --template=python`) or adding `[tool.kindgi]` to
+  an existing Python app, `uv sync`, `kindgi dev`, the first agent run,
+  connecting a real model, flows, calling the Kindgi API from Python
+  (`kindgi.client`), and building an image. Load this when a Python
+  project has no `[tool.kindgi]` table yet and the user asks to "add
+  Kindgi", "make an agent", "set up a pack", or when you are orienting
+  in a Python pack (pyproject.toml with `[tool.kindgi]`) for the first
+  time. Authoring tools, guardrails and agents is covered by
+  kindgi-python-authoring-tools, kindgi-python-authoring-guardrails and
+  kindgi-python-authoring-agents; models by kindgi-authoring-providers.
+type: core
+library: "kindgi (Python)"
+version: "0.1.0"
+sdk_version: "0.1.0"
+pack_languages: [python]
+sources:
+  - sdks/python/README.md
+  - sdks/python/src/kindgi/pack/config.py
+  - sdks/python/src/kindgi/pack/discovery.py
+---
+
+# 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
+> commands run in the pack's environment: `uv run …`.
+
+## What a pack is
+
+A **pack** is a project Kindgi indexes and runs. Its config is the
+`[tool.kindgi]` table of `pyproject.toml`; its primitives live in four
+folders, one or more per `.py` file, at module level:
+
+- **Tools** (`tools/*.py`, `@tool`) — your Python code an agent or flow
+  calls.
+- **Guardrails** (`guardrails/*.py`, `@guardrail`) — checks over an
+  agent's turn.
+- **Agents** (`agents/*.py`, `Agent(...)`) — data: instructions, tools,
+  capabilities. The model runs in Kindgi.
+- **Flows** (`flows/*.py`, `Flow(...)`) — data: steps (tool or agent
+  nodes) and the edges between them.
+
+Kindgi runs the tools and checks in the pack's own Python process (the
+pack service) and calls them over HTTP; everything else runs in the
+Kindgi runtime. A module whose name starts with `_` is a helper, not a
+primitive; `test_*.py`, `*_test.py` and `conftest.py` are skipped.
+
+## Scaffold a new pack
+
+```sh
+kindgi init my-pack --template=python
+cd my-pack
+uv sync            # .venv with the kindgi package
+uv run pytest
+kindgi dev         # boots Kindgi locally and runs this pack, reloading on save
+```
+
+`kindgi dev` needs Postgres: it starts one in Docker unless
+`KINDGI_DATABASE_URL` points at yours. It runs the pack with
+`.venv/bin/python` (or `dev.python` in `[tool.kindgi]`, e.g.
+`["uv", "run", "python"]`), checks that interpreter can import
+`kindgi`, and swaps the code on every save.
+
+## Add Kindgi to an existing Python app
+
+In the app's directory (where its `pyproject.toml` is):
+
+```sh
+kindgi init            # --pack-id=<id> if the app's name doesn't make one
+uv sync                # or what it prints for Poetry / pip
+kindgi dev
+```
+
+`kindgi init` edits the app's `pyproject.toml` in place — your layout and
+comments stay — appending the `[tool.kindgi]` tables (the pack id from
+`[project].name`, or `[tool.poetry].name` in a Poetry 1 app; discovery
+under `kindgi/`; in a Poetry app, `dev.python` runs `poetry run python`)
+and adding `kindgi` to `[project].dependencies`; where it can't edit the
+dependencies (Poetry 1, `dynamic`), it prints the command to run. It adds the `kindgi/tools`,
+`guardrails`, `agents` and `flows` folders, these skills and `.gitignore`
+entries. An app with a `package.json` too gets a TypeScript pack unless you
+pass `--template=python`.
+
+The pack root is on `sys.path`, so tools import the app's own packages by
+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.
+
+## Layout of the template
+
+```
+my-pack/
+├── pyproject.toml                     # [tool.kindgi] — id, version, (discovery, dev, environments)
+├── tools/echo.py, tools/greet.py      # @tool
+├── guardrails/response_not_empty.py   # @guardrail
+├── agents/echo_agent.py               # Agent(...)
+├── flows/echo_flow.py                 # Flow(...)
+├── tests/test_tools.py                # the tools and the check, called directly
+├── README.md
+└── .claude/skills/                    # these skills (`kindgi skills sync` refreshes them)
+```
+
+The `[tool.kindgi]` keys are the ones `kindgi.config.ts` takes —
+`pack`, `discovery`, `dev`, `env`, `environments` — spelled the same.
+
+## First run
+
+With `kindgi dev` running, from another terminal in the pack directory:
+
+```sh
+kindgi runs start --agent=my-pack.echo-agent --input='{"userMessage":"Ada"}'
+```
+
+The answer comes from `dev-echo`, a **fallback** provider a new pack
+gets: no model, no key — it calls the first tool and replies "Tool
+responded: …", and the turn carries a `fallback-provider` warning. For
+a real model, put the key in `.env` and register a provider:
+
+```sh
+kindgi secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt
+kindgi providers register --preset=anthropic
+```
+
+It takes over at the next turn. Details and other providers:
+`kindgi-authoring-providers`.
+
+`uv run python -m kindgi.pack index --pack-dir .` prints what Kindgi
+sees (the index); `kindgi dev` reports a broken file with its path and
+keeps serving the rest.
+
+## Flows
+
+A flow is data: nodes and edges (`flow.schema.json`). A node's `ref` may
+be the `Tool` object:
+
+```python
+# flows/record.py
+from kindgi import Flow
+
+from ..tools.ledger import record_expense
+
+record = Flow(
+    id="acme.ledger.record-flow",
+    version="0.1.0",
+    nodes=[{"id": "record", "kind": "tool", "ref": record_expense}],
+    edges=[
+        {"id": "e-start", "from": "$start", "to": "record"},
+        {"id": "e-end", "from": "record", "to": "$end"},
+    ],
+)
+```
+
+A node gets its single upstream node's output (the run input after
+`$start`), or what its `inputMapping` says: each key a `{"literal": …}`
+or a `{"path": …}` rooted at `runInput`, `state` or
+`nodeOutputs.<nodeId>`. The indexer checks every flow against the
+schema. Run one with `kindgi runs start --flow=<id> --input='{…}'`;
+branches, loops and agent steps → `kindgi-python-authoring-flows`.
+
+## Calling Kindgi from Python
+
+`kindgi.client` covers the whole API:
+
+```python
+from kindgi.client import Kindgi
+
+client = Kindgi()  # KINDGI_API_URL + KINDGI_API_TOKEN, or Kindgi(url, token=…)
+run = client.runs.start(agent="my-pack.echo-agent", input={"userMessage": "Ada"})
+print(run.status, run.output["response"]["content"])
+for event in client.runs.stream(str(run.id)):
+    print(event.kind)
+```
+
+`AsyncKindgi` is the asyncio twin. `kindgi dev` prints the URL and the
+token; `.kindgirc.json` in the pack holds them for the CLI.
+
+## Build an image
+
+`kindgi build --env=<name>` (an `[tool.kindgi.environments.<name>]`
+block) builds the pack's image. Its dependencies install from the pack's
+lockfile, frozen, main dependencies only: `uv.lock` (run `uv lock`
+first), or in a Poetry app `poetry.lock` (`poetry lock`; the image brings
+its own pinned Poetry). The index is built in the image; the pack service
+is its entrypoint. An app with only `requirements.txt` can't build yet.
+
+Debian packages the code needs (OCR, PDF tools, `libmagic`, …) are
+declared in `pyproject.toml`; the image installs them, for the build and
+at run time:
+
+```toml
+[tool.kindgi.image]
+system-packages = ["tesseract-ocr", "poppler-utils"]   # names, or name=version
+```
+
+The variables the code reads from `os.environ` (a database URL, a bucket)
+are declared too, names only. A deployed pack service missing a `required`
+one isn't ready, and its `/readyz` names it:
+
+```toml
+[tool.kindgi.env]
+required = ["DATABASE_URL"]
+optional = ["SENTRY_DSN"]
+```
+
+A `[tool.uv] required-version` that excludes the image's uv stops the
+build before anything uploads, with the range to use.
+
+## Two things need the human
+
+- **The pack id and version** in `[tool.kindgi.pack]`. The id prefixes
+  every primitive (`<pack-id>.<name>`); pick it once.
+- **Model credentials.** Ask for the key; never invent or hard-code one.
+
+## Next
+
+- A tool → `kindgi-python-authoring-tools`.
+- A guardrail → `kindgi-python-authoring-guardrails`.
+- An agent → `kindgi-python-authoring-agents`.
+- A flow → `kindgi-python-authoring-flows`.
+- A real model → `kindgi-authoring-providers`.
+- An external resource (a database) for the coding agent →
+  `kindgi-authoring-mcp-servers`.
+
+## Keeping skills up to date
+
+`kindgi skills sync` refreshes `.claude/skills/` from the CLI's copy
+(local edits are kept unless `--force`); `kindgi dev` says when they are
+out of date.
+
+## When the framework itself is the problem
+
+If the bug is in Kindgi or the `kindgi` package and not in the pack's
+code, load `kindgi-framework-feedback` and file it with
+`kindgi feedback write`.

package/dist/stop-signal.d.ts

@@ -0,0 +1,15 @@
+/**
+ * SIGINT / SIGTERM → an AbortSignal long-lived commands (`kindgi dev`)
+ * watch to shut down cleanly: close watchers, stop the api-server, tear
+ * down the bundled containers.
+ *
+ * The listener stays registered (`on`, never `once`), so a dependency
+ * that re-raises a signal when it finds itself the only listener left
+ * (`signal-exit` v3 does) can't cut the graceful shutdown short. A second
+ * signal forces the exit, the usual Ctrl+C-twice contract.
+ */
+export interface SignalSource {
+    on(event: 'SIGINT' | 'SIGTERM', listener: () => void): unknown;
+}
+export declare function createStopSignal(source: SignalSource, forceExit: (code: number) => void): AbortSignal;
+//# sourceMappingURL=stop-signal.d.ts.map

package/dist/stop-signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stop-signal.d.ts","sourceRoot":"","sources":["../src/stop-signal.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AAEH,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;CAChE;AAED,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAChC,WAAW,CAYb"}

package/dist/stop-signal.js

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export function createStopSignal(source, forceExit) {
+    const controller = new AbortController();
+    const onSignal = () => {
+        if (!controller.signal.aborted) {
+            controller.abort();
+            return;
+        }
+        forceExit(130);
+    };
+    source.on('SIGINT', onSignal);
+    source.on('SIGTERM', onSignal);
+    return controller.signal;
+}
+//# sourceMappingURL=stop-signal.js.map

package/dist/stop-signal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stop-signal.js","sourceRoot":"","sources":["../src/stop-signal.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAiBjC,MAAM,UAAU,gBAAgB,CAC9B,MAAoB,EACpB,SAAiC;IAEjC,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,QAAQ,GAAG,GAAS,EAAE;QAC1B,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YAC/B,UAAU,CAAC,KAAK,EAAE,CAAC;YACnB,OAAO;QACT,CAAC;QACD,SAAS,CAAC,GAAG,CAAC,CAAC;IACjB,CAAC,CAAC;IACF,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC9B,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC/B,OAAO,UAAU,CAAC,MAAM,CAAC;AAC3B,CAAC"}

package/dist/templates/minimal/.gitignore

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

package/dist/templates/minimal/.nvmrc

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

package/dist/templates/minimal/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/minimal/README.md.tmpl

@@ -0,0 +1,69 @@
+# {{PACK_NAME}}
+
+A Kindgi pack — scaffolded by `kindgi init --template=minimal`.
+
+Empty by design: the four discovery folders exist but ship no primitives.
+Author your first via `defineTool` / `defineAgent` / `defineCheck` /
+`defineFlow` from `@kindgi/sdk` — hover the exports for JSDoc.
+
+## Layout
+
+```
+{{PACK_NAME}}/
+├── kindgi.config.ts    # pack id + version + discovery patterns
+├── package.json           # depends on @kindgi/sdk + zod
+├── tsconfig.json
+├── .claude/skills/        # SDK skills — Claude Code auto-loads per task
+├── tools/                 # place `<name>/index.ts` per tool
+├── agents/                # place `<name>/index.ts` per agent
+├── guardrails/            # place `<name>/index.ts` per check
+└── flows/                # place `<name>/index.ts` per flow
+```
+
+## AI coding assistants
+
+`.claude/skills/` is auto-populated at `kindgi init` with per-primitive
+guides: `kindgi-authoring-tools`, `kindgi-authoring-agents`,
+`kindgi-authoring-guardrails`, `kindgi-getting-started` — plus
+`kindgi-authoring-providers` (a real model), `kindgi-authoring-mcp-servers`
+and `kindgi-framework-feedback`. Claude Code
+loads them on-demand based on what you're editing — no configuration
+needed. Read them directly if you want the mental model without an
+assistant in the loop.
+
+## Run
+
+```sh
+pnpm install
+pnpm typecheck              # verify the pack compiles
+kindgi dev                  # runs the Kindgi runtime (Docker) + hot-reloads this pack
+```
+
+The api-server ships with a built-in `demo.echo-agent` you can hit to
+verify boot before authoring anything:
+
+```sh
+kindgi runs start --agent=demo.echo-agent --input='{"userMessage":"hi"}'
+```
+
+## 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`.
+
+## 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/minimal/kindgi.config.ts.tmpl

@@ -0,0 +1,44 @@
+// Kindgi pack config — scaffolded by `kindgi init --template=minimal`.
+
+const config = {
+  pack: {
+    id: '{{PACK_ID}}',
+    version: '{{PACK_VERSION}}',
+    description: 'A minimal Kindgi pack.',
+  },
+  discovery: {
+    tools: 'tools/**/*.ts',
+    guardrails: 'guardrails/**/*.ts',
+    agents: 'agents/**/*.ts',
+    flows: 'flows/**/*.ts',
+  },
+  // ---------------------------------------------------------------
+  // Environments — one entry per deploy target (staging / production
+  // / preview / custom). Each names the build server endpoint, the
+  // signing key path (Ed25519 PEM, never leaves the developer's
+  // machine), the target registry (build server pushes here on your
+  // behalf), and the tenantId the Kindgi runtime scopes the
+  // deployment to. Consumed by `kindgi build` + `kindgi deploy`.
+  //
+  // Fill these in when you're ready to push a build off the laptop.
+  // 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/minimal/package.json.tmpl

@@ -0,0 +1,25 @@
+{
+  "name": "{{PACK_NAME}}",
+  "version": "{{PACK_VERSION}}",
+  "private": true,
+  "description": "Kindgi pack — scaffolded by `kindgi init --template=minimal`.",
+  "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/minimal/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/minimal/tsconfig.json.tmpl

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2023", "DOM"],
+    "types": ["node"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "declaration": true,
+    "sourceMap": true,
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": [
+    "tools/**/*.ts",
+    "guardrails/**/*.ts",
+    "agents/**/*.ts",
+    "flows/**/*.ts",
+    "kindgi.config.ts"
+  ],
+  "exclude": ["node_modules", "dist", ".kindgi"]
+}

package/dist/templates/minimal/vitest.config.ts.tmpl

@@ -0,0 +1,14 @@
+// Vitest configuration for {{PACK_NAME}}. Scaffolded by `kindgi init`.
+// `kindgi test` shells out to the pack's local vitest install using
+// this config — the CLI does NOT force a vitest version through.
+
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['**/*.test.ts'],
+    exclude: ['node_modules/**', '.kindgi/**', 'dist/**'],
+    reporters: ['default'],
+    passWithNoTests: true,
+  },
+});

package/dist/templates/python/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.kindgi/
+.kindgirc.json
+.env
+.env.*
+!.env.example

package/dist/templates/python/AGENTS.md

@@ -0,0 +1,30 @@
+# AGENTS.md
+
+This directory is a Kindgi pack written in Python (the `kindgi` package).
+Tools are `@tool` functions, guardrail checks `@guardrail` functions; agents
+(`Agent`) and flows (`Flow`) are data. Each lives at module level in a file
+under `tools/`, `guardrails/`, `agents/` or `flows/`; a helper module there
+starts with `_`. The config is `[tool.kindgi]` in `pyproject.toml`.
+
+- `kindgi dev` boots Kindgi locally and runs this pack's code with its own
+  `.venv`, reloading on every save.
+- `uv run pytest` runs the tests; a `Tool` or `Guardrail` is still callable.
+- `uv run python -m kindgi.pack index --pack-dir .` shows what Kindgi sees.
+- 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`.
+
+## Skills
+
+`.claude/skills/` holds Kindgi's skills for Python packs: getting started,
+tools, guardrails and agents in Python (`kindgi-python-*`), model providers,
+MCP servers, framework feedback. Claude Code loads them on its own; other
+coding agents can read them. `kindgi skills sync` refreshes them.
+
+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`.

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

@@ -0,0 +1,56 @@
+# {{PACK_NAME}}
+
+A sample Kindgi pack in Python — scaffolded by `kindgi init --template=python`.
+
+Two tools (`echo`, `greet`), one guardrail (`response-not-empty`), one agent
+that uses both tools and the guardrail, and one flow that runs the echo tool.
+
+## Layout
+
+```
+{{PACK_NAME}}/
+├── pyproject.toml                     # [tool.kindgi] — the pack's id and version
+├── tools/echo.py                      # @tool — pydantic in, pydantic out
+├── tools/greet.py                     # @tool
+├── guardrails/response_not_empty.py   # @guardrail — a zero-LLM check over the run
+├── agents/echo_agent.py               # Agent(...) — data
+├── flows/echo_flow.py                 # Flow(...) — data
+└── tests/test_tools.py                # the tools and the check, called directly
+```
+
+## Run
+
+```sh
+uv sync          # .venv with kindgi and the dev tools
+uv run pytest
+kindgi dev       # boots Kindgi locally and runs this pack's code, reloading on save
+```
+
+`kindgi dev` uses the pack's `.venv/bin/python` (or `dev.python` in
+`[tool.kindgi]`). Then, from another terminal:
+
+```sh
+kindgi runs start --agent={{PACK_ID}}.echo-agent --input='{"userMessage":"hi"}'
+```
+
+## 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`.
+
+## Build
+
+`kindgi build --env=<name>` makes the pack's image: dependencies from `uv.lock`
+(run `uv lock` first), the index built in the image, the pack service as its
+entrypoint.

package/dist/templates/python/agents/echo_agent.py.tmpl

@@ -0,0 +1,23 @@
+"""{{PACK_ID}}.echo-agent — uses both tools; the response-not-empty guardrail guards its answer."""
+
+from kindgi import Agent
+
+from ..guardrails.response_not_empty import response_not_empty
+from ..tools.echo import echo
+from ..tools.greet import greet
+
+echo_agent = Agent(
+    id="{{PACK_ID}}.echo-agent",
+    version="{{PACK_VERSION}}",
+    name="Echo Agent",
+    description="Uses the pack's echo and 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."
+    ),
+    capabilities=[{"needs": [{"feature": "tool-use"}]}],
+    tools=[echo, greet],
+    guardrails=[response_not_empty],
+    conversation_policy={"historyLimit": 10},
+    budget={"maxSteps": 4, "maxCostUsd": 0.1, "maxWallMs": 60_000},
+)

package/dist/templates/python/flows/echo_flow.py.tmpl

@@ -0,0 +1,17 @@
+"""{{PACK_ID}}.echo-flow — runs the pack's echo tool, then ends."""
+
+from kindgi import Flow
+
+from ..tools.echo import echo
+
+echo_flow = Flow(
+    id="{{PACK_ID}}.echo-flow",
+    version="{{PACK_VERSION}}",
+    name="Echo Flow",
+    description="Runs the pack's echo tool and terminates.",
+    nodes=[{"id": "echo", "kind": "tool", "ref": echo}],
+    edges=[
+        {"id": "e-start", "from": "$start", "to": "echo"},
+        {"id": "e-end", "from": "echo", "to": "$end"},
+    ],
+)