@kindgi/cli 0.0.0-bootstrap.0 → 0.1.0

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

@@ -0,0 +1,291 @@
+---
+name: kindgi-authoring-guardrails
+description: >
+  Covers writing guardrails (safety checks) for a Kindgi pack: the check
+  implementation via defineCheck from @kindgi/sdk/define, the guardrail
+  declaration a pack file default-exports (the indexer's shape), the
+  three kinds (zero-llm / llm-judge / external), action semantics
+  (halt / retry / escalate / log-only / compensate), severity levels,
+  scope selectors, config schemas via Zod or JSON Schema, validating a
+  declaration with defineGuardrail from @kindgi/guardrails, and how
+  guardrails reach agents. Load this whenever you are authoring or
+  editing code inside a pack's guardrails/ directory, defining a check,
+  or wiring a guardrail onto an agent. Authoring tools is covered by
+  kindgi-authoring-tools; authoring agents is covered by
+  kindgi-authoring-agents.
+type: core
+library: "@kindgi/sdk"
+version: "0.3.5"
+sdk_version: "0.1.0"
+pack_languages: [node]
+sources:
+  - packages/guardrails/src/types.ts
+  - packages/guardrails/src/define-check.ts
+  - packages/guardrails/src/define.ts
+  - packages/guardrails/src/judge.ts
+  - packages/guardrails/src/checks.ts
+  - packages/handler-runtime/src/kindgi-index.ts
+  - packages/handler-runtime/src/handler-runner.ts
+---
+
+# Authoring Kindgi guardrails
+
+> **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.
+
+A **guardrail** is a safety rule an agent turn must satisfy. It combines
+a **check** (the function that inspects the turn's trace) with an
+**action** (what happens when the check fails). In a pack, a guardrail
+lives at `guardrails/<name>/index.ts`. For an agent turn, the runtime
+evaluates every guardrail the agent lists once, on the final response,
+before the response is stored.
+
+## Mental model: guardrail vs check
+
+- **Check** — the implementation. `defineCheck({ id, kind, configSchema?,
+  evaluate })` from `@kindgi/sdk/define` returns a registered check whose
+  `evaluate(config, trace, bindings)` resolves to `{ passed, reason? }`.
+  Zero-llm checks are pure over the trace.
+- **Guardrail** — the declaration: `id`, `kind`, the `check` it uses,
+  the check's `config`, and `action` / `severity` / `scope`. Its type is
+  `Guardrail` from `@kindgi/guardrails`. One check can back many
+  guardrails with different configs.
+- **Built-in checks** (`BUILT_IN_CHECK_IDS` in `@kindgi/guardrails`):
+  `must-cite`, `never-call-tool`, `max-tool-calls`, `output-matches`,
+  `tool-order`, `required-substring`, `forbidden-substring`. A guardrail
+  can name one of these instead of shipping its own check.
+
+`@kindgi/sdk` exports `defineCheck` but no helper for the guardrail
+itself: a pack file default-exports the declaration as a plain object.
+
+## A pack guardrail file (zero-llm)
+
+```ts
+// guardrails/no-fabricated-quotes/index.ts
+import { defineCheck } from '@kindgi/sdk/define';
+import { z } from 'zod';
+
+// The check implementation. The pack service calls `check.evaluate`.
+export const check = defineCheck({
+  id: 'acme.checks.no-fabricated-quotes',
+  kind: 'zero-llm',
+  configSchema: z.object({ minPrecedentCalls: z.number().int().min(0).optional() }),
+  evaluate: async (config, trace) => {
+    const needed = config.minPrecedentCalls ?? 1;
+    const precedentCalls = trace.toolCalls.filter((c) => c.toolName === 'acme.fetch-precedent');
+    if (precedentCalls.length < needed) {
+      return {
+        passed: false,
+        reason: `Only ${precedentCalls.length} precedent lookups (need ${needed}+).`,
+      };
+    }
+    return { passed: true };
+  },
+});
+
+// The guardrail declaration the indexer reads.
+export default {
+  id: 'acme.no-fabricated-quotes',
+  name: 'No fabricated quotations',
+  kind: 'zero-llm',
+  check,
+  action: { 'on-violation': 'halt' },
+  severity: 'critical',
+};
+```
+
+How the pack tooling reads this file:
+
+- The **indexer** (`packages/handler-runtime/src/kindgi-index.ts`)
+  recognises a guardrail by a default export with a `kind` and an
+  `action` object carrying `on-violation`. It records `id`, `name`,
+  `kind`, `action`, `severity`, `scope`, `sandbox` / `limits` /
+  `network`, and the check: its id (`check` may be the check id as a
+  string, or the check object) and its config schema (from the check's
+  `configZod`, `configSchema` or `configJsonSchema`, or a top-level
+  `configZod` / `configSchema`), and the declaration's `config` — what
+  the check runs with. It does not record `description`, `budget` or
+  `judgeCapabilities`.
+- The **pack service** loads the same module to run the check. It uses
+  the module's `evaluate` export, or the `default` / `check` export when
+  that is a function or has an `evaluate` method — here, the named
+  `check` export.
+
+## Validating a declaration in-process
+
+`defineGuardrail(spec, checks)` from `@kindgi/guardrails` validates a
+`Guardrail` against the wire schema and a check registry: the check id
+must be registered, the check's `kind` must match, and `config` must
+pass the check's config schema. It returns a `Result`; use it in tests
+or wherever guardrails are registered in-process.
+
+```ts
+import { createCheckRegistry, defineGuardrail } from '@kindgi/guardrails';
+import type { GuardrailId } from '@kindgi/sdk/types';
+
+import { check } from './index.js';
+
+const checks = createCheckRegistry([check]); // built-in checks are included
+const defined = defineGuardrail(
+  {
+    id: 'acme.no-fabricated-quotes' as GuardrailId,
+    kind: 'zero-llm',
+    check: check.id,
+    config: { minPrecedentCalls: 2 },
+    action: { 'on-violation': 'halt' },
+    severity: 'critical',
+  },
+  checks,
+);
+if (defined.kind === 'err') {
+  throw new Error(`acme.no-fabricated-quotes: ${defined.error.message}`);
+}
+```
+
+Registering a guardrail through the API (`POST /v1/guardrails`, or
+`client.guardrails.author(spec, { projectId })` in `@kindgi/sdk/client`)
+stores the declaration only; the check it names must already be
+available to the runtime that evaluates it.
+
+## Field-by-field
+
+- **`id`** — `<pack-id>.<guardrail-name>` (kebab-case, dot-namespaced).
+  Name the ASSERTION as a positive rule (e.g. `no-fabricated-quotes`,
+  `response-not-empty`, `must-cite-source`).
+- **`kind`**:
+  - `'zero-llm'` — pure function over the trace. Fast, deterministic,
+    free. **The default choice for most safety rules.**
+  - `'llm-judge'` — a model scores the turn against a rubric. Costs
+    money; requires `judgeCapabilities`. See below.
+  - `'external'` — evaluated outside the engine. The built-in
+    `external` strategy returns an `invalid-guardrail` error; a caller
+    that wants external evaluation registers its own strategy.
+- **`check`** — the id of a registered check (built-in, or one built
+  with `defineCheck`). In a pack file it may also be the check object.
+- **`config`** — the check's parameters, validated against the check's
+  `configSchema` by `defineGuardrail`. In a pack, the declaration's
+  `config` goes into the index and the check runs with it; without one
+  it runs with `{}`. `evaluate` receives the config as declared —
+  schema defaults are not filled in — so handle absent optional fields.
+- **`action.on-violation`** — `'halt'`, `'retry'` (with
+  `retry.maxAttempts`, 1–10), `'escalate'` (with `escalateTo`),
+  `'log-only'`, `'compensate'` (with `compensateWith`, a tool id). In an
+  agent turn, a failed `halt` guardrail fails the turn with
+  `guardrail-violation` and the response is not stored; failures with
+  any other action are reported in `AgentTurnResult.violations` and the
+  turn completes. The action handlers in `@kindgi/guardrails`
+  (`retryHandler`, `escalateHandler`, `compensateHandler`, …) record the
+  intent for callers that act on it.
+- **`severity`** — `'info'` / `'warn'` / `'error'` (the default) /
+  `'critical'`. Orthogonal to `action`: logs and dashboards group by
+  severity; execution follows the action. A `log-only` guardrail can
+  still be `'critical'`.
+- **`scope`** — when the guardrail applies. `{ when: 'always' }` fires
+  everywhere; `{ when: 'ci-only' }` blocks CI but not runtime;
+  `{ when: 'runtime-only' }` enforces at runtime but not CI. `agents`,
+  `flows` and `tenants` lists narrow it further.
+- **`budget`** — `{ maxCostUsd?, maxLatencyMs? }`, relevant to
+  `llm-judge`. Declarative: the runtime does not enforce it.
+- **`judgeCapabilities`** — for `llm-judge`: the capability
+  declaration used to route the judge model.
+
+## LLM-judge guardrail (costs money)
+
+An `llm-judge` guardrail does not run custom check code: the engine's
+`llm-judge` strategy sends the turn's trace and the rubric in `config`
+(`{ rubric, responseFormat?, threshold?, temperature? }`) to a model
+routed through `judgeCapabilities`, and parses a PASS/FAIL or a score.
+
+```ts
+import type { Guardrail } from '@kindgi/guardrails';
+import type { GuardrailId } from '@kindgi/sdk/types';
+
+export const toneProfessional: Guardrail = {
+  id: 'acme.tone-professional' as GuardrailId,
+  kind: 'llm-judge',
+  // Required by the `Guardrail` type; the llm-judge strategy judges
+  // with `config` and does not call this check.
+  check: 'acme.checks.tone-professional',
+  config: {
+    rubric: 'The response is professional in tone and contains no slang.',
+    responseFormat: 'pass-fail',
+  },
+  judgeCapabilities: { needs: [{ feature: 'structured-output' }] },
+  action: { 'on-violation': 'log-only' },
+  severity: 'warn',
+  budget: { maxCostUsd: 0.01, maxLatencyMs: 5000 }, // declarative, not enforced
+};
+```
+
+The judge is resolved from the provider registry passed in the
+evaluation bindings (or a pinned `judgeProvider`), under the tenant
+policy in those bindings when one is passed. Checks that run in a pack are called with empty
+`bindings` — no provider registry — so a pack check cannot call a model
+itself; use `kind: 'llm-judge'` for model-based rules.
+
+## Wiring the guardrail onto an agent
+
+Agents reference guardrails by id:
+
+```ts
+// agents/brief-writer/index.ts
+guardrails: ['acme.no-fabricated-quotes'],
+```
+
+At the start of each turn, the runtime resolves these ids against the
+guardrails available to the run. An id that isn't registered fails the
+turn with `unresolved-guardrail`, so register the guardrail before an
+agent references it.
+
+## Changing a guardrail
+
+Guardrails have no `version` field; the id is the stable identifier.
+Changing a guardrail's check, config, severity or action changes
+behavior for every agent that references it. When you tighten a rule
+(raise severity from `warn` to `error`, switch the action from
+`log-only` to `halt`), check whether the agents that reference it are
+ready for the stricter enforcement.
+
+## Common mistakes
+
+1. **Confusing guardrail and check.** The id in `agent.guardrails: [...]`
+   is the GUARDRAIL id, not the check id. The agent binds to
+   guardrails; guardrails reference checks.
+
+2. **A check whose `evaluate` always returns `passed: true`.** If you
+   are stubbing the check, give the guardrail `action: { 'on-violation':
+   'log-only' }` so it is honest about not being enforced.
+
+3. **Calling a model from a pack check.** Pack checks receive empty
+   `bindings`; there is no provider registry to route through. Declare
+   an `llm-judge` guardrail with a rubric instead.
+
+4. **Not declaring `configSchema`.** Without it, `config` is
+   `Record<string, unknown>` — no validation, no editor completion,
+   silent typos. Prefer Zod for TS-side inference on
+   `evaluate(config, ...)`.
+
+5. **Ignoring the `Result` from `defineGuardrail`.** It returns
+   `Result<Guardrail, …>`; check `kind` and throw at load time.
+   `defineCheck` itself throws when its `configSchema` can't be
+   compiled.
+
+## References
+
+- Type surface: hover any `@kindgi/sdk/define` export for full JSDoc;
+  `Guardrail`, `defineGuardrail` and the built-in checks are in
+  `@kindgi/guardrails`.
+- Companion docs: `pnpm --filter @kindgi/sdk exec typedoc`.
+- Built-in check implementations: `packages/guardrails/src/checks.ts`.
+
+## When the framework itself is the problem
+
+If you diagnose that the bug lives in Kindgi/`@kindgi/sdk` itself
+(guardrail runtime dropping context fields, check-sandbox dispatch
+regression, 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.

package/dist/sdk-skills/kindgi-authoring-mcp-servers/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: kindgi-authoring-mcp-servers
+description: >
+  Wire an MCP server into a Kindgi pack so the coding agent (Claude Code,
+  Cursor, VS Code, Windsurf, …) can discover a live external resource
+  through tools instead of asking the user to paste schemas or values.
+  Uses `kindgi secrets set` for the credential (interactive, no-echo) and
+  `kindgi mcp add <preset>` to write `.mcp.json` at the pack root. The
+  launcher (`kindgi mcp-launch`) spawns the actual MCP server as a
+  subprocess with the secret injected into its env — never onto the
+  model's transcript. Load this when the user says "I have a Postgres
+  URL, can you look at the schema", "connect to my database", "wire
+  MCP", "add a Postgres MCP", "let CC query my DB", "I don't want to
+  paste my table shape", or when the model is about to ask the user to
+  paste external schema/data that Kindgi could discover through MCP.
+  Credential storage is covered by kindgi-authoring-providers's
+  `kindgi secrets set` flow.
+type: core
+library: "@kindgi/sdk"
+version: "0.3.0"
+sdk_version: "0.1.0"
+pack_languages: [node, python]
+---
+
+# Wiring an MCP server for a Kindgi pack
+
+> **Running `kindgi`:** in a Node project the CLI is a devDependency
+> (`@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 …`. A Python pack (`[tool.kindgi]` in
+> `pyproject.toml`) has no Node project: run the `kindgi` on `PATH`.
+> Commands below are written `kindgi …` for brevity.
+
+If the user has an external resource (Postgres DB, GitHub org, Notion
+workspace, …) that would be useful to a coding agent, **wire an MCP
+server** rather than asking the user to paste values. Kindgi keeps the
+credential out of the model's transcript by injecting it into the
+subprocess's environment; the model only sees the tools the MCP server
+exposes.
+
+## When to reach for this
+
+Reach for MCP when the user hands you a live external resource by
+reference (URL, host + credential, workspace id). Signals from the
+user:
+- "I have a Postgres database at $URL"
+- "Connect to my Notion workspace at $TOKEN"
+- "Let CC look at the schema of my DB"
+- "Don't paste it, just query it"
+
+**Do NOT reach for MCP when:**
+- The resource is a static file the user has locally (just Read it).
+- The resource is best-inspected once by a human (a one-shot answer, no
+  agent tools needed).
+- The user is in a client that hasn't loaded `.mcp.json` yet — they'll
+  need to restart their MCP client after `kindgi mcp add` (see gotcha
+  #2 below).
+
+## Mental model
+
+```
+Kindgi's SecretBinding      .mcp.json (pack root)      launcher subprocess       MCP server subprocess
+─────────────────────       ────────────────────       ──────────────────        ────────────────────
+MY_DB_URL=…       →  { "command": "pnpm",    →  reads .env +         →   spawns child with
+(.env / .env.local, or           "args": ["exec","kindgi", .env.local (the      DATABASE_URI in env,
+ `kindgi secrets set`)            "mcp-launch", "--", …] } pack env files),     stdio piped to CC
+                                     │                   substitutes secret       ▲     │
+                                     │                   into child env           │     ▼
+                                     ▼                          │            MCP protocol (stdio)
+                            Claude Code / Cursor spawns          │             ▲     │
+                            `kindgi mcp-launch …` at             │             │     ▼
+                            startup ─────────────────────────────┘         ┌─────────────────┐
+                                                                            │  Claude Code    │
+                                                                            │  (or Cursor…)   │
+                                                                            └─────────────────┘
+```
+
+Three moving parts:
+
+1. **The secret on disk** — for `local`, the project's env files at the
+   pack root (`.env`, then `.env.local`; `dev.envFiles` to change);
+   other environments use `.env.<envName>`. Add it by hand or with
+   `kindgi secrets set` (interactive no-echo prompt; never the value on
+   argv), which writes `.env.local`. See `kindgi-authoring-providers`
+   for the same flow used for LLM API keys.
+2. **`.mcp.json` at the pack root** — Kindgi writes this via
+   `kindgi mcp add`. Every entry runs the project's own `kindgi
+   mcp-launch -- <launcher-flags>...` through its package manager
+   (`"command": "pnpm", "args": ["exec", "kindgi", "mcp-launch", …]`;
+   npm: `npx --no kindgi …`) — never a global `kindgi`, never a
+   download. A Python pack has no Node project, so its entries run the
+   `kindgi` on `PATH` (`"command": "kindgi", "args": ["mcp-launch", …]`).
+   The file is safe to commit — it references secrets by NAME, not
+   value.
+3. **The launcher** — `kindgi mcp-launch` is what the coding agent
+   actually spawns. It reads the referenced secret from the pack env files,
+   injects it into the child MCP server's env, and pipes stdio through.
+
+## Path A — Postgres
+
+Best-worn path. Uses `crystaldba/postgres-mcp` via Docker with
+read-only access mode by default.
+
+**Step 1 — set the DB URL** (interactive, no-echo):
+
+```sh
+kindgi secrets set MY_DB_URL --env=local --scope=tenant
+# paste postgres://user:pass@host:port/db, press enter
+```
+
+For pipelines/CI: `pbpaste | kindgi secrets set … --from-stdin`, or
+`--from-file=<path>` on a mode-0600 file. Never pass the value on argv.
+
+**Step 2 — wire the MCP server:**
+
+```sh
+kindgi mcp add postgres --secret=MY_DB_URL
+```
+
+Writes `.mcp.json` at the pack root (or merges into an existing one).
+The server name defaults to `my_db` (derived from the secret
+name — see "Server naming" below). Override with `--server-name=<label>`.
+
+**Step 3 — restart your MCP client.** MCP servers are loaded at client
+startup — a fresh `.mcp.json` doesn't take effect mid-session:
+- **Claude Code:** exit + `claude` again in the same pack dir
+- **Cursor:** ⌘⇧P → "Restart Extension Host" (or restart the app)
+- **Claude Desktop:** quit + reopen
+- **Windsurf:** Command Palette → "Restart Windsurf"
+
+**Step 4 — use it.** Tools like `execute_sql`, `list_tables`,
+`analyze_index_health` now appear. Ask the agent things like "what
+tables are in this schema?" or "what's the shape of the customers
+table?" or "how many rows are in orders where created_at > 2024?".
+
+## Path B — Multiple servers in the same pack
+
+Two connections against different DBs? Two `mcp add` invocations,
+each with its own `--secret` and `--server-name`:
+
+```sh
+kindgi secrets set MY_DB_URL --env=local --scope=tenant
+kindgi secrets set ANALYTICS_DB_URL --env=local --scope=tenant
+
+kindgi mcp add postgres --secret=MY_DB_URL --server-name=my_db
+kindgi mcp add postgres --secret=ANALYTICS_DB_URL --server-name=analytics_db
+```
+
+`.mcp.json` gets two entries. The agent picks the right one by name
+when it invokes a tool (e.g. `my_db.execute_sql`).
+
+## Server naming
+
+`--server-name` defaults are derived from the secret name:
+
+| Secret name | Default server name |
+|---|---|
+| `MY_DB_URL` | `my_db` |
+| `ANALYTICS_DB_URL` | `analytics_db` |
+| `ANTHROPIC_API_KEY` | `anthropic_api` |
+| `GITHUB_PAT` | `github` |
+| `DB_PASSWORD` | `db` |
+
+The suffix-stripping (`_url` / `_uri` / `_key` / `_token` / `_pat` /
+`_secret` / `_password`) is intentional — the server name should
+describe the *resource*, not the *credential shape*. Override with
+`--server-name=<label>` when the default reads wrong.
+
+## Path C — Non-Claude-Code clients
+
+`.mcp.json` at the pack root is what Claude Code reads natively. Other
+clients read from their own paths (`.cursor/mcp.json`, `.vscode/mcp.json`,
+Claude Desktop's system-wide config). To bridge:
+
+1. Establish a symlink from the client's expected path to `.mcp.json`:
+   ```sh
+   mkdir -p .cursor && ln -sfn ../.mcp.json .cursor/mcp.json
+   ```
+2. Restart the client.
+
+Symlinks work because the FILE CONTENTS are portable across every MCP
+client — the `mcpServers` block has the same shape everywhere. Only
+the file LOCATION differs. Edits to `.mcp.json` flow through
+automatically via the symlink; no re-sync needed.
+
+Windows users without dev-drive symlinks: `cp .mcp.json .cursor/mcp.json`,
+and re-copy after every `kindgi mcp` edit.
+
+## Verifying end-to-end
+
+```sh
+# 1. Check the secret exists
+kindgi secrets list --env=local --scope=tenant
+
+# 2. Check .mcp.json
+kindgi mcp list
+
+# 3. Check available presets
+kindgi mcp presets
+```
+
+`kindgi mcp list` prints the configured servers with their launcher
+argv shape. `kindgi mcp presets` shows what presets are available and
+their audit status. If the postgres preset audit says
+`urlLeakInErrors: "pending"`, that's a known unresolved item — see
+gotcha #4.
+
+## Common mistakes
+
+1. **Reading `.mcp.json` mid-session and asking about it.** `.mcp.json`
+   references secrets by NAME (e.g. `secret:MY_DB_URL@local:tenant`),
+   not by value. Safe to Read + describe to the user. **Do NOT** run
+   `cat .env`, `env | grep`, or Read `.env` / `.env.local` — those return
+   the raw URL, which enters your transcript, gets sent to the model
+   provider on every subsequent turn, and can be exfiltrated via
+   prompt injection. Once a secret is in a model's context, it's a
+   rotation event, not a "clean up the log" event.
+
+2. **Expecting the new server to activate without a restart.** MCP
+   servers are loaded at client startup. `kindgi mcp add` writes the
+   config file; the CLIENT doesn't re-scan it until a restart. Tell
+   the user to restart their client after `mcp add`, and don't call
+   MCP tools before that restart happens in your current session.
+
+3. **`--env` / `--scope` mismatch between `secrets set` and `mcp add`.**
+   Both flags need to agree — the launcher looks up the secret using
+   whatever `--env` + `--scope` you passed to `mcp add`. Default is
+   `--env=local --scope=tenant`; match this on both commands.
+
+4. **Trusting a preset's audit metadata that says `pending`.** Every
+   preset carries `audit.urlLeakInErrors`. Only `"verified-safe"` means
+   someone has confirmed the wrapped MCP server doesn't echo the
+   secret in its error/debug output. `"pending"` means the audit
+   hasn't run — the server may or may not leak. When you see a
+   `pending` preset in a session that handles real credentials, tell
+   the user: "this preset works but its URL-echo safety isn't
+   verified for this version; watch tool error messages for the raw
+   URL, and file feedback if you see one."
+
+5. **Trying to use MCP against a `localhost` DB from Docker on Mac
+   without the host-remap.** Docker containers on Mac can't reach the
+   host's `localhost`. The `postgres` preset carries `hostRemap:
+   "docker-desktop"`, which the launcher applies automatically — it
+   rewrites `@localhost` / `@127.0.0.1` in the resolved URL to
+   `@host.docker.internal` before injecting into the container's env.
+   If you author a preset with a Docker runtime + a localhost
+   consumer, include `"hostRemap": "docker-desktop"` in the preset JSON.
+
+6. **`kindgi mcp add` fails with "Secret X not in .env, .env.local".** The
+   secret hasn't been stored yet. Run `kindgi secrets set X --env=local
+   --scope=tenant` first. The error message includes this fix pointer.
+
+## Security discipline
+
+The invariants this skill inherits — every bullet here is enforced by
+you, the coding agent, in the session where MCP is wired:
+
+- **Never Read `.env`, `.env.local` or `.env.<envName>` files.** Their contents are the raw
+  secret values. Reading them puts the secret in your tool result and
+  from there in every subsequent turn's context sent to the model
+  provider.
+- **Never run `env | grep SECRET_NAME`, `printenv SECRET_NAME`, or
+  equivalent** in a bash tool. Same failure — the value returns in the
+  tool result.
+- **When a tool errors, check the error message before summarizing.**
+  Some MCP servers echo the connection string in `connection refused`
+  errors. If you see the URL in a tool error, redact when
+  summarizing to the user, and file the incident via the
+  `kindgi-framework-feedback` skill so the preset's audit gets updated.
+- **Prefer `kindgi mcp list` over Reading `.mcp.json`** when the user
+  asks "what's configured?" — the list output has the same info in a
+  cleaner shape and is safe to include in your reply.
+- **Never repeat the resolved URL back to the user** — even in a
+  "here's what I wired up" summary. Refer to the secret by NAME and
+  to the server by its `.mcp.json` label. The point of MCP is that
+  the value stays out of every layer that a model can see; repeating
+  it in your reply defeats the invariant.
+
+## When the framework itself is the problem
+
+If you diagnose that the bug lives in Kindgi/`@kindgi/cli` itself
+(`kindgi mcp add` writes malformed JSON, `mcp-launch` hangs, a preset
+has bad `defaultArgs`, launcher can't resolve a secret that clearly
+exists in the pack env files, an MCP server echoes the URL in its
+error tool result) — not in your pack's `.mcp.json` or secret setup —
+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.