@kindgi/cli 0.1.1 → 0.1.3

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

@@ -14,8 +14,8 @@ description: >
   kindgi-python-authoring-agents; models by kindgi-authoring-providers.
 type: core
 library: "kindgi (Python)"
-version: "0.1.1"
-sdk_version: "0.1.1"
+version: "0.1.5"
+sdk_version: "0.1.3"
 pack_languages: [python]
 sources:
   - sdks/python/README.md
@@ -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
@@ -129,8 +129,16 @@ kindgi secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prom
 kindgi providers register --preset=anthropic
 ```
 
-It takes over at the next turn. Details and other providers:
-`kindgi-authoring-providers`.
+It takes over at the next turn. That registration is in this project's dev
+database only. To have `kindgi dev` register it on every boot, in every
+worktree and after `--reset`, declare it in `pyproject.toml` instead:
+
+```toml
+[[tool.kindgi.providers]]
+preset = "anthropic"   # its key, ANTHROPIC_API_KEY, from the env files
+```
+
+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
@@ -182,6 +190,67 @@ 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"]`).
+- **What it cost:** `client.cost.records.list(root_run_id=run_id).data`
+  (`GET /v1/cost/records?rootRunId={runId}`): one record per model call,
+  with its `model`, `usage` (`prompt_tokens`, `completion_tokens`) and
+  `cost_usd` (a float, US dollars), a flow's agent steps included. For one
+  customer's spend, see below.
+- **When a run finished:** the `run.finished` webhook (the run's id, its
+  outcome and its cost in `data.run.usage`; no output, so then `runs.get`),
+  not polling.
+
+**One customer's spend:** give each customer an org, and start their runs in a
+project of that org. Then one call sums their month:
+
+```python
+from datetime import datetime, timezone
+
+# Once per customer. Project slugs are unique across the tenant: put the customer in them.
+org = client.orgs.create(slug="acme-customer-one", name="Customer one")
+project = client.projects.create(org_id=str(org.id), slug="acme-customer-one-app", name="App")
+# save org.id and project.id on the customer's row; start their runs with project_id=project.id
+
+now = datetime.now(timezone.utc)
+month = client.cost.aggregate(
+    group_by="month",
+    scope_kind="org",
+    scope_id=str(org.id),
+    from_=now.replace(day=1, hour=0, minute=0, second=0, microsecond=0).isoformat(),
+    to=now.isoformat(),  # exclusive
+)
+# month.total_usd; month.groups[i].key ({"month": "2026-10"}), .total_usd, .tokens
+```
+
+Docs: https://docs.kindgi.com/v0.1/guides/observability/cost-per-run/
+
+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/dist/templates/minimal/AGENTS.md

@@ -8,9 +8,10 @@ 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:
+"Tool responded: …" while no other provider fits. For Claude,
+put the key in `.env` and declare `{ preset: 'anthropic' }` in
+`kindgi.config.ts`'s `providers`: `kindgi dev` then registers it on every
+boot, in every worktree. Other providers and per-agent model choice:
 `.claude/skills/kindgi-authoring-providers/SKILL.md`.
 
 ## For Claude Code sessions

package/dist/templates/minimal/package.json.tmpl

@@ -6,7 +6,7 @@
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.12.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/dist/templates/python/AGENTS.md

@@ -12,10 +12,11 @@ starts with `_`. The config is `[tool.kindgi]` in `pyproject.toml`.
 - `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`.
+  "Tool responded: …" while no other provider fits. For Claude,
+  put the key in `.env` and add a `[[tool.kindgi.providers]]` table with
+  `preset = "anthropic"` to `pyproject.toml`: `kindgi dev` then registers it
+  on every boot, in every worktree. Other providers and per-agent model
+  choice: `.claude/skills/kindgi-authoring-providers/SKILL.md`.
 
 ## Skills
 

package/dist/templates/sample/AGENTS.md

@@ -8,9 +8,10 @@ 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:
+"Tool responded: …" while no other provider fits. For Claude,
+put the key in `.env` and declare `{ preset: 'anthropic' }` in
+`kindgi.config.ts`'s `providers`: `kindgi dev` then registers it on every
+boot, in every worktree. Other providers and per-agent model choice:
 `.claude/skills/kindgi-authoring-providers/SKILL.md`.
 
 ## For Claude Code sessions

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

@@ -6,7 +6,7 @@
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.12.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindgi/cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Command-line interface for Kindgi™ — the sovereign AI OS. Create a pack, run it on your machine (`kindgi dev`), build, sign and deploy it, and work with a running Kindgi API from the terminal.",
   "license": "Apache-2.0",
   "repository": {
@@ -21,7 +21,8 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     }
   },
   "files": [
@@ -29,22 +30,22 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.12.0"
   },
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
   "dependencies": {
-    "@kindgi/client": "0.1.1",
-    "@kindgi/dotenv-file": "0.1.1",
-    "@kindgi/crypto": "0.1.1",
-    "@kindgi/env-schema": "0.1.1",
-    "@kindgi/handler-runtime": "0.1.1",
-    "@kindgi/secrets-dotenv": "0.1.1",
-    "@kindgi/platform": "0.1.1",
-    "@kindgi/sdk": "0.1.1",
-    "@kindgi/types": "0.1.1",
+    "@kindgi/client": "0.1.3",
+    "@kindgi/dotenv-file": "0.1.3",
+    "@kindgi/crypto": "0.1.3",
+    "@kindgi/env-schema": "0.1.3",
+    "@kindgi/handler-runtime": "0.1.3",
+    "@kindgi/secrets-dotenv": "0.1.3",
+    "@kindgi/platform": "0.1.3",
+    "@kindgi/sdk": "0.1.3",
+    "@kindgi/types": "0.1.3",
     "esbuild": "^0.24.0",
     "semver": "^7.8.5",
     "smol-toml": "^1.9.0",