@kindgi/cli 0.1.8 → 0.1.9-rc.1

package/dist/sdk-skills/kindgi-java-authoring-tools/SKILL.md

@@ -14,8 +14,8 @@ description: >
   by kindgi-java-getting-started.
 type: core
 library: "kindgi-pack (Java)"
-version: "0.1.2"
-sdk_version: "0.1.8"
+version: "0.1.3"
+sdk_version: "0.1.9-rc.1"
 pack_languages: [java]
 sources:
   - sdks/java/kindgi-pack/README.md
@@ -247,6 +247,23 @@ review, so declare what the tool really does.
 Java has no HTTP-tool form (TypeScript's `kind: 'http'`). A tool that calls
 an HTTP API is a handler with `java.net.http.HttpClient`, as above.
 
+## A person's yes when no one is watching: `needsApprovalWhenUnattended`
+
+`needsApprovalWhenUnattended(true)` declares that a person must say yes to every call of the tool in a run no person started: one a schedule, a webhook, an event or a service account's key started. In such a run:
+
+- **An agent's call waits** for a person's yes, whatever the agent's `conversationPolicy.hitl.tools` says. The agent's rules can't lift it: agents are reused, and the tool's author knows what it does.
+- **A flow's tool step that calls it is refused.** Put the tool behind an agent step instead, whose call waits.
+
+In a run a person started (signed in, or with their own API key), the agent's rules decide, as for any tool. Left unset, it counts as `false`. Declare it on a tool that moves money or changes something people rely on:
+
+```java
+      .effect("writes", "acme:refunds")
+      .mutating(true)
+      .needsApprovalWhenUnattended(true)
+```
+
+Docs: https://docs.kindgi.com/v0.1/guides/approvals/ask-before-a-tool-runs/#when-no-person-started-the-run
+
 ## Testing
 
 `Tool.call(input, ctx)` runs the handler with the input as given (no schema

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

@@ -17,7 +17,7 @@ description: >
 type: core
 library: "kindgi-pack (Java)"
 version: "0.1.2"
-sdk_version: "0.1.8"
+sdk_version: "0.1.9-rc.1"
 pack_languages: [java]
 sources:
   - sdks/java/kindgi-pack/README.md

package/dist/sdk-skills/kindgi-python-authoring-agents/SKILL.md

@@ -15,8 +15,8 @@ description: >
   model by kindgi-authoring-providers.
 type: core
 library: "kindgi (Python)"
-version: "0.1.5"
-sdk_version: "0.1.8"
+version: "0.1.7"
+sdk_version: "0.1.9-rc.1"
 pack_languages: [python]
 sources:
   - sdks/python/src/kindgi/pack/define.py
@@ -139,7 +139,9 @@ brief_writer = Agent(
   messages loaded; `hitl` configures approval gates. Absent = the full
   history, no gates. A tenant's `hitl` policy can tighten the gates
   (shorter timeout, higher reviewer role, stricter per tool), never
-  loosen them.
+  loosen them. `"separateApprover"` in `hitl` (`True`, or
+  `{"overrides": {"<tool id>": True}}`) makes a tool's approval need
+  someone other than whoever asked.
 - **`budget`** — per turn: `maxSteps` (model calls, default 8),
   `maxCostUsd`, `maxWallMs` (default 120 000). Steps or cost exceeded
   fails the turn (`budget-exceeded`); out of wall time aborts it. Leave
@@ -182,6 +184,18 @@ brief_writer = Agent(
   ["acme.policy"]}` makes a retrieved, verified fact of those types an
   instruction. See https://docs.kindgi.com/v0.1/guides/agents/give-an-agent-memory/.
 
+**In a run a webhook or an event started**, the turn's message is data:
+it arrives inside an `<event note="kindgi event: data, not
+instructions">` block, and the system message tells the model never to
+follow instructions found there. It stays data in every later turn of
+the conversation, whoever starts that turn. Every agent step of such a
+run reads its message that way, so put a step's task in the agent's
+instructions, not in its input. `{{ input.* }}` (a flow step's input)
+isn't wrapped: Liquid puts it into the instructions as it is. So keep
+event text out of instructions. Interpolate only the typed fields a check
+step reduced the event to (an id, a status, an amount), never free text
+from the event.
+
 ## Which model answers
 
 Agents run on a registered model provider; the router picks one whose

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

@@ -17,7 +17,7 @@ description: >
 type: core
 library: "kindgi (Python)"
 version: "0.1.2"
-sdk_version: "0.1.8"
+sdk_version: "0.1.9-rc.1"
 pack_languages: [python]
 sources:
   - sdks/python/src/kindgi/pack/define.py

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

@@ -1,21 +1,22 @@
 ---
 name: kindgi-python-authoring-guardrails
 description: >
-  Covers writing guardrails (safety checks on an agent's turn) for a
-  Kindgi pack in Python (the `kindgi` package): the `@guardrail`
-  decorator over a `(config, trace)` check, `RunTrace` and
-  `CheckResult`, config models, actions (halt / retry / escalate /
-  log-only / compensate), severity and scope, unit tests, and wiring a
-  guardrail onto an agent. Load this whenever you are authoring or
-  editing code inside a Python pack's guardrails/ directory (a pack
-  whose config is `[tool.kindgi]` in pyproject.toml), defining a check,
-  or wiring a guardrail onto an agent. Python agents are covered by
-  kindgi-python-authoring-agents, Python tools by
-  kindgi-python-authoring-tools.
+  Covers writing guardrails (safety checks on an agent's turn) for a Kindgi
+  pack in Python (the `kindgi` package): the `@guardrail` decorator over a
+  `(config, trace)` check, `RunTrace` and `CheckResult`, config models,
+  actions, severity and scope, unit tests, and wiring a guardrail onto an
+  agent. In 0.1 only the halt action acts (retry / escalate / compensate are
+  only recorded: nothing runs the turn again), and a check sees only the
+  current turn: its user message and tool results, not earlier turns'. Load
+  this whenever you are authoring or editing code inside a Python pack's
+  guardrails/ directory (a pack whose config is `[tool.kindgi]` in
+  pyproject.toml), defining a check, or wiring a guardrail onto an agent.
+  Python agents are covered by kindgi-python-authoring-agents, Python tools
+  by kindgi-python-authoring-tools.
 type: core
 library: "kindgi (Python)"
-version: "0.1.4"
-sdk_version: "0.1.8"
+version: "0.1.5"
+sdk_version: "0.1.9-rc.1"
 pack_languages: [python]
 sources:
   - sdks/python/src/kindgi/pack/define.py
@@ -41,6 +42,41 @@ answer, before it is stored.
 Ask what the rule should catch before writing one; the sample
 `response-not-empty` guardrail is a demonstration, not a template.
 
+## What a guardrail can do in 0.1
+
+Read this before you plan a guardrail. Three limits decide what can be
+built:
+
+- **Only `halt` acts.** A failed `halt` guardrail fails the turn with
+  `guardrail-violation`, and the answer is not stored. `retry`, `escalate`
+  and `compensate` are recorded on the turn's violations, as `log-only`
+  is, and the turn completes: nothing runs the turn again, escalates or
+  calls a compensating tool. So "block the reply and make the agent try
+  again" can't be a guardrail. Use `halt`: the error names the guardrail
+  and the check's reason, and the message is sent again (by the person, or
+  by your app when it gets `guardrail-violation`).
+- **A check sees one turn.** The trace holds the current turn only: its
+  user message (`trace.user_input`), its tool calls and their results
+  (`trace.tool_calls`, `trace.tool_results`) and its answer
+  (`trace.output`). Earlier turns' messages, tool results and answers
+  aren't in it. A check that every figure in the answer comes from a tool
+  result or the user's message therefore blocks an answer that repeats a
+  figure seen only in an earlier turn.
+- **A check's in-memory state doesn't last.** The check runs in the pack
+  service's process, so anything it keeps at module level (say, a dict
+  keyed by `trace.conversation_id`) is lost when that process is replaced:
+  under `kindgi dev`, on every reload after a save and on a restart; in a
+  deployment, whenever an instance stops. With more than one instance,
+  each keeps its own copy, and one conversation's turns can land on
+  different instances. Don't keep a conversation's history this way.
+
+What works today for a check on figures: tell the agent, in its
+instructions, to call its tools again in every answer that quotes a
+figure, so the figure is in that turn's tool results. It depends on the
+model following the instruction, and it doesn't cover figures the user
+typed in an earlier turn: `trace.user_input` is only the current turn's
+message, so an answer that repeats them is still blocked.
+
 ## A guardrail
 
 ```python

package/dist/sdk-skills/kindgi-python-authoring-tools/SKILL.md

@@ -14,8 +14,8 @@ description: >
   kindgi-python-getting-started.
 type: core
 library: "kindgi (Python)"
-version: "0.1.4"
-sdk_version: "0.1.8"
+version: "0.1.5"
+sdk_version: "0.1.9-rc.1"
 pack_languages: [python]
 sources:
   - sdks/python/src/kindgi/pack/define.py
@@ -242,6 +242,28 @@ a tool with a `writes`, `deletes`, `spawns-run`, `emits-event` or
 `limits=` and `network=`. They are recorded in the pack's index for
 policy and review; declare what the tool really does.
 
+## A person's yes when no one is watching: `needs_approval_when_unattended`
+
+`needs_approval_when_unattended=True` declares that a person must say yes to every call of the tool in a run no person started: one a schedule, a webhook, an event or a service account's key started. In such a run:
+
+- **An agent's call waits** for a person's yes, whatever the agent's `conversation_policy` says in `hitl["tools"]`. The agent's rules can't lift it: agents are reused, and the tool's author knows what it does.
+- **A flow's tool step that calls it is refused.** Put the tool behind an agent step instead, whose call waits.
+
+In a run a person started (signed in, or with their own API key), the agent's rules decide, as for any tool. Left out, it counts as `False`. Declare it on a tool that moves money or changes something people rely on:
+
+```python
+@tool(
+    id="acme.refund",
+    effects=[{"kind": "writes", "resource": "acme:refunds"}],
+    mutating=True,
+    needs_approval_when_unattended=True,
+)
+def refund(request: RefundRequest) -> Refunded:
+    """Refunds an order."""
+```
+
+Docs: https://docs.kindgi.com/v0.1/guides/approvals/ask-before-a-tool-runs/#when-no-person-started-the-run
+
 ## HTTP tools — one request, no code
 
 A tool that is a single HTTP request needs no handler. `http_tool(...)`
@@ -278,7 +300,9 @@ lookup_case = http_tool(
   `{"kind": "text", "template": "…{field}…"}` (sent as `text/plain`).
 - Also `timeout_ms=` (default 30000), `parse_json=` (default `True`),
   `success_status=(200, 299)`, `effects=`, `version=`, and
-  `mutating=False` for a request that changes nothing (a GET, usually).
+  `mutating=False` for a request that changes nothing (a GET, usually), and
+  `needs_approval_when_unattended=True` for one that moves money or
+  changes something people rely on.
 - `timeout_ms` covers the whole call, reading the response included, and
   so does a run's cancel. A response body over 10 MiB, counted after it's
   decompressed, fails the call. So point the tool at an endpoint that

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

@@ -15,7 +15,7 @@ description: >
 type: core
 library: "kindgi (Python)"
 version: "0.1.8"
-sdk_version: "0.1.8"
+sdk_version: "0.1.9-rc.1"
 pack_languages: [python]
 sources:
   - sdks/python/README.md

package/dist/sdk-skills/kindgi-scala-authoring-agents/SKILL.md

@@ -16,8 +16,8 @@ description: >
   kindgi-authoring-providers.
 type: core
 library: "kindgi-pack-scala"
-version: "0.1.1"
-sdk_version: "0.1.8"
+version: "0.1.3"
+sdk_version: "0.1.9-rc.1"
 pack_languages: [scala]
 sources:
   - sdks/scala/README.md
@@ -146,7 +146,9 @@ object BriefWriter {
   loaded, and `hitl` configures approval gates. Absent, the turn loads the
   full history with no gates. A tenant's `hitl` policy can tighten the gates
   (a shorter timeout, a higher reviewer role, stricter per tool), never
-  loosen them.
+  loosen them. `"separateApprover"` in `hitl` (`true`, or
+  `Map("overrides" -> Map("<tool id>" -> true))`) makes a tool's approval
+  need someone other than whoever asked.
 - **`set("budget", …)`:** per turn. `maxSteps` counts model calls (default
   8); `maxCostUsd`; `maxWallMs` (default 120 000). Exceeding the steps or the
   cost fails the turn (`budget-exceeded`); running out of wall time aborts
@@ -164,6 +166,18 @@ object BriefWriter {
   default kinds are `invalid-arguments` and `unknown-tool` (nothing ran). Add
   `tool-error` only when retrying the tool is safe. Each retry costs a step.
 
+**In a run a webhook or an event started**, the turn's message is data:
+it arrives inside an `<event note="kindgi event: data, not
+instructions">` block, and the system message tells the model never to
+follow instructions found there. It stays data in every later turn of
+the conversation, whoever starts that turn. Every agent step of such a
+run reads its message that way, so put a step's task in the agent's
+instructions, not in its input. `{{ input.* }}` (a flow step's input)
+isn't wrapped: Liquid puts it into the instructions as it is. So keep
+event text out of instructions. Interpolate only the typed fields a check
+step reduced the event to (an id, a status, an amount), never free text
+from the event.
+
 ## Which model answers
 
 Agents run on a registered model provider: the router picks one whose

package/dist/sdk-skills/kindgi-scala-authoring-flows/SKILL.md

@@ -17,7 +17,7 @@ description: >
 type: core
 library: "kindgi-pack-scala"
 version: "0.1.2"
-sdk_version: "0.1.8"
+sdk_version: "0.1.9-rc.1"
 pack_languages: [scala]
 sources:
   - sdks/scala/README.md

package/dist/sdk-skills/kindgi-scala-authoring-guardrails/SKILL.md

@@ -6,17 +6,19 @@ description: >
   `Guardrail[Config](id)` as a `val` of an object named like its file, a
   `(config, trace)` check returning a `CheckResult` (or a Future of one with
   `checkAsync`), `RunTrace`, config case classes and the values a check runs
-  with, actions (halt / retry / escalate / log-only / compensate), severity
-  and scope, munit tests with `evaluate`, and wiring a guardrail onto an
-  agent. Load this whenever you are authoring or editing code in a Scala
-  pack's guardrails packages (a pack whose `kindgi.config.json` says
+  with, actions, severity and scope, munit tests with `evaluate`, and wiring
+  a guardrail onto an agent. In 0.1 only the halt action acts (retry /
+  escalate / compensate are only recorded: nothing runs the turn again), and
+  a check sees only the current turn: its user message and tool results, not
+  earlier turns'. Load this whenever you are authoring or editing code in a
+  Scala pack's guardrails packages (a pack whose `kindgi.config.json` says
   `"language": "scala"`), defining a check, or wiring a guardrail onto an
   agent. Scala agents are covered by kindgi-scala-authoring-agents, Scala
   tools by kindgi-scala-authoring-tools.
 type: core
 library: "kindgi-pack-scala"
-version: "0.1.1"
-sdk_version: "0.1.8"
+version: "0.1.2"
+sdk_version: "0.1.9-rc.1"
 pack_languages: [scala]
 sources:
   - sdks/scala/README.md
@@ -43,6 +45,41 @@ before it is stored.
 Ask what the rule should catch before writing one. The sample
 `response-not-empty` guardrail is a demonstration, not a template.
 
+## What a guardrail can do in 0.1
+
+Read this before you plan a guardrail. Three limits decide what can be
+built:
+
+- **Only `halt` acts.** A failed `halt` guardrail fails the turn with
+  `guardrail-violation`, and the answer is not stored. `retry`, `escalate`
+  and `compensate` are recorded on the turn's violations, as `log-only`
+  is, and the turn completes: nothing runs the turn again, escalates or
+  calls a compensating tool. So "block the reply and make the agent try
+  again" can't be a guardrail. Use `halt`: the error names the guardrail
+  and the check's reason, and the message is sent again (by the person, or
+  by your app when it gets `guardrail-violation`).
+- **A check sees one turn.** The trace holds the current turn only: its
+  user message (`trace.userInput`), its tool calls and their results
+  (`toolCalls`, `toolResults`) and its answer (`output`). Earlier turns'
+  messages, tool results and answers aren't in it. A check that every
+  figure in the answer comes from a tool result or the user's message
+  therefore blocks an answer that repeats a figure seen only in an earlier
+  turn.
+- **A check's in-memory state doesn't last.** The check runs in the pack
+  service's process, so anything it keeps in an object's state (say, a
+  mutable map of conversations) is lost when that process is replaced:
+  under `kindgi dev`, on every reload after a save and on a restart; in a
+  deployment, whenever an instance stops. With more than one instance,
+  each keeps its own copy, and one conversation's turns can land on
+  different instances. Don't keep a conversation's history this way.
+
+What works today for a check on figures: tell the agent, in its
+instructions, to call its tools again in every answer that quotes a
+figure, so the figure is in that turn's tool results. It depends on the
+model following the instruction, and it doesn't cover figures the user
+typed in an earlier turn: `trace.userInput` is only the current turn's
+message, so an answer that repeats them is still blocked.
+
 ## A guardrail
 
 ```scala

package/dist/sdk-skills/kindgi-scala-authoring-tools/SKILL.md

@@ -15,8 +15,8 @@ description: >
   kindgi-scala-getting-started.
 type: core
 library: "kindgi-pack-scala"
-version: "0.1.2"
-sdk_version: "0.1.8"
+version: "0.1.3"
+sdk_version: "0.1.9-rc.1"
 pack_languages: [scala]
 sources:
   - sdks/scala/README.md
@@ -232,6 +232,23 @@ are recorded for policy and review, so declare what the tool really does.
 There is no HTTP-tool form (TypeScript's `kind: 'http'`). A tool that calls
 an HTTP API is a handler with `java.net.http.HttpClient`, as above.
 
+## A person's yes when no one is watching: `needsApprovalWhenUnattended`
+
+`needsApprovalWhenUnattended(true)` declares that a person must say yes to every call of the tool in a run no person started: one a schedule, a webhook, an event or a service account's key started. In such a run:
+
+- **An agent's call waits** for a person's yes, whatever the agent's `conversationPolicy.hitl.tools` says. The agent's rules can't lift it: agents are reused, and the tool's author knows what it does.
+- **A flow's tool step that calls it is refused.** Put the tool behind an agent step instead, whose call waits.
+
+In a run a person started (signed in, or with their own API key), the agent's rules decide, as for any tool. Left unset, it counts as `false`. Declare it on a tool that moves money or changes something people rely on:
+
+```scala
+    .effect("writes", "acme:refunds")
+    .mutating(true)
+    .needsApprovalWhenUnattended(true)
+```
+
+Docs: https://docs.kindgi.com/v0.1/guides/approvals/ask-before-a-tool-runs/#when-no-person-started-the-run
+
 ## Testing
 
 `tool.call(input, ctx)` runs the handler with the input as given (no schema

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

@@ -17,7 +17,7 @@ description: >
 type: core
 library: "kindgi-pack-scala"
 version: "0.1.2"
-sdk_version: "0.1.8"
+sdk_version: "0.1.9-rc.1"
 pack_languages: [scala]
 sources:
   - sdks/scala/README.md

package/dist/sdk-skills/kindgi-using/SKILL.md

@@ -15,7 +15,7 @@ description: >
 type: core
 library: "@kindgi/sdk"
 version: "0.1.0"
-sdk_version: "0.1.8"
+sdk_version: "0.1.9-rc.1"
 pack_languages: [node, python, java, scala]
 ---
 

package/dist/slug.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A project's slug, as the CLI makes and sends one: `kindgi projects create`
+ * and `rename`, and the way `kindgi deploy` says how to make one.
+ */
+/**
+ * The slugs the CLI sends: lowercase letters, digits and hyphens, starting
+ * with a letter or digit, at most 63 characters. The server takes any slug
+ * that isn't empty; the CLI keeps to these, which a shell and
+ * `kindgi deploy --project <id|slug>` take as they are.
+ */
+export declare const SLUG: RegExp;
+/**
+ * A name as a slug: lowercase letters and digits, each run of anything else
+ * one `-`, none at either end, at most 63 characters. An accent goes, not
+ * its letter (`Café` is `cafe`).
+ */
+export declare function slugOf(name: string): string;
+//# sourceMappingURL=slug.d.ts.map

package/dist/slug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slug.d.ts","sourceRoot":"","sources":["../src/slug.ts"],"names":[],"mappings":"AAGA;;;GAGG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,IAAI,QAA8B,CAAC;AAEhD;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAS3C"}

package/dist/slug.js

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * A project's slug, as the CLI makes and sends one: `kindgi projects create`
+ * and `rename`, and the way `kindgi deploy` says how to make one.
+ */
+/**
+ * The slugs the CLI sends: lowercase letters, digits and hyphens, starting
+ * with a letter or digit, at most 63 characters. The server takes any slug
+ * that isn't empty; the CLI keeps to these, which a shell and
+ * `kindgi deploy --project <id|slug>` take as they are.
+ */
+export const SLUG = /^[a-z0-9][a-z0-9-]{0,62}$/;
+/**
+ * A name as a slug: lowercase letters and digits, each run of anything else
+ * one `-`, none at either end, at most 63 characters. An accent goes, not
+ * its letter (`Café` is `cafe`).
+ */
+export function slugOf(name) {
+    return name
+        .normalize('NFKD')
+        .replace(/\p{M}/gu, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 63)
+        .replace(/-+$/, '');
+}
+//# sourceMappingURL=slug.js.map

package/dist/slug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slug.js","sourceRoot":"","sources":["../src/slug.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC;;;GAGG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,2BAA2B,CAAC;AAEhD;;;;GAIG;AACH,MAAM,UAAU,MAAM,CAAC,IAAY;IACjC,OAAO,IAAI;SACR,SAAS,CAAC,MAAM,CAAC;SACjB,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC;SACtB,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;SACZ,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AACxB,CAAC"}

package/dist/templates/drupal/AGENTS.md

@@ -60,6 +60,8 @@ pack's code), append an entry to `FEEDBACK.md` at the pack root via
 `kindgi feedback write` — see the `kindgi-framework-feedback` skill. Mark
 items fixed by adding a `> **Fixed:** <note>` line right after their
 header; the file is a plain markdown list you edit directly.
+Send entries to Kindgi only after the person has seen the preview and said
+yes: `kindgi feedback submit --preview`, then `--yes=<its digest>`.
 
 When the person asks how to use what you built (where something is in
 Kindgi's console, what an agent did, what it cost, who has access), answer

package/dist/templates/java/AGENTS.md

@@ -39,6 +39,8 @@ loads `.claude/skills/` on its own; Codex and Gemini CLI look in
 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 with
 `kindgi feedback write`.
+Send entries to Kindgi only after the person has seen the preview and said
+yes: `kindgi feedback submit --preview`, then `--yes=<its digest>`.
 
 When the person asks how to use what you built (where something is in
 Kindgi's console, what an agent did, what it cost, who has access), answer

package/dist/templates/minimal/AGENTS.md

@@ -31,6 +31,8 @@ pack's code), append an entry to `FEEDBACK.md` at the pack root via
 `kindgi feedback write` — see the `kindgi-framework-feedback` skill. Mark
 items fixed by adding a `> **Fixed:** <note>` line right after their
 header; the file is a plain markdown list you edit directly.
+Send entries to Kindgi only after the person has seen the preview and said
+yes: `kindgi feedback submit --preview`, then `--yes=<its digest>`.
 
 When the person asks how to use what you built (where something is in
 Kindgi's console, what an agent did, what it cost, who has access), answer

package/dist/templates/python/AGENTS.md

@@ -34,6 +34,8 @@ loads `.claude/skills/` on its own; Codex and Gemini CLI look in
 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 the `kindgi-framework-feedback` skill.
+Send entries to Kindgi only after the person has seen the preview and said
+yes: `kindgi feedback submit --preview`, then `--yes=<its digest>`.
 
 ## Commands for the person's own terminal
 

package/dist/templates/sample/AGENTS.md

@@ -31,6 +31,8 @@ pack's code), append an entry to `FEEDBACK.md` at the pack root via
 `kindgi feedback write` — see the `kindgi-framework-feedback` skill. Mark
 items fixed by adding a `> **Fixed:** <note>` line right after their
 header; the file is a plain markdown list you edit directly.
+Send entries to Kindgi only after the person has seen the preview and said
+yes: `kindgi feedback submit --preview`, then `--yes=<its digest>`.
 
 When the person asks how to use what you built (where something is in
 Kindgi's console, what an agent did, what it cost, who has access), answer

package/dist/templates/scala/AGENTS.md

@@ -40,6 +40,8 @@ loads `.claude/skills/` on its own; Codex and Gemini CLI look in
 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 with
 `./kindgiw feedback write`.
+Send entries to Kindgi only after the person has seen the preview and said
+yes: `./kindgiw feedback submit --preview`, then `--yes=<its digest>`.
 
 When the person asks how to use what you built (where something is in
 Kindgi's console, what an agent did, what it cost, who has access), answer

package/dist/templates/woocommerce/AGENTS.md

@@ -27,10 +27,15 @@ README.md explains the whole design; keep it true when you change the pack.
   that changes the store or moves money, unless the person you work for
   asks for exactly that.
 - **The refund limit is two tools.** Approval rules key on the tool, not
-  its arguments. `woo.refund` (no approval) is capped by its input schema
-  and its handler (`REFUND_LIMIT`, counting earlier refunds); larger
-  refunds go through `woo.refund-large` (always approved). Keep both caps
-  when you change one.
+  its arguments. `woo.refund` (no approval when a person starts the turn)
+  is capped by its input schema and its handler (`REFUND_LIMIT`, counting
+  earlier refunds); larger refunds go through `woo.refund-large` (always
+  approved). Keep both caps when you change one.
+- **Tools that move money or change the store declare
+  `needsApprovalWhenUnattended: true`** (`woo.refund`, `woo.refund-large`,
+  `woo.set-price`, `woo.publish-product`): in a run no person started, each
+  call waits for a person, and no agent's policy lifts that. Keep it on
+  them, and add it to any such tool you write.
 - **Order events are untrusted.** `woo.check-order-event` runs before
   any model sees an event and keeps typed fields only; the agent that
   reads events (`order-reviewer`) has read-only tools. Keep it that way:
@@ -53,6 +58,8 @@ pack's code), append an entry to `FEEDBACK.md` at the pack root via
 `kindgi feedback write` — see the `kindgi-framework-feedback` skill. Mark
 items fixed by adding a `> **Fixed:** <note>` line right after their
 header; the file is a plain markdown list you edit directly.
+Send entries to Kindgi only after the person has seen the preview and said
+yes: `kindgi feedback submit --preview`, then `--yes=<its digest>`.
 
 ## Commands for the person's own terminal
 

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

@@ -20,7 +20,7 @@ Scaffolded by `kindgi init --template=woocommerce`.
 ├── lib/fake-store.ts                           # a store in memory, for the tools' tests
 ├── tools/
 │   ├── find-orders/index.ts                    # look orders up (read-only)
-│   ├── refund/index.ts                         # refund up to 100, no approval
+│   ├── refund/index.ts                         # refund up to 100, no approval when a person asks
 │   ├── refund/index.test.ts                    # the limit, and each refund once, tested
 │   ├── refund-large/index.ts                   # refund any amount, approved first
 │   ├── refund-large/index.test.ts              # each refund once, tested
@@ -56,6 +56,17 @@ otherwise.
 | `{{PACK_ID}}.woo.set-price` | waits for a person | not given |
 | `{{PACK_ID}}.woo.publish-product` | waits for a person | not given |
 
+The store agent's three that wait need a second person
+(`conversationPolicy.hitl.separateApprover`). Whoever's turn asked for a
+large refund, a price change or a publish isn't offered **Approve** for it:
+another reviewer decides.
+
+The table is for a person's turn. The four tools that refund or change the
+store also declare `needsApprovalWhenUnattended`: in a run no person
+started (a webhook, a schedule or a service account's key started it),
+every call of one waits for a person, whatever the agent's policy says.
+So `{{PACK_ID}}.woo.refund` runs on its own only when a person asks for it.
+
 A call that waits shows in the console's approvals inbox, and in
 `{{KINDGI}} approvals list`. The tool runs only once a reviewer approves it
 (`{{KINDGI}} approvals complete <approval-id> --decision=approve`). A
@@ -114,12 +125,13 @@ The tools sign in to your store as a WordPress user made for the agent,
 with an Application Password. WordPress has had these since 5.6. Never use
 your own account.
 
-1. **Make the user.** In WordPress, go to Users → Add New User. Use a
-   username like `shop-agent` and the **Shop Manager** role, which can
+1. **Make the user.** In WordPress, go to Users → Add User (Add New User
+   before WordPress 6.8). Use a username like `shop-agent` and the **Shop Manager** role, which can
    manage orders and products but not the site.
 2. **Make its Application Password.** Edit that user (Users → All Users →
    `shop-agent`), find **Application Passwords**, name it `kindgi`, and
-   choose **Add New Application Password**. WordPress shows it once.
+   choose **Add Application Password** (**Add New Application Password**
+   before WordPress 6.8). WordPress shows it once.
    WordPress offers Application Passwords only over HTTPS, except on a
    site whose `WP_ENVIRONMENT_TYPE` is `local`.
 3. **Give them to Kindgi.** With `{{KINDGI}} dev` running, from another
@@ -296,3 +308,34 @@ refused deliveries in a row. `{{KINDGI}} webhooks list` and the trigger's
 fire history show what arrived. So change the signing secret when the store
 is quiet: until WooCommerce has the new one, Kindgi refuses its deliveries,
 and those orders aren't reviewed.
+
+## Ask and approve in WordPress
+
+**The store's staff can ask this pack's agents, and approve the refunds,
+without leaving wp-admin,** each as themselves. The Kindgi plugin for
+WordPress adds a Kindgi page with two tabs, Ask and Approvals. The record
+then says who approved, for example "approved by Jane, via Acme store", not
+"the store".
+
+1. **Install the plugin:** `kindgi-<version>.zip`, on the Kindgi SDK's
+   [latest release](https://github.com/kindgi/kindgi-sdk/releases/latest).
+   Its source is at
+   [`integrations/wordpress/kindgi`](https://github.com/kindgi/kindgi-sdk/tree/main/integrations/wordpress/kindgi).
+2. **Register the store as a site** on this pack's project. A tenant admin
+   runs `kindgi sites register` with `--project`, the store's origin and the
+   approvals URL the plugin's settings page shows.
+3. **Connect.** Paste the one-time code under Kindgi → Settings.
+
+**The runtime needs site sign-in on:**
+- `KINDGI_SITE_SIGN_IN=true`;
+- authorization enforced;
+- `KINDGI_PUBLIC_URL`.
+
+The plugin's README has the details:
+- where the signing key lives;
+- which WordPress roles may sign in;
+- what "the site vouches for its staff" means for four eyes.
+
+**When four eyes must be real,** for example two people for every refund,
+give the refund tools a required reviewer role above the site's ceiling. A
+person signed in to Kindgi directly then decides, never only the store.