diff --git a/docs/adhoc.md b/docs/adhoc.md
index 6f2ba17..868ebb9 100644
--- a/docs/adhoc.md
+++ b/docs/adhoc.md
@@ -1,3 +1,9 @@
+---
+summary: 'How to use mcporter’s ad-hoc HTTP/stdio flags to try MCP servers without editing config files.'
+read_when:
+  - 'Exploring or debugging unknown MCP endpoints'
+---
+
 # Ad-hoc MCP Servers
 
 mcporter is gaining support for "just try it" workflows where you point the CLI at a raw MCP endpoint without first editing a config file. This doc tracks the behavior and heuristics we use to make that experience smooth while keeping the runtime predictable.
diff --git a/docs/call-heuristic.md b/docs/call-heuristic.md
index 4ee881b..759a42d 100644
--- a/docs/call-heuristic.md
+++ b/docs/call-heuristic.md
@@ -1,3 +1,9 @@
+---
+summary: 'Explains mcporter call’s typo heuristics, auto-correction thresholds, and suggestion behavior.'
+read_when:
+  - 'Tool invocations fail due to misspelled names'
+---
+
 # Call Command Auto-Correction
 
 `mcporter call` aims to help when a tool name is *almost* correct without hiding real mistakes.
diff --git a/docs/call-syntax.md b/docs/call-syntax.md
index 4d54cf3..1262cb7 100644
--- a/docs/call-syntax.md
+++ b/docs/call-syntax.md
@@ -1,3 +1,9 @@
+---
+summary: 'Reference for mcporter call argument styles, CLI signatures, and structured output modes.'
+read_when:
+  - 'Working on call CLI UX or documenting invocation examples'
+---
+
 # Call Syntax Reference
 
 `mcporter call` now understands two complementary styles:
diff --git a/docs/cli-generator.md b/docs/cli-generator.md
index 4b07974..9dcbbb8 100644
--- a/docs/cli-generator.md
+++ b/docs/cli-generator.md
@@ -1,3 +1,9 @@
+---
+summary: 'Goals and requirements for mcporter generate-cli, including outputs, runtimes, and schema-aware UX.'
+read_when:
+  - 'Changing generate-cli behavior or bundler integrations'
+---
+
 # CLI Generator Plan
 
 Default behavior: generating `<server>.ts` in the working directory if no output path is provided. Bundling is opt-in via `--bundle` and produces a single JS file with shebang; otherwise we emit TypeScript targeting Node.js. Rolldown handles bundling by default unless the runtime resolves to Bun—in that case Bun’s native bundler is selected automatically (still requires `--runtime bun` or Bun auto-detection); `--bundler` lets you override either choice.
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index fe54965..fb2c57a 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -1,3 +1,9 @@
+---
+summary: 'Quick reference for mcporter subcommands, their arguments, and shared global flags.'
+read_when:
+  - 'Need a refresher on available CLI commands'
+---
+
 # mcporter CLI Reference
 
 A quick reference for the primary `mcporter` subcommands. Each command inherits
diff --git a/docs/emit-ts.md b/docs/emit-ts.md
index 57b0c3e..d1ee1d8 100644
--- a/docs/emit-ts.md
+++ b/docs/emit-ts.md
@@ -1,3 +1,9 @@
+---
+summary: 'How to generate `.d.ts` files or typed client helpers with mcporter emit-ts.'
+read_when:
+  - 'Adding new emit-ts behavior or troubleshooting generated clients'
+---
+
 # `mcporter emit-ts`
 
 `mcporter emit-ts` turns a configured MCP server into TypeScript artifacts so
diff --git a/docs/hang-debug.md b/docs/hang-debug.md
index f9f7bf6..76a2c46 100644
--- a/docs/hang-debug.md
+++ b/docs/hang-debug.md
@@ -1,3 +1,9 @@
+---
+summary: 'Checklist for diagnosing mcporter commands that never exit, using tmux and active-handle dumps.'
+read_when:
+  - 'Seeing the CLI hang after tool completion'
+---
+
 # Debugging Hanging mcporter Calls
 
 When `mcporter call` prints a tool response but the process never exits, it
diff --git a/docs/known-issues.md b/docs/known-issues.md
index bbd68fe..20091f5 100644
--- a/docs/known-issues.md
+++ b/docs/known-issues.md
@@ -1,3 +1,9 @@
+---
+summary: 'Living list of mcporter limitations, hosted MCP quirks, and upstream gaps.'
+read_when:
+  - 'Triaging a bug that might already be documented'
+---
+
 # Known Issues
 
 This file tracks limitations that users regularly run into. Most of these require upstream cooperation or larger refactors—feel free to reference this when triaging bugs.
diff --git a/docs/local.md b/docs/local.md
index 11c001d..9ac566c 100644
--- a/docs/local.md
+++ b/docs/local.md
@@ -1,3 +1,9 @@
+---
+summary: 'How to run mcporter directly from the repo (tsx, tsx --watch, built artifacts) without npx.'
+read_when:
+  - 'Setting up a local development loop for this repo'
+---
+
 # Running mcporter Locally
 
 You don’t need `npx` every time—here are the three local entry points we use while developing mcporter itself.
diff --git a/docs/manual-testing.md b/docs/manual-testing.md
index 85c1824..d716bc7 100644
--- a/docs/manual-testing.md
+++ b/docs/manual-testing.md
@@ -1,3 +1,9 @@
+---
+summary: 'Tmux-based manual testing recipe for exercising mcporter against real MCP servers.'
+read_when:
+  - 'Need to reproduce a bug or verify CLI output by hand'
+---
+
 # Manual Testing Harness
 
 When we need to sanity-check CLI flows against real MCP servers (or reproduce bugs by hand), use this repeatable harness. Everything runs under `tmux` so long-running commands can be inspected without blocking the current shell.
diff --git a/docs/mcp.md b/docs/mcp.md
index 4ecd85f..b3b0bab 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -1,8 +1,44 @@
-$(python - <<'PY'
-from pathlib import Path
-text = Path("docs/mcp.md").read_text()
-old = "- `pnpm mcporter:call` — execute a tool using either loose `key=value` pairs or `--args` JSON; append `--tail-log` to follow log files reported by the response.\n- Prefer `createServerProxy(runtime, \"serverName\")` in Node scripts when you want to call tools via `camelCase` methods instead of remembering the exact kebab-case names.\n"
-new = "- `pnpm mcporter:call` — execute a tool using either loose `key=value` pairs or `--args` JSON; append `--tail-log` to follow log files reported by the response.\n- Prefer `createServerProxy(runtime, \"serverName\")` in Node scripts when you want to call tools via `camelCase` methods instead of remembering the exact kebab-case names. The proxy automatically merges schema defaults and returns a `CallResult` helper so you can call `.text()`, `.markdown()`, or `.json()` without hand-parsing content envelopes.\n"
-Path("docs/mcp.md.new").write_text(text.replace(old, new))
-PY
-)
+---
+summary: 'High-level overview of mcporter’s runtime, entry points, and reusable helpers.'
+read_when:
+  - 'Onboarding to this repository or explaining mcporter to others'
+---
+
+# mcporter Overview
+
+mcporter is the Sweetistics CLI + runtime for the Model Context Protocol (MCP). It wraps the upstream TypeScript SDK with:
+
+- **Runtime orchestration** – `createRuntime` loads servers from config JSON, editor imports, or ad-hoc flags and handles OAuth retries, transport promotion, and cleanup.
+- **CLI surfaces** – `mcporter list`, `mcporter call`, `mcporter generate-cli`, `mcporter emit-ts`, and `mcporter inspect-cli` expose the runtime features to humans and scripts.
+- **Tooling helpers** – `createServerProxy` maps MCP tools to camelCase methods for Node/Bun scripts and returns `CallResult` helpers (`.text()`, `.markdown()`, `.json()`).
+
+## Primary Commands
+
+- `npx mcporter list [server|--http-url|--stdio]`  
+  Lists tool metadata, renders TypeScript-style signatures, and surfaces copy/pasteable examples (including ad-hoc HTTP selectors).
+- `npx mcporter call server.tool key=value …`  
+  Invokes a tool via either flag syntax or the function-call expression form; add `--output json` to capture structured responses.
+- `npx mcporter generate-cli --server name [--bundle|--compile]`  
+  Emits a standalone CLI for a single MCP server. Bundling defaults to Rolldown unless the runtime resolves to Bun; compiled binaries require Bun.
+- `npx mcporter emit-ts <server> --mode types|client`  
+  Produces `.d.ts` files or typed client factories that mirror the CLI schema output.
+- `npx mcporter inspect-cli dist/server.js`  
+  Reads embedded metadata so you can regenerate a CLI without guesswork.
+
+## Runtime Helpers
+
+Use `createServerProxy(runtime, name)` inside scripts when you want ergonomic camelCase calls instead of kebab-case tool names. The proxy:
+
+1. Validates arguments against the MCP schema.
+2. Automatically merges default values.
+3. Returns a `CallResult` helper so you can render `.text()`, `.markdown()`, or `.json()` without manual parsing.
+
+When you need raw access (custom transports, streaming), use the bare `Client` from `@modelcontextprotocol/sdk` or inspect `runtime.connect(name)` for lower-level control.
+
+## Debug + Support Docs
+
+- **Ad-hoc MCP Servers** (`docs/adhoc.md`) – explains the `--http-url` / `--stdio` flags.
+- **Tool Calling Cheatsheet** (`docs/tool-calling.md`) – shows the two argument styles and when to use each.
+- **Hang Diagnostics** (`docs/hang-debug.md` + `docs/tmux.md`) – run long-lived commands inside tmux and dump active handles if shutdown stalls.
+
+Read these docs (via `pnpm run docs:list`) whenever your task touches the corresponding area. They contain the up-to-date guardrails used across Sweetistics repositories.
diff --git a/docs/pnpm-mcp-migration.md b/docs/pnpm-mcp-migration.md
index cc94fe6..d4193e1 100644
--- a/docs/pnpm-mcp-migration.md
+++ b/docs/pnpm-mcp-migration.md
@@ -1,3 +1,9 @@
+---
+summary: 'Mapping from the legacy `pnpm mcp:*` scripts to the modern mcporter CLI.'
+read_when:
+  - 'Helping teammates migrate old pnpm workflows to mcporter'
+---
+
 # Migrating from `pnpm mcp:*`
 
 The legacy `pnpm mcp:*` helpers map directly onto the `mcporter` CLI.
diff --git a/docs/refactor.md b/docs/refactor.md
index 0aa6b59..9b9ac81 100644
--- a/docs/refactor.md
+++ b/docs/refactor.md
@@ -1,3 +1,9 @@
+---
+summary: 'Status tracker for post-launch refactors, shared utilities, and remaining cleanup tasks.'
+read_when:
+  - 'Scoping engineering work beyond immediate feature changes'
+---
+
 # Next-Step Refactor Checklist
 
 This doc tracks remaining reuse/refactor work now that the original plan is done.
diff --git a/docs/supabase-auth-issue.md b/docs/supabase-auth-issue.md
index 1d8c5f3..d67fd1b 100644
--- a/docs/supabase-auth-issue.md
+++ b/docs/supabase-auth-issue.md
@@ -1,3 +1,9 @@
+---
+summary: 'Notes on OAuth scope expectations for hosted MCP servers (e.g., Supabase) and why mcporter requests currently fail.'
+read_when:
+  - 'Investigating OAuth errors or scope negotiation problems'
+---
+
 # OAuth Notes & Hosted MCP Compatibility
 
 ## MCP Spec Expectations
diff --git a/docs/tmux.md b/docs/tmux.md
index a69157b..3b984f5 100644
--- a/docs/tmux.md
+++ b/docs/tmux.md
@@ -1,3 +1,9 @@
+---
+summary: 'How to wrap mcporter commands in tmux sessions to monitor hangs and capture output.'
+read_when:
+  - 'Debugging long-running commands or needing persistent logs'
+---
+
 # tmux Hang Diagnostics
 
 Use `tmux` to verify whether a CLI command actually exits or is stalled on open handles. This keeps the main shell free while you inspect logs.
diff --git a/docs/tool-calling.md b/docs/tool-calling.md
index 0fe0948..5f03c11 100644
--- a/docs/tool-calling.md
+++ b/docs/tool-calling.md
@@ -1,3 +1,9 @@
+---
+summary: 'Cheatsheet for the various mcporter call argument syntaxes and best practices.'
+read_when:
+  - 'Designing or debugging tool invocation UX'
+---
+
 # Tool Calling Cheatsheet
 
 mcporter accepts multiple argument styles so you can match whatever feels most natural in your shell or script. Every style feeds the same validation pipeline (schema-driven type coercion, required-field checks, enum hints), so pick the one that's easiest to type.
diff --git a/package.json b/package.json
index 3f65e5a..edbe0e7 100644
--- a/package.json
+++ b/package.json
@@ -39,8 +39,9 @@
     "@modelcontextprotocol/sdk": "^1.10.1",
     "acorn": "^8.15.0",
     "commander": "^12.1.0",
-    "rolldown": "^1.0.0-beta.47",
+    "es-toolkit": "^1.41.0",
     "ora": "^8.0.1",
+    "rolldown": "^1.0.0-beta.47",
     "zod": "^3.25.76"
   },
   "devDependencies": {
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 6bac41e..4993993 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -20,6 +20,9 @@ importers:
       commander:
         specifier: ^12.1.0
         version: 12.1.0
+      es-toolkit:
+        specifier: ^1.41.0
+        version: 1.41.0
       ora:
         specifier: ^8.0.1
         version: 8.2.0
@@ -863,6 +866,9 @@ packages:
     resolution: {integrity: sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA==}
     engines: {node: '>= 0.4'}
 
+  es-toolkit@1.41.0:
+    resolution: {integrity: sha512-bDd3oRmbVgqZCJS6WmeQieOrzpl3URcWBUVDXxOELlUW2FuW+0glPOz1n0KnRie+PdyvUZcXz2sOn00c6pPRIA==}
+
   esbuild@0.25.12:
     resolution: {integrity: sha512-bbPBYYrtZbkt6Os6FiTLCTFxvq4tt3JKall1vRwshA3fdVztsLAatFaZobhkBC8/BrPetoa0oksYoKXoG4ryJg==}
     engines: {node: '>=18'}
@@ -2027,6 +2033,8 @@ snapshots:
     dependencies:
       es-errors: 1.3.0
 
+  es-toolkit@1.41.0: {}
+
   esbuild@0.25.12:
     optionalDependencies:
       '@esbuild/aix-ppc64': 0.25.12
diff --git a/scripts/docs-list.ts b/scripts/docs-list.ts
old mode 100644
new mode 100755
diff --git a/scripts/git-policy.ts b/scripts/git-policy.ts
old mode 100644
new mode 100755
diff --git a/scripts/runner.ts b/scripts/runner.ts
old mode 100644
new mode 100755