toolfunnel 0.5.0 → 0.6.0

package/src/extend/add-hook.md

@@ -1,142 +1,152 @@
-# How to add a hook (self-extension)
-
-This is the instruction served by `toolfunnel_howto({ topic: "add-hook" })`. It explains how to add a hook
-to the Hook Engine: the manifest entry shape, where the script goes, and how the enabled/disabled
-state is persisted separately in `hooks.state.json`. The full contract is HOOK_ENGINE.md — this is
-the authoring view.
-
-A hook is exactly two things:
-1. **A manifest entry** in `hooks/hooks.manifest.json` (its config: event, matcher, command, …).
-2. **A script** under `hooks/scripts/` that the entry's `command` runs.
-
-Activation (on/off) is NOT in the manifest's source of truth at runtime — it lives in an overlay,
-`hooks/hooks.state.json` (see §4).
-
----
-
-## 1. The manifest entry shape
-
-`hooks.manifest.json` has `version`, `hooksDir`, and a `hooks` array. Each entry:
-
-```json
-{
-  "id": "pre-tool-use/deny-dangerous",
-  "event": "PreToolUse",
-  "matcher": "Bash|toolfunnel_run_tool",
-  "type": "command",
-  "command": "bash \"${HOOKS_DIR}/scripts/deny-dangerous.sh\"",
-  "script": "scripts/deny-dangerous.sh",
-  "timeout": 5,
-  "enabled": true,
-  "description": "Denies any tool call whose args contain a destructive pattern (rm -rf, etc)."
-}
-```
-
-| Field | Type | Meaning |
-|---|---|---|
-| `id` | string | Unique key, format `"<kebab-event>/<script-basename-without-ext>"` (e.g. `pre-tool-use/deny-dangerous`). The loader and `hooks.state.json` key on this. |
-| `event` | string | One of the six lifecycle events: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`, `PreCompact`. |
-| `matcher` | string | Regex anchored full-match against `tool_name`. `""`, `undefined`, or `"*"` = always fire. Tool-less events (SessionStart, UserPromptSubmit, Stop, PreCompact) ignore it. Example: `"Bash|Write|Edit"`. |
-| `type` | string | `"command"` (the only type today). |
-| `command` | string | The command line the runner spawns. `${HOOKS_DIR}` expands to the absolute `hooks` path at load time. |
-| `script` | string | The script path relative to `hooksDir`, e.g. `scripts/deny-dangerous.sh`. Used by the manager's open/edit (`readScript`/`writeScript`). |
-| `timeout` | number | **Seconds** (the runner multiplies by 1000). The runner kills the child past this. |
-| `enabled` | boolean | The manifest's default/seed state. The live value is the overlay in `hooks.state.json` — see §4. |
-| `description` | string | What the hook does, for the manager UI. |
-
-One entry **per hook command** — a settings.json event with N hooks becomes N entries.
-
----
-
-## 2. Where the script goes
-
-```
-hooks/
-  hooks.manifest.json    # config entries (above)
-  hooks.state.json       # enabled/disabled overlay, keyed by hook id
-  scripts/               # your hook scripts live HERE
-    deny-dangerous.sh
-```
-
-(The loader itself — `hook-loader.js` — is engine code and is NOT user content; it lives in
-`src/core/`, not in `hooks/`.)
-
-`writeScript` (the manager's save path) refuses any path that resolves outside
-`hooks/scripts/` — defense-in-depth for the isolation rule. Author your script there only;
-never point a hook at a script in a live host hooks directory. Clone the behaviour in if you need it.
-
----
-
-## 3. What the script returns (the two protocols)
-
-The runner spawns the command, writes the event payload as JSON on stdin, then reads the result.
-Two protocols (HOOK_ENGINE.md §3):
-
-**A) Exit-code (simple):**
-- `exit 0` → success. On `SessionStart`/`UserPromptSubmit`, stdout becomes **injected context**;
-  on other events stdout is advisory.
-- `exit 2` → **blocking**. stderr is the reason.
-- any other code → non-blocking error (stderr captured, loop continues; never throws).
-
-**B) JSON (advanced)** — honored **only on exit 0**, when stdout parses as a JSON object:
-```json
-{
-  "continue": true,
-  "decision": "block",
-  "reason": "…",
-  "hookSpecificOutput": {
-    "hookEventName": "PreToolUse",
-    "permissionDecision": "allow" | "deny" | "ask",
-    "permissionDecisionReason": "…",
-    "additionalContext": "…"
-  }
-}
-```
-- **PreToolUse blocks via `hookSpecificOutput.permissionDecision: "deny"`** — NOT the top-level
-  `decision` field. `"allow"` passes; `"ask"` is non-blocking in the autonomous host.
-- **Top-level `decision: "block"`** is for the other blockable events (UserPromptSubmit, PostToolUse,
-  Stop, PreCompact). There is no `"approve"`.
-- `continue: false` stops the whole loop. `hookSpecificOutput.additionalContext` → injected text.
-
-This is the mechanism that makes a PreToolUse hook gate `toolfunnel_run_tool`: match its `tool_name`, and
-return `permissionDecision: "deny"` to block the call before the tool runs.
-
----
-
-## 4. Activation state lives in `hooks.state.json`
-
-The Hook Manager design splits **what exists** from **what's on**:
-
-- **The `scripts/` folder is the source of truth for what exists.** On startup the loader scans it
-  and reconciles with the manifest: newly-found scripts are added as entries (event/matcher inferred
-  or flagged "unconfigured"); manifest entries whose script is missing are flagged.
-- **The manifest carries config** (event, matcher, command, timeout, description, seed `enabled`).
-- **`hooks.state.json` is the activation overlay** — an object keyed by hook `id` recording the live
-  enabled/disabled value:
-
-```json
-{
-  "version": 1,
-  "enabled": {
-    "pre-tool-use/deny-dangerous": true,
-    "user-prompt-submit/inject-context": false
-  }
-}
-```
-
-Toggling a hook writes `hooks.state.json` **atomically** (temp + rename). It survives restarts and is
-kept separate from the auto-detected inventory, so re-scanning the folder never clobbers your toggles.
-At load, the overlay wins over the manifest's seed `enabled` for any id it lists.
-
----
-
-## 5. Steps to add a hook
-
-1. Write the script into `hooks/scripts/<name>.sh` (or a node script). Read the stdin JSON
-   payload; emit one of the two protocols above.
-2. Add the manifest entry: `id` = `"<kebab-event>/<name>"`, set `event`, `matcher`, `command`
-   (`bash "${HOOKS_DIR}/scripts/<name>.sh"`), `script`, `timeout` (seconds), `description`, and a
-   seed `enabled`.
-3. Set its live state in `hooks.state.json` via the loader's `setEnabled(id, bool)` (atomic write).
-4. Verify: the manager lists it under its event; a run-once test fires it with a sample payload and
-   shows the result. For a gate, confirm a matching `toolfunnel_run_tool` call is denied with your reason.
+# How to add a hook (self-extension)
+
+This is the instruction served by `toolfunnel_howto({ topic: "add-hook" })`. It explains how to add a hook
+to the Hook Engine: the manifest entry shape, where the script goes, and how the enabled/disabled
+state is persisted separately in `hooks.state.json`. The full contract is HOOK_ENGINE.md - this is
+the authoring view.
+
+A hook is exactly two things:
+1. **A manifest entry** in `hooks/hooks.manifest.json` (its config: event, matcher, command, ...).
+2. **A script** under `hooks/scripts/` that the entry's `command` runs.
+
+Activation (on/off) is NOT in the manifest's source of truth at runtime - it lives in an overlay,
+`hooks/hooks.state.json` (see §4).
+
+---
+
+## 1. The manifest entry shape
+
+`hooks.manifest.json` has `version`, `hooksDir`, and a `hooks` array. Each entry:
+
+```json
+{
+  "id": "pre-tool-use/deny-dangerous",
+  "event": "PreToolUse",
+  "matcher": "Bash|toolfunnel_run_tool",
+  "type": "command",
+  "command": "bash \"${HOOKS_DIR}/scripts/deny-dangerous.sh\"",
+  "script": "scripts/deny-dangerous.sh",
+  "timeout": 5,
+  "enabled": true,
+  "description": "Denies any tool call whose args contain a destructive pattern (rm -rf, etc)."
+}
+```
+
+| Field | Type | Meaning |
+|---|---|---|
+| `id` | string | Unique key, format `"<kebab-event>/<script-basename-without-ext>"` (e.g. `pre-tool-use/deny-dangerous`). The loader and `hooks.state.json` key on this. |
+| `event` | string | One of the six lifecycle events: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`, `PreCompact`. |
+| `matcher` | string | Regex anchored full-match against `tool_name`. `""`, `undefined`, or `"*"` = always fire. Tool-less events (SessionStart, UserPromptSubmit, Stop, PreCompact) ignore it. Example: `"Bash|Write|Edit"`. |
+| `type` | string | `"command"` (the only type today). |
+| `command` | string | The command line the runner spawns. `${HOOKS_DIR}` expands to the absolute `hooks` path at load time. |
+| `script` | string | The script path relative to `hooksDir`, e.g. `scripts/deny-dangerous.sh`. Used by the manager's open/edit (`readScript`/`writeScript`). |
+| `timeout` | number | **Seconds** (the runner multiplies by 1000). The runner kills the child past this. |
+| `enabled` | boolean | The manifest's default/seed state. The live value is the overlay in `hooks.state.json` - see §4. |
+| `description` | string | What the hook does, for the manager UI. |
+
+One entry **per hook command** - a settings.json event with N hooks becomes N entries.
+
+---
+
+## 2. Where the script goes
+
+```
+hooks/
+  hooks.manifest.json    # config entries (above)
+  hooks.state.json       # enabled/disabled overlay, keyed by hook id
+  scripts/               # your hook scripts live HERE
+    deny-dangerous.sh
+```
+
+(The loader itself - `hook-loader.js` - is engine code and is NOT user content; it lives in
+`src/core/`, not in `hooks/`.)
+
+`writeScript` (the manager's save path) refuses any path that resolves outside
+`hooks/scripts/` - defense-in-depth for the isolation rule. Author your script there only;
+never point a hook at a script in a live host hooks directory. Clone the behaviour in if you need it.
+
+---
+
+## 3. What the script returns (the two protocols)
+
+The runner spawns the command, writes the event payload as JSON on stdin, then reads the result.
+The payload a tool event receives on stdin:
+
+```json
+{ "tool_name": "note_slow", "tool_input": { "arg": "value" } }
+```
+
+(`PreToolUse` → `tool_name` + `tool_input`; `PostToolUse` adds `tool_response`. Tool-less
+events carry their own fields - `prompt`, `source` - instead.)
+
+Two protocols (HOOK_ENGINE.md §3):
+
+**A) Exit-code (simple):**
+- `exit 0` → success. On `SessionStart`/`UserPromptSubmit`, stdout becomes **injected context**;
+  on other events stdout is advisory.
+- `exit 2` → **blocking**. stderr is the reason - on a blocked tool call the client receives it
+  as the result text with `isError: true`.
+- any other code → non-blocking error (stderr captured, loop continues; never throws).
+
+**B) JSON (advanced)** - honored **only on exit 0**, when stdout parses as a JSON object:
+```json
+{
+  "continue": true,
+  "decision": "block",
+  "reason": "...",
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "allow" | "deny" | "ask",
+    "permissionDecisionReason": "...",
+    "additionalContext": "..."
+  }
+}
+```
+- **PreToolUse blocks via `hookSpecificOutput.permissionDecision: "deny"`** - NOT the top-level
+  `decision` field. `"allow"` passes; `"ask"` is non-blocking in the autonomous host.
+- **Top-level `decision: "block"`** is for the other blockable events (UserPromptSubmit, PostToolUse,
+  Stop, PreCompact). There is no `"approve"`.
+- `continue: false` stops the whole loop. `hookSpecificOutput.additionalContext` → injected text.
+
+This is the mechanism that makes a PreToolUse hook gate `toolfunnel_run_tool`: match its `tool_name`, and
+return `permissionDecision: "deny"` to block the call before the tool runs.
+
+---
+
+## 4. Activation state lives in `hooks.state.json`
+
+The Hook Manager design splits **what exists** from **what's on**:
+
+- **The `scripts/` folder is the source of truth for what exists.** On startup the loader scans it
+  and reconciles with the manifest: newly-found scripts are added as entries (event/matcher inferred
+  or flagged "unconfigured"); manifest entries whose script is missing are flagged.
+- **The manifest carries config** (event, matcher, command, timeout, description, seed `enabled`).
+- **`hooks.state.json` is the activation overlay** - an object keyed by hook `id` recording the live
+  enabled/disabled value:
+
+```json
+{
+  "version": 1,
+  "enabled": {
+    "pre-tool-use/deny-dangerous": true,
+    "user-prompt-submit/inject-context": false
+  }
+}
+```
+
+Toggling a hook writes `hooks.state.json` **atomically** (temp + rename). It survives restarts and is
+kept separate from the auto-detected inventory, so re-scanning the folder never clobbers your toggles.
+At load, the overlay wins over the manifest's seed `enabled` for any id it lists.
+
+---
+
+## 5. Steps to add a hook
+
+1. Write the script into `hooks/scripts/<name>.sh` (or a node script). Read the stdin JSON
+   payload; emit one of the two protocols above.
+2. Add the manifest entry: `id` = `"<kebab-event>/<name>"`, set `event`, `matcher`, `command`
+   (`bash "${HOOKS_DIR}/scripts/<name>.sh"`), `script`, `timeout` (seconds), `description`, and a
+   seed `enabled`.
+3. Set its live state in `hooks.state.json` via the loader's `setEnabled(id, bool)` (atomic write).
+4. Verify: the manager lists it under its event; a run-once test fires it with a sample payload and
+   shows the result. For a gate, confirm a matching `toolfunnel_run_tool` call is denied with your reason.

package/src/extend/add-mcp.md

@@ -1,121 +1,122 @@
-# How to register an upstream MCP (self-extension)
-
-This is the instruction served by `toolfunnel_howto({ topic: "add-mcp" })`. It explains how to connect an
-**upstream MCP server** (a browser-automation MCP, a chat bridge, …) to the aggregator and choose **which of its
-tools to expose downstream** to the CLI. All of this is configured in one persisted file:
-`mcp/expose.json`.
-
-The architecture (see the architecture overview, §1): many upstream MCPs each expose many tools; the
-aggregator connects to them and the **MCP Manager picks which tools to surface** to the CLI as
-*curated-direct* tools — alongside the four lean meta-tools (`toolfunnel_list_tools`,
-`toolfunnel_tool_instructions`, `toolfunnel_run_tool`, `toolfunnel_howto`). The CLI sees a small surface; everything
-else stays reachable through the register.
-
-> Phase note: the live aggregator (`src/mcp/aggregator.js`) is Phase 2. This doc defines the
-> `expose.json` shape so the config is authorable now and the aggregator reads exactly these fields
-> when it lands.
-
----
-
-## 1. `expose.json` — the two blocks
-
-`expose.json` persists (a) the upstream MCP connections and (b) the curated-direct selection drawn
-from them:
-
-```json
-{
-  "version": 1,
-  "upstreams": [
-    {
-      "id": "chat",
-      "transport": "stdio",
-      "command": "node",
-      "args": ["vendor/chat-mcp/server.js"],
-      "env": { "CHAT_DB": "..." },
-      "enabled": true,
-      "description": "Chat bridge MCP — chats, messages, send."
-    },
-    {
-      "id": "browser",
-      "transport": "stdio",
-      "command": "npx",
-      "args": ["@example/browser-mcp"],
-      "enabled": false,
-      "description": "Browser automation MCP."
-    }
-  ],
-  "expose": [
-    {
-      "upstream": "chat",
-      "tool": "list_chats",
-      "as": "chat_list_chats",
-      "category": "chat",
-      "enabled": true
-    },
-    {
-      "upstream": "chat",
-      "tool": "send_message",
-      "as": "chat_send_message",
-      "category": "chat",
-      "enabled": true
-    }
-  ]
-}
-```
-
-### `upstreams[]` — one entry per upstream MCP
-
-| Field | Type | Meaning |
-|---|---|---|
-| `id` | string | Stable key for this upstream. Referenced by `expose[].upstream`. Unique. |
-| `transport` | string | How the aggregator connects. `"stdio"` (spawn `command`+`args`) is the baseline. |
-| `command` / `args` / `env` | string / string[] / object | The process the aggregator spawns for a `stdio` upstream. Paths must point **inside the project's vendor directory** (clone vendored servers in; never reference servers configured elsewhere on the host). |
-| `enabled` | boolean | Whether the aggregator connects to this upstream at startup. |
-| `description` | string | Human-facing note for the MCP Manager UI. |
-
-### `expose[]` — which upstream tools become curated-direct
-
-| Field | Type | Meaning |
-|---|---|---|
-| `upstream` | string | Must match an `upstreams[].id`. |
-| `tool` | string | The upstream tool's own name (as the upstream's `tools/list` reports it). |
-| `as` | string | The downstream name the CLI sees (namespaced so two upstreams can't collide, e.g. `chat_send_message`). Optional — defaults to `<upstream>_<tool>`. |
-| `category` | string | Grouping label, same convention as register entries. |
-| `enabled` | boolean | Whether this tool is actually exposed downstream right now. |
-
-Only the tools listed in `expose[]` with `enabled: true` are surfaced to the CLI as curated-direct
-tools. Everything else on the upstream stays connected but hidden — reachable, if needed, by adding
-an `expose` entry (no upstream reconnect required to *list*, though see §3 on the CLI surface).
-
----
-
-## 2. Steps to register an upstream and expose a tool
-
-1. Add an entry to `upstreams[]` with a unique `id`, the `stdio` `command`/`args`, and
-   `enabled: true`. Vendor the server **inside the project's vendor directory** if it isn't already.
-2. Let the aggregator connect and run the upstream's `tools/list` (the MCP Manager UI surfaces the
-   discovered tools).
-3. For each tool you want hot, add an `expose[]` entry: `{ upstream, tool, as, category, enabled:true }`.
-4. Leave the long tail unexposed — the model can still reach those via the register/meta-tools if you
-   later mirror them, but the *curated-direct* surface stays lean by design (the dial in §1 of the
-   architecture: directly-exposed = the HOT tools; the register meta-tools = the long tail).
-
----
-
-## 3. Curated-direct vs. the register (update cost)
-
-This matters because the two layers refresh differently (see the architecture overview, §1):
-
-- **Curated-direct tools** (what `expose[]` produces) are negotiated with the CLI **at connect time**.
-  Changing the exposed set therefore needs a **reconnect**, or a `notifications/tools/list_changed`
-  message *if the CLI honours it* (VERIFY per host; restart is the safe baseline).
-- **Register tools** (the `toolfunnel_list_tools`/`run` path) are **always live** — the model re-reads the
-  register on every `toolfunnel_list_tools` call, so no reconnect is needed.
-
-Rule of thumb: expose a handful of HOT, high-reliability tools curated-direct; everything else lives
-in the register and is reached through the meta-tools.
-
-> Safety: a curated-direct upstream tool is still ultimately invoked by the model. When you wire
-> upstream execution through the host, route it through the same PreToolUse gate the register's `run`
-> uses (see `toolfunnel_howto({ topic: "add-hook" })`) so the safety invariant holds uniformly. The gate
-> firing on every execution path is a tested invariant, not an assumption.
+# How to register an upstream MCP (self-extension)
+
+This is the instruction served by `toolfunnel_howto({ topic: "add-mcp" })`. It explains how to connect an
+**upstream MCP server** (a browser-automation MCP, a chat bridge, ...) to the aggregator and choose **which of its
+tools to expose downstream** to the CLI. All of this is configured in one persisted file:
+`mcp/expose.json`.
+
+The architecture (see the architecture overview, §1): many upstream MCPs each expose many tools; the
+aggregator connects to them and the **MCP Manager picks which tools to surface** to the CLI as
+*curated-direct* tools - alongside the four lean meta-tools (`toolfunnel_list_tools`,
+`toolfunnel_tool_instructions`, `toolfunnel_run_tool`, `toolfunnel_howto`). The CLI sees a small surface; everything
+else stays reachable through the register.
+
+> Phase note: the live aggregator (`src/mcp/aggregator.js`) is Phase 2. This doc defines the
+> `expose.json` shape so the config is authorable now and the aggregator reads exactly these fields
+> when it lands.
+
+---
+
+## 1. `expose.json` - the two blocks
+
+`expose.json` persists (a) the upstream MCP connections and (b) the curated-direct selection drawn
+from them:
+
+```json
+{
+  "version": 1,
+  "upstreams": [
+    {
+      "id": "chat",
+      "transport": "stdio",
+      "command": "node",
+      "args": ["vendor/chat-mcp/server.js"],
+      "env": { "CHAT_DB": "..." },
+      "enabled": true,
+      "description": "Chat bridge MCP - chats, messages, send."
+    },
+    {
+      "id": "browser",
+      "transport": "stdio",
+      "command": "npx",
+      "args": ["@example/browser-mcp"],
+      "enabled": false,
+      "description": "Browser automation MCP."
+    }
+  ],
+  "expose": [
+    {
+      "upstream": "chat",
+      "tool": "list_chats",
+      "as": "chat_list_chats",
+      "category": "chat",
+      "enabled": true
+    },
+    {
+      "upstream": "chat",
+      "tool": "send_message",
+      "as": "chat_send_message",
+      "category": "chat",
+      "enabled": true
+    }
+  ]
+}
+```
+
+### `upstreams[]` - one entry per upstream MCP
+
+| Field | Type | Meaning |
+|---|---|---|
+| `id` | string | Stable key for this upstream. Referenced by `expose[].upstream`. Unique. |
+| `transport` | string | How the aggregator connects. `"stdio"` (spawn `command`+`args`) is the baseline. |
+| `command` / `args` / `env` | string / string[] / object | The process the aggregator spawns for a `stdio` upstream. Path-shaped **args** must stay **inside the config home** - the isolation guard refuses to connect an upstream whose args escape it. (The `command` itself, an executable, is not guarded; the currently-WRAPPED upstream is exempt in transparent-wrapper mode, with a warning.) |
+| `enabled` | boolean | Whether the aggregator connects to this upstream at startup. |
+| `description` | string | Human-facing note for the MCP Manager UI. |
+
+### `expose[]` - which upstream tools become curated-direct
+
+| Field | Type | Meaning |
+|---|---|---|
+| `upstream` | string | Must match an `upstreams[].id`. |
+| `tool` | string | The upstream tool's own name (as the upstream's `tools/list` reports it). |
+| `as` | string | The downstream name the CLI sees (namespaced so two upstreams can't collide, e.g. `chat_send_message`). Optional - defaults to `<upstream>_<tool>`. |
+| `category` | string | Grouping label, same convention as register entries. |
+| `enabled` | boolean | Whether this tool is actually exposed downstream right now. |
+
+Only the tools listed in `expose[]` with `enabled: true` are surfaced to the CLI as curated-direct
+tools. Everything else on the upstream stays connected but hidden - reachable, if needed, by adding
+an `expose` entry (no upstream reconnect required to *list*, though see §3 on the CLI surface).
+
+---
+
+## 2. Steps to register an upstream and expose a tool
+
+1. Add an entry to `upstreams[]` with a unique `id`, the `stdio` `command`/`args`, and
+   `enabled: true`. Keep the server's path-shaped args **inside the config home** (vendor the
+   server in if it isn't already) - the isolation guard refuses args that escape it.
+2. Let the aggregator connect and run the upstream's `tools/list` (the MCP Manager UI surfaces the
+   discovered tools).
+3. For each tool you want hot, add an `expose[]` entry: `{ upstream, tool, as, category, enabled:true }`.
+4. Leave the long tail unexposed - the model can still reach those via the register/meta-tools if you
+   later mirror them, but the *curated-direct* surface stays lean by design (the dial in §1 of the
+   architecture: directly-exposed = the HOT tools; the register meta-tools = the long tail).
+
+---
+
+## 3. Curated-direct vs. the register (update cost)
+
+This matters because the two layers refresh differently (see the architecture overview, §1):
+
+- **Curated-direct tools** (what `expose[]` produces) are negotiated with the CLI **at connect time**.
+  Changing the exposed set therefore needs a **reconnect**, or a `notifications/tools/list_changed`
+  message *if the CLI honours it* (VERIFY per host; restart is the safe baseline).
+- **Register tools** (the `toolfunnel_list_tools`/`run` path) are **always live** - the model re-reads the
+  register on every `toolfunnel_list_tools` call, so no reconnect is needed.
+
+Rule of thumb: expose a handful of HOT, high-reliability tools curated-direct; everything else lives
+in the register and is reached through the meta-tools.
+
+> Safety: a curated-direct upstream tool is still ultimately invoked by the model. When you wire
+> upstream execution through the host, route it through the same PreToolUse gate the register's `run`
+> uses (see `toolfunnel_howto({ topic: "add-hook" })`) so the safety invariant holds uniformly. The gate
+> firing on every execution path is a tested invariant, not an assumption.

package/src/extend/configure.md

@@ -0,0 +1,87 @@
+# How to configure ToolFunnel - config files only, no code
+
+This is the instruction served by `toolfunnel_howto({ topic: "configure" })`. It is the complete
+no-code setup map: every behaviour of the gateway is driven by a small set of JSON files at the
+**config home**. Editing these files (or driving the UI / the `tf_*` management tools, which write
+the same files) is the entire configuration story - there is nothing to program.
+
+## 1. The config home
+
+All files live under one directory, resolved in this order:
+
+1. `--config-dir <dir>` on the command line
+2. the `TOOLFUNNEL_HOME` environment variable
+3. the package/repo root (the default for a git clone)
+
+On first start with a fresh `--config-dir`, the home is seeded with the standard layout. Every
+file below is read FRESH per request - edits are live without a restart, except `toolfunnel.json`
+(read at boot; restart to apply).
+
+## 2. The files
+
+| File | What it controls | Live? |
+|---|---|---|
+| `toolfunnel.json` | Identity + default ports (see §3) | restart |
+| `mcp/expose.json` | Attached upstream MCPs + which of their tools are curated-direct | live |
+| `tools/tools.register.json` | The local tool register (the gateway's own tools) | live |
+| `tools/tools.state.json` | Per-tool overlays: enabled / hot / hidden, and the active wrap (`"passthrough"`). Wrapped example: `{ "passthrough": "acme-notes" }`; cleared: `{}` (the file-edit equivalent of `wrap --off`) | live |
+| `hooks/hooks.manifest.json` | PreToolUse / PostToolUse policy hooks (the gate) | live |
+| `hooks/hooks.state.json` | Per-hook enabled overlay | live |
+| `logs/log.config.json` | Activity log on/off + path | live |
+| `auth/auth.config.json` | OAuth 2.1 resource-server validation (opt-in; needs `toolfunnel install-oauth` once) | live |
+
+Shapes: `expose.json` → `toolfunnel_howto({ topic: "add-mcp" })`; register entries →
+`toolfunnel_howto({ topic: "create-tool" })`; hook entries → `toolfunnel_howto({ topic: "add-hook" })`;
+the wrap field → `toolfunnel_howto({ topic: "wrap" })`.
+
+## 3. `toolfunnel.json` - identity & ports
+
+Every field optional; an absent or empty file IS the default identity. Blank/omitted fields fall
+back per-field (a broken file never stops the gateway starting).
+
+```json
+{
+  "serverName":    "my-mcp",     // what CLIENTS see in the initialize handshake   (default "toolfunnel")
+  "serverVersion": "1.0.0",      // ...its version                                   (default: package version)
+  "clientName":    "my-client",  // what UPSTREAM servers see from the gateway     (default "toolfunnel")
+  "clientVersion": "1.0.0",      // ...its version
+  "httpPort":      9998,         // --http default port                            (default 9998)
+  "uiPort":        9777          // --ui   default port                            (default 9777)
+}
+```
+
+Precedence: CLI flag > this file > built-in default. Under a WRAP on stdio, the wrapped upstream
+is shown the real downstream client's identity automatically - `clientName`/`clientVersion` cover
+funnel mode, HTTP, and the boot connection. The UI's **Settings** tab edits this file.
+
+## 4. Worked example - a complete gateway from five files
+
+A gateway that attaches one upstream, exposes two of its tools, gates everything, logs activity,
+and introduces itself as `acme-tools`:
+
+1. `toolfunnel.json` → `{ "serverName": "acme-tools", "clientName": "acme-tools" }`
+2. `mcp/expose.json` → one `upstreams[]` entry (id, `"transport": "stdio"`, command, args,
+   `"enabled": true`) + two `expose[]` entries (`{ "upstream", "tool", "enabled": true }`)
+3. `hooks/hooks.manifest.json` → one PreToolUse entry matching the tools you want policy on
+4. `logs/log.config.json` → `{ "enabled": true }`
+5. Start it: `node bin/toolfunnel.js` (stdio) or `--http` / `--ui` as needed.
+
+Optional per-upstream flags in `expose.json`: `"legacyPin": true` pins that upstream to the
+legacy MCP protocol permanently (opt-in, warns loudly); `"env"` passes environment variables to
+the spawned server; `"cwd"` sets its working directory; `"timeoutMs"` raises the payload
+timeout for that upstream (default 120000 ms - applies to `tools/call`, `prompts/get` and
+`resources/read`; under a wrap, a tool that reports progress keeps its call alive regardless.
+The 10 s handshake/list window is fixed: it detects dead servers); `"modernOnly": true`
+requires that upstream to speak the modern (2026-07-28) protocol - the connect fails with a
+clear error instead of falling back to legacy (the mirror of `legacyPin`; setting both on one
+upstream is refused). Server side, `"serveLegacy": false` in `toolfunnel.json` makes the
+gateway itself modern-only: legacy clients are refused with a clear error (default: serve
+both eras - only an explicit `false` flips it).
+
+## 5. Where the AI-driven and human paths meet
+
+The UI (all five tabs + Settings), the `tf_*` management tools, and hand-editing these files are
+three views of the SAME state - every write goes through the same validated, atomic store code.
+Pick whichever fits: config files for repeatable/scripted setups, the UI for humans, the
+management tools for in-band agent-driven changes (each documented via
+`toolfunnel_tool_instructions`).