From 737bc067273a6550ee2931e3028df03f386e467e Mon Sep 17 00:00:00 2001
From: Lorem Dev <contact@lorem.dev>
Date: Sat, 23 May 2026 10:00:27 +0200
Subject: [PATCH 1/6] test(initflow): require MCP fallback block in every agent
 template

---
 internal/initflow/agents_test.go | 40 ++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/internal/initflow/agents_test.go b/internal/initflow/agents_test.go
index a3d6d81..bf67791 100644
--- a/internal/initflow/agents_test.go
+++ b/internal/initflow/agents_test.go
@@ -492,3 +492,43 @@ func TestTemplates_NoCrossAgentMentions(t *testing.T) {
 		}
 	}
 }
+
+func TestTemplates_AllHaveMCPFallback(t *testing.T) {
+	cases := []struct {
+		name   string
+		loader func(string) ([]byte, error)
+		files  []string
+	}{
+		{
+			"claude", claudefiles.ReadTemplateForTest,
+			[]string{"templates/claude_md.md.tmpl", "templates/claude_skill.md.tmpl"},
+		},
+		{"codex", codexfiles.ReadTemplateForTest, []string{"templates/codex_agents.md.tmpl"}},
+		{"gemini", geminifiles.ReadTemplateForTest, []string{"templates/gemini_md.md.tmpl"}},
+		{"opencode", opencodefiles.ReadTemplateForTest, []string{"templates/instructions.md.tmpl"}},
+		{"generic", genericfiles.ReadTemplateForTest, []string{"templates/instructions.md.tmpl"}},
+	}
+	needles := []string{
+		"Locksmith Commands (runtime whitelist)",
+		"MCP Servers and Locksmith",
+		"Fallback for locksmith-wrapped MCP servers",
+		"{key:",
+		"{vault:",
+		"locksmith get --key",
+		"locksmith get --vault",
+		"locksmith session ensure --quiet",
+	}
+	for _, c := range cases {
+		for _, f := range c.files {
+			data, err := c.loader(f)
+			if err != nil {
+				t.Fatalf("%s %s: %v", c.name, f, err)
+			}
+			for _, n := range needles {
+				if !bytes.Contains(data, []byte(n)) {
+					t.Errorf("%s/%s missing %q", c.name, f, n)
+				}
+			}
+		}
+	}
+}

From a4437c39a35687473b8013f8b059891a4c7461a5 Mon Sep 17 00:00:00 2001
From: Lorem Dev <contact@lorem.dev>
Date: Sat, 23 May 2026 10:03:54 +0200
Subject: [PATCH 2/6] feat(initflow): document MCP wrapper fallback in agent
 templates

---
 CHANGES.md                                    |  1 +
 .../agents/claude/templates/claude_md.md.tmpl | 97 +++++++++++++++++++
 .../claude/templates/claude_skill.md.tmpl     | 96 ++++++++++++++++++
 .../codex/templates/codex_agents.md.tmpl      | 97 +++++++++++++++++++
 .../agents/gemini/templates/gemini_md.md.tmpl | 97 +++++++++++++++++++
 .../generic/templates/instructions.md.tmpl    | 97 +++++++++++++++++++
 .../opencode/templates/instructions.md.tmpl   | 97 +++++++++++++++++++
 7 files changed, 582 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index 5ec6418..d3cdba2 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -63,6 +63,7 @@
   use `export LOCKSMITH_SESSION=$(locksmith session ensure --quiet)`)
   and includes usage examples for all three shipped vault types
   (`gopass`, `keychain`, `1password`).
+- Agent templates now document an MCP-wrapper fallback: when a locksmith-wrapped MCP server fails, the agent parses `--header` and `--env` templates from its own MCP config, resolves them via `locksmith get`, and runs the server directly. Templates also whitelist `session ensure`, `serve`, and `get` as the only runtime locksmith commands.
 
 ## Version v0.3.0 - 2026-05-15
 
diff --git a/internal/initflow/agents/claude/templates/claude_md.md.tmpl b/internal/initflow/agents/claude/templates/claude_md.md.tmpl
index 00dbb70..5be22fd 100644
--- a/internal/initflow/agents/claude/templates/claude_md.md.tmpl
+++ b/internal/initflow/agents/claude/templates/claude_md.md.tmpl
@@ -16,6 +16,103 @@ Just call `locksmith get` directly.
     locksmith get --vault keychain --path "My API Token"
     locksmith get --vault op --path "op://Personal/GitHub/token"
 
+## Locksmith Commands (runtime whitelist)
+
+Use ONLY these at runtime:
+
+- `locksmith session ensure --quiet` - obtain/refresh a session ID
+- `locksmith serve` - start the daemon if it is not running
+  (rare; `session ensure` will spawn it automatically)
+- `locksmith get --key <alias>` or `--vault <name> --path <path>` -
+  fetch a secret
+
+Do not call `init`, `vault`, `plugins`, `config`, `reload`, `mcp`,
+or any other subcommand - they are for the human operator only.
+
+## MCP Servers and Locksmith
+
+The MCP server config lives in **the agent's own settings**
+(e.g. `~/.claude.json`, `~/.codex/mcp.json`, `~/.gemini/...`),
+NOT in locksmith's config file. Always read from there.
+
+- If an MCP entry's `command` is anything other than `"locksmith"` -
+  run it exactly as written. Do not wrap it in locksmith. Behave
+  as if locksmith does not exist for this server.
+- If `command` is `"locksmith"` with `args` starting with
+  `["mcp", "run", ...]` - the server is locksmith-wrapped. If it
+  fails to start or returns an auth error, apply the fallback below.
+
+### Fallback for locksmith-wrapped MCP servers
+
+1. Parse these flags from the entry's `args` (after `mcp run`):
+   - `--header Name=<template>` - HTTP header (proxy mode)
+   - `--env VAR=<template>` - environment variable (local mode)
+   - `--url <url>` - remote endpoint (proxy mode)
+   - tokens after `--` - the underlying command + args (local mode)
+
+   Templates look like `{key:<alias>}` or `{vault:<name> path:<value>}`.
+
+2. Resolve each template manually:
+   - `{key:alias}` -> `locksmith get --key alias`
+   - `{vault:name path:p}` -> `locksmith get --vault name --path p`
+
+3. Run the MCP server **directly** with the resolved values:
+   - local mode: export the resolved env vars, exec the command
+     from after `--`;
+   - proxy mode: there is no process to spawn - send HTTP requests
+     to `--url` yourself with the resolved headers.
+
+4. If access is still denied, prompt the user (replace `<MCP_NAME>`
+   with the entry name; substitute the placeholder values below
+   with header/arg names you actually saw in the entry):
+
+   > Enter credentials for MCP `<MCP_NAME>` in this format:
+   >
+   >     headers: {"X-Authorization": "Bearer ...", "X-Request-ID": "..."}
+   >     args: --arg1 value1 --arg2 "value2" --flag3
+   >
+   > Parse the user's `headers` and `args` and retry the MCP
+   > server with them.
+
+If `locksmith get` itself fails (missing key, daemon down), surface
+that error to the user verbatim. Do NOT fall through to the
+credential prompt; the prompt is for auth-denial only.
+
+### Examples
+
+Proxy-mode entry (header from key alias + header from direct
+vault+path):
+
+    "github": {
+      "command": "locksmith",
+      "args": ["mcp", "run", "--url", "https://api.githubcopilot.com/mcp",
+               "--header", "Authorization=Bearer {key:gh-token}",
+               "--header", "X-Org-ID={vault:keychain path:gh/org}"]
+    }
+
+Fallback:
+
+    TOKEN=$(locksmith get --key gh-token)
+    ORG=$(locksmith get --vault keychain --path gh/org)
+    # then call https://api.githubcopilot.com/mcp with:
+    #   Authorization: Bearer $TOKEN
+    #   X-Org-ID: $ORG
+
+Local-mode entry (env via vault+path, real binary after `--`):
+
+    "linear": {
+      "command": "locksmith",
+      "args": ["mcp", "run",
+               "--env", "LINEAR_API_KEY={vault:keychain path:linear/api-key}",
+               "--", "linear-mcp", "--workspace", "acme"]
+    }
+
+Fallback:
+
+    LINEAR_API_KEY=$(locksmith get --vault keychain --path linear/api-key)
+    export LINEAR_API_KEY
+    exec linear-mcp --workspace acme
+
 - Sessions expire automatically by TTL; no manual cleanup needed.
 - Pass `LOCKSMITH_SESSION` to sub-agents to share the parent session.
 <!-- LOCKSMITH_END -->
diff --git a/internal/initflow/agents/claude/templates/claude_skill.md.tmpl b/internal/initflow/agents/claude/templates/claude_skill.md.tmpl
index 780158a..e143d8b 100644
--- a/internal/initflow/agents/claude/templates/claude_skill.md.tmpl
+++ b/internal/initflow/agents/claude/templates/claude_skill.md.tmpl
@@ -19,5 +19,101 @@ prompt, so no manual session step is needed.
     locksmith get --vault keychain --path "My API Token"
     locksmith get --vault op --path "op://Personal/GitHub/token"
 
+**Locksmith Commands (runtime whitelist)**
+
+Use ONLY these at runtime:
+
+- `locksmith session ensure --quiet` - obtain/refresh a session ID
+- `locksmith serve` - start the daemon if it is not running
+  (rare; `session ensure` will spawn it automatically)
+- `locksmith get --key <alias>` or `--vault <name> --path <path>` -
+  fetch a secret
+
+Do not call `init`, `vault`, `plugins`, `config`, `reload`, `mcp`,
+or any other subcommand - they are for the human operator only.
+
+**MCP Servers and Locksmith**
+
+The MCP server config lives in the agent's own settings
+(e.g. `~/.claude.json`, `~/.codex/mcp.json`, `~/.gemini/...`),
+NOT in locksmith's config file. Always read from there.
+
+- If an MCP entry's `command` is anything other than `"locksmith"` -
+  run it exactly as written. Do not wrap it in locksmith. Behave
+  as if locksmith does not exist for this server.
+- If `command` is `"locksmith"` with `args` starting with
+  `["mcp", "run", ...]` - the server is locksmith-wrapped. If it
+  fails to start or returns an auth error, apply the fallback below.
+
+**Fallback for locksmith-wrapped MCP servers**
+
+1. Parse these flags from the entry's `args` (after `mcp run`):
+   - `--header Name=<template>` - HTTP header (proxy mode)
+   - `--env VAR=<template>` - environment variable (local mode)
+   - `--url <url>` - remote endpoint (proxy mode)
+   - tokens after `--` - the underlying command + args (local mode)
+
+   Templates look like `{key:<alias>}` or `{vault:<name> path:<value>}`.
+
+2. Resolve each template manually:
+   - `{key:alias}` -> `locksmith get --key alias`
+   - `{vault:name path:p}` -> `locksmith get --vault name --path p`
+
+3. Run the MCP server directly with the resolved values:
+   - local mode: export the resolved env vars, exec the command
+     from after `--`;
+   - proxy mode: there is no process to spawn - send HTTP requests
+     to `--url` yourself with the resolved headers.
+
+4. If access is still denied, prompt the user (replace `<MCP_NAME>`
+   with the entry name; substitute the placeholder values below
+   with header/arg names you actually saw in the entry):
+
+   > Enter credentials for MCP `<MCP_NAME>` in this format:
+   >
+   >     headers: {"X-Authorization": "Bearer ...", "X-Request-ID": "..."}
+   >     args: --arg1 value1 --arg2 "value2" --flag3
+   >
+   > Parse the user's `headers` and `args` and retry the MCP
+   > server with them.
+
+If `locksmith get` itself fails (missing key, daemon down), surface
+that error to the user verbatim. Do NOT fall through to the
+credential prompt; the prompt is for auth-denial only.
+
+**Examples**
+
+Proxy-mode entry:
+
+    "github": {
+      "command": "locksmith",
+      "args": ["mcp", "run", "--url", "https://api.githubcopilot.com/mcp",
+               "--header", "Authorization=Bearer {key:gh-token}",
+               "--header", "X-Org-ID={vault:keychain path:gh/org}"]
+    }
+
+Fallback:
+
+    TOKEN=$(locksmith get --key gh-token)
+    ORG=$(locksmith get --vault keychain --path gh/org)
+    # then call https://api.githubcopilot.com/mcp with:
+    #   Authorization: Bearer $TOKEN
+    #   X-Org-ID: $ORG
+
+Local-mode entry:
+
+    "linear": {
+      "command": "locksmith",
+      "args": ["mcp", "run",
+               "--env", "LINEAR_API_KEY={vault:keychain path:linear/api-key}",
+               "--", "linear-mcp", "--workspace", "acme"]
+    }
+
+Fallback:
+
+    LINEAR_API_KEY=$(locksmith get --vault keychain --path linear/api-key)
+    export LINEAR_API_KEY
+    exec linear-mcp --workspace acme
+
 Never hardcode secrets. Never cache secrets outside of locksmith.
 <!-- LOCKSMITH_END -->
diff --git a/internal/initflow/agents/codex/templates/codex_agents.md.tmpl b/internal/initflow/agents/codex/templates/codex_agents.md.tmpl
index 1b5722a..f3ffee1 100644
--- a/internal/initflow/agents/codex/templates/codex_agents.md.tmpl
+++ b/internal/initflow/agents/codex/templates/codex_agents.md.tmpl
@@ -24,5 +24,102 @@ configured TTL (default 3h).
     locksmith get --vault keychain --path "My API Token"
     locksmith get --vault op --path "op://Personal/GitHub/token"
 
+## Locksmith Commands (runtime whitelist)
+
+Use ONLY these at runtime:
+
+- `locksmith session ensure --quiet` - obtain/refresh a session ID
+- `locksmith serve` - start the daemon if it is not running
+  (rare; `session ensure` will spawn it automatically)
+- `locksmith get --key <alias>` or `--vault <name> --path <path>` -
+  fetch a secret
+
+Do not call `init`, `vault`, `plugins`, `config`, `reload`, `mcp`,
+or any other subcommand - they are for the human operator only.
+
+## MCP Servers and Locksmith
+
+The MCP server config lives in **the agent's own settings**
+(e.g. `~/.claude.json`, `~/.codex/mcp.json`, `~/.gemini/...`),
+NOT in locksmith's config file. Always read from there.
+
+- If an MCP entry's `command` is anything other than `"locksmith"` -
+  run it exactly as written. Do not wrap it in locksmith. Behave
+  as if locksmith does not exist for this server.
+- If `command` is `"locksmith"` with `args` starting with
+  `["mcp", "run", ...]` - the server is locksmith-wrapped. If it
+  fails to start or returns an auth error, apply the fallback below.
+
+### Fallback for locksmith-wrapped MCP servers
+
+1. Parse these flags from the entry's `args` (after `mcp run`):
+   - `--header Name=<template>` - HTTP header (proxy mode)
+   - `--env VAR=<template>` - environment variable (local mode)
+   - `--url <url>` - remote endpoint (proxy mode)
+   - tokens after `--` - the underlying command + args (local mode)
+
+   Templates look like `{key:<alias>}` or `{vault:<name> path:<value>}`.
+
+2. Resolve each template manually:
+   - `{key:alias}` -> `locksmith get --key alias`
+   - `{vault:name path:p}` -> `locksmith get --vault name --path p`
+
+3. Run the MCP server **directly** with the resolved values:
+   - local mode: export the resolved env vars, exec the command
+     from after `--`;
+   - proxy mode: there is no process to spawn - send HTTP requests
+     to `--url` yourself with the resolved headers.
+
+4. If access is still denied, prompt the user (replace `<MCP_NAME>`
+   with the entry name; substitute the placeholder values below
+   with header/arg names you actually saw in the entry):
+
+   > Enter credentials for MCP `<MCP_NAME>` in this format:
+   >
+   >     headers: {"X-Authorization": "Bearer ...", "X-Request-ID": "..."}
+   >     args: --arg1 value1 --arg2 "value2" --flag3
+   >
+   > Parse the user's `headers` and `args` and retry the MCP
+   > server with them.
+
+If `locksmith get` itself fails (missing key, daemon down), surface
+that error to the user verbatim. Do NOT fall through to the
+credential prompt; the prompt is for auth-denial only.
+
+### Examples
+
+Proxy-mode entry (header from key alias + header from direct
+vault+path):
+
+    "github": {
+      "command": "locksmith",
+      "args": ["mcp", "run", "--url", "https://api.githubcopilot.com/mcp",
+               "--header", "Authorization=Bearer {key:gh-token}",
+               "--header", "X-Org-ID={vault:keychain path:gh/org}"]
+    }
+
+Fallback:
+
+    TOKEN=$(locksmith get --key gh-token)
+    ORG=$(locksmith get --vault keychain --path gh/org)
+    # then call https://api.githubcopilot.com/mcp with:
+    #   Authorization: Bearer $TOKEN
+    #   X-Org-ID: $ORG
+
+Local-mode entry (env via vault+path, real binary after `--`):
+
+    "linear": {
+      "command": "locksmith",
+      "args": ["mcp", "run",
+               "--env", "LINEAR_API_KEY={vault:keychain path:linear/api-key}",
+               "--", "linear-mcp", "--workspace", "acme"]
+    }
+
+Fallback:
+
+    LINEAR_API_KEY=$(locksmith get --vault keychain --path linear/api-key)
+    export LINEAR_API_KEY
+    exec linear-mcp --workspace acme
+
 Pass `LOCKSMITH_SESSION` to sub-agents so they share the parent session.
 <!-- LOCKSMITH_END -->
diff --git a/internal/initflow/agents/gemini/templates/gemini_md.md.tmpl b/internal/initflow/agents/gemini/templates/gemini_md.md.tmpl
index e4f9937..3efeeb4 100644
--- a/internal/initflow/agents/gemini/templates/gemini_md.md.tmpl
+++ b/internal/initflow/agents/gemini/templates/gemini_md.md.tmpl
@@ -25,6 +25,103 @@ configured TTL (default 3h).
     locksmith get --vault keychain --path "My API Token"
     locksmith get --vault op --path "op://Personal/GitHub/token"
 
+## Locksmith Commands (runtime whitelist)
+
+Use ONLY these at runtime:
+
+- `locksmith session ensure --quiet` - obtain/refresh a session ID
+- `locksmith serve` - start the daemon if it is not running
+  (rare; `session ensure` will spawn it automatically)
+- `locksmith get --key <alias>` or `--vault <name> --path <path>` -
+  fetch a secret
+
+Do not call `init`, `vault`, `plugins`, `config`, `reload`, `mcp`,
+or any other subcommand - they are for the human operator only.
+
+## MCP Servers and Locksmith
+
+The MCP server config lives in **the agent's own settings**
+(e.g. `~/.claude.json`, `~/.codex/mcp.json`, `~/.gemini/...`),
+NOT in locksmith's config file. Always read from there.
+
+- If an MCP entry's `command` is anything other than `"locksmith"` -
+  run it exactly as written. Do not wrap it in locksmith. Behave
+  as if locksmith does not exist for this server.
+- If `command` is `"locksmith"` with `args` starting with
+  `["mcp", "run", ...]` - the server is locksmith-wrapped. If it
+  fails to start or returns an auth error, apply the fallback below.
+
+### Fallback for locksmith-wrapped MCP servers
+
+1. Parse these flags from the entry's `args` (after `mcp run`):
+   - `--header Name=<template>` - HTTP header (proxy mode)
+   - `--env VAR=<template>` - environment variable (local mode)
+   - `--url <url>` - remote endpoint (proxy mode)
+   - tokens after `--` - the underlying command + args (local mode)
+
+   Templates look like `{key:<alias>}` or `{vault:<name> path:<value>}`.
+
+2. Resolve each template manually:
+   - `{key:alias}` -> `locksmith get --key alias`
+   - `{vault:name path:p}` -> `locksmith get --vault name --path p`
+
+3. Run the MCP server **directly** with the resolved values:
+   - local mode: export the resolved env vars, exec the command
+     from after `--`;
+   - proxy mode: there is no process to spawn - send HTTP requests
+     to `--url` yourself with the resolved headers.
+
+4. If access is still denied, prompt the user (replace `<MCP_NAME>`
+   with the entry name; substitute the placeholder values below
+   with header/arg names you actually saw in the entry):
+
+   > Enter credentials for MCP `<MCP_NAME>` in this format:
+   >
+   >     headers: {"X-Authorization": "Bearer ...", "X-Request-ID": "..."}
+   >     args: --arg1 value1 --arg2 "value2" --flag3
+   >
+   > Parse the user's `headers` and `args` and retry the MCP
+   > server with them.
+
+If `locksmith get` itself fails (missing key, daemon down), surface
+that error to the user verbatim. Do NOT fall through to the
+credential prompt; the prompt is for auth-denial only.
+
+### Examples
+
+Proxy-mode entry (header from key alias + header from direct
+vault+path):
+
+    "github": {
+      "command": "locksmith",
+      "args": ["mcp", "run", "--url", "https://api.githubcopilot.com/mcp",
+               "--header", "Authorization=Bearer {key:gh-token}",
+               "--header", "X-Org-ID={vault:keychain path:gh/org}"]
+    }
+
+Fallback:
+
+    TOKEN=$(locksmith get --key gh-token)
+    ORG=$(locksmith get --vault keychain --path gh/org)
+    # then call https://api.githubcopilot.com/mcp with:
+    #   Authorization: Bearer $TOKEN
+    #   X-Org-ID: $ORG
+
+Local-mode entry (env via vault+path, real binary after `--`):
+
+    "linear": {
+      "command": "locksmith",
+      "args": ["mcp", "run",
+               "--env", "LINEAR_API_KEY={vault:keychain path:linear/api-key}",
+               "--", "linear-mcp", "--workspace", "acme"]
+    }
+
+Fallback:
+
+    LINEAR_API_KEY=$(locksmith get --vault keychain --path linear/api-key)
+    export LINEAR_API_KEY
+    exec linear-mcp --workspace acme
+
 ## Sub-agent Session Passing
 
 When spawning sub-agents, export `LOCKSMITH_SESSION` into their
diff --git a/internal/initflow/agents/generic/templates/instructions.md.tmpl b/internal/initflow/agents/generic/templates/instructions.md.tmpl
index a6dffef..4cbed3b 100644
--- a/internal/initflow/agents/generic/templates/instructions.md.tmpl
+++ b/internal/initflow/agents/generic/templates/instructions.md.tmpl
@@ -21,6 +21,103 @@ configured TTL (default 3h).
     locksmith get --vault keychain --path "My API Token"
     locksmith get --vault op --path "op://Personal/GitHub/token"
 
+## Locksmith Commands (runtime whitelist)
+
+Use ONLY these at runtime:
+
+- `locksmith session ensure --quiet` - obtain/refresh a session ID
+- `locksmith serve` - start the daemon if it is not running
+  (rare; `session ensure` will spawn it automatically)
+- `locksmith get --key <alias>` or `--vault <name> --path <path>` -
+  fetch a secret
+
+Do not call `init`, `vault`, `plugins`, `config`, `reload`, `mcp`,
+or any other subcommand - they are for the human operator only.
+
+## MCP Servers and Locksmith
+
+The MCP server config lives in **the agent's own settings**
+(e.g. `~/.claude.json`, `~/.codex/mcp.json`, `~/.gemini/...`),
+NOT in locksmith's config file. Always read from there.
+
+- If an MCP entry's `command` is anything other than `"locksmith"` -
+  run it exactly as written. Do not wrap it in locksmith. Behave
+  as if locksmith does not exist for this server.
+- If `command` is `"locksmith"` with `args` starting with
+  `["mcp", "run", ...]` - the server is locksmith-wrapped. If it
+  fails to start or returns an auth error, apply the fallback below.
+
+### Fallback for locksmith-wrapped MCP servers
+
+1. Parse these flags from the entry's `args` (after `mcp run`):
+   - `--header Name=<template>` - HTTP header (proxy mode)
+   - `--env VAR=<template>` - environment variable (local mode)
+   - `--url <url>` - remote endpoint (proxy mode)
+   - tokens after `--` - the underlying command + args (local mode)
+
+   Templates look like `{key:<alias>}` or `{vault:<name> path:<value>}`.
+
+2. Resolve each template manually:
+   - `{key:alias}` -> `locksmith get --key alias`
+   - `{vault:name path:p}` -> `locksmith get --vault name --path p`
+
+3. Run the MCP server **directly** with the resolved values:
+   - local mode: export the resolved env vars, exec the command
+     from after `--`;
+   - proxy mode: there is no process to spawn - send HTTP requests
+     to `--url` yourself with the resolved headers.
+
+4. If access is still denied, prompt the user (replace `<MCP_NAME>`
+   with the entry name; substitute the placeholder values below
+   with header/arg names you actually saw in the entry):
+
+   > Enter credentials for MCP `<MCP_NAME>` in this format:
+   >
+   >     headers: {"X-Authorization": "Bearer ...", "X-Request-ID": "..."}
+   >     args: --arg1 value1 --arg2 "value2" --flag3
+   >
+   > Parse the user's `headers` and `args` and retry the MCP
+   > server with them.
+
+If `locksmith get` itself fails (missing key, daemon down), surface
+that error to the user verbatim. Do NOT fall through to the
+credential prompt; the prompt is for auth-denial only.
+
+### Examples
+
+Proxy-mode entry (header from key alias + header from direct
+vault+path):
+
+    "github": {
+      "command": "locksmith",
+      "args": ["mcp", "run", "--url", "https://api.githubcopilot.com/mcp",
+               "--header", "Authorization=Bearer {key:gh-token}",
+               "--header", "X-Org-ID={vault:keychain path:gh/org}"]
+    }
+
+Fallback:
+
+    TOKEN=$(locksmith get --key gh-token)
+    ORG=$(locksmith get --vault keychain --path gh/org)
+    # then call https://api.githubcopilot.com/mcp with:
+    #   Authorization: Bearer $TOKEN
+    #   X-Org-ID: $ORG
+
+Local-mode entry (env via vault+path, real binary after `--`):
+
+    "linear": {
+      "command": "locksmith",
+      "args": ["mcp", "run",
+               "--env", "LINEAR_API_KEY={vault:keychain path:linear/api-key}",
+               "--", "linear-mcp", "--workspace", "acme"]
+    }
+
+Fallback:
+
+    LINEAR_API_KEY=$(locksmith get --vault keychain --path linear/api-key)
+    export LINEAR_API_KEY
+    exec linear-mcp --workspace acme
+
 ## Sub-Agents
 
 Pass `LOCKSMITH_SESSION` to sub-agents via environment so they share
diff --git a/internal/initflow/agents/opencode/templates/instructions.md.tmpl b/internal/initflow/agents/opencode/templates/instructions.md.tmpl
index a9f4ca7..308c5fd 100644
--- a/internal/initflow/agents/opencode/templates/instructions.md.tmpl
+++ b/internal/initflow/agents/opencode/templates/instructions.md.tmpl
@@ -23,6 +23,103 @@ configured TTL (default 3h).
     locksmith get --vault keychain --path "My API Token"
     locksmith get --vault op --path "op://Personal/GitHub/token"
 
+## Locksmith Commands (runtime whitelist)
+
+Use ONLY these at runtime:
+
+- `locksmith session ensure --quiet` - obtain/refresh a session ID
+- `locksmith serve` - start the daemon if it is not running
+  (rare; `session ensure` will spawn it automatically)
+- `locksmith get --key <alias>` or `--vault <name> --path <path>` -
+  fetch a secret
+
+Do not call `init`, `vault`, `plugins`, `config`, `reload`, `mcp`,
+or any other subcommand - they are for the human operator only.
+
+## MCP Servers and Locksmith
+
+The MCP server config lives in **the agent's own settings**
+(e.g. `~/.claude.json`, `~/.codex/mcp.json`, `~/.gemini/...`),
+NOT in locksmith's config file. Always read from there.
+
+- If an MCP entry's `command` is anything other than `"locksmith"` -
+  run it exactly as written. Do not wrap it in locksmith. Behave
+  as if locksmith does not exist for this server.
+- If `command` is `"locksmith"` with `args` starting with
+  `["mcp", "run", ...]` - the server is locksmith-wrapped. If it
+  fails to start or returns an auth error, apply the fallback below.
+
+### Fallback for locksmith-wrapped MCP servers
+
+1. Parse these flags from the entry's `args` (after `mcp run`):
+   - `--header Name=<template>` - HTTP header (proxy mode)
+   - `--env VAR=<template>` - environment variable (local mode)
+   - `--url <url>` - remote endpoint (proxy mode)
+   - tokens after `--` - the underlying command + args (local mode)
+
+   Templates look like `{key:<alias>}` or `{vault:<name> path:<value>}`.
+
+2. Resolve each template manually:
+   - `{key:alias}` -> `locksmith get --key alias`
+   - `{vault:name path:p}` -> `locksmith get --vault name --path p`
+
+3. Run the MCP server **directly** with the resolved values:
+   - local mode: export the resolved env vars, exec the command
+     from after `--`;
+   - proxy mode: there is no process to spawn - send HTTP requests
+     to `--url` yourself with the resolved headers.
+
+4. If access is still denied, prompt the user (replace `<MCP_NAME>`
+   with the entry name; substitute the placeholder values below
+   with header/arg names you actually saw in the entry):
+
+   > Enter credentials for MCP `<MCP_NAME>` in this format:
+   >
+   >     headers: {"X-Authorization": "Bearer ...", "X-Request-ID": "..."}
+   >     args: --arg1 value1 --arg2 "value2" --flag3
+   >
+   > Parse the user's `headers` and `args` and retry the MCP
+   > server with them.
+
+If `locksmith get` itself fails (missing key, daemon down), surface
+that error to the user verbatim. Do NOT fall through to the
+credential prompt; the prompt is for auth-denial only.
+
+### Examples
+
+Proxy-mode entry (header from key alias + header from direct
+vault+path):
+
+    "github": {
+      "command": "locksmith",
+      "args": ["mcp", "run", "--url", "https://api.githubcopilot.com/mcp",
+               "--header", "Authorization=Bearer {key:gh-token}",
+               "--header", "X-Org-ID={vault:keychain path:gh/org}"]
+    }
+
+Fallback:
+
+    TOKEN=$(locksmith get --key gh-token)
+    ORG=$(locksmith get --vault keychain --path gh/org)
+    # then call https://api.githubcopilot.com/mcp with:
+    #   Authorization: Bearer $TOKEN
+    #   X-Org-ID: $ORG
+
+Local-mode entry (env via vault+path, real binary after `--`):
+
+    "linear": {
+      "command": "locksmith",
+      "args": ["mcp", "run",
+               "--env", "LINEAR_API_KEY={vault:keychain path:linear/api-key}",
+               "--", "linear-mcp", "--workspace", "acme"]
+    }
+
+Fallback:
+
+    LINEAR_API_KEY=$(locksmith get --vault keychain --path linear/api-key)
+    export LINEAR_API_KEY
+    exec linear-mcp --workspace acme
+
 ## Sub-Agents
 
 Pass `LOCKSMITH_SESSION` to sub-agents via environment so they share

From 7b21ce3eb7e0061931c4f125938673c8d8883976 Mon Sep 17 00:00:00 2001
From: Lorem Dev <contact@lorem.dev>
Date: Sat, 23 May 2026 10:13:25 +0200
Subject: [PATCH 3/6] chore(verification): ignore GitHub web-flow merge commits
 in GPG gate

GitHub's "Merge pull request" commits are signed by the web-flow key,
which is often expired (E) or untrusted locally. Re-signing them is
impossible without diverging from the remote, so filter them out of
the unsigned-commits report and document the rule in the skill.
---
 .claude/skills/verification/SKILL.md | 5 ++++-
 .scripts/verification.sh             | 5 ++++-
 CHANGES.md                           | 1 +
 3 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/.claude/skills/verification/SKILL.md b/.claude/skills/verification/SKILL.md
index e52cdd2..82dcf45 100644
--- a/.claude/skills/verification/SKILL.md
+++ b/.claude/skills/verification/SKILL.md
@@ -36,7 +36,7 @@ For every `FAIL` line in the output, apply the fix described below, then re-run
 | `make lint` | Run `make lint` to see current errors. Fix each one - do not add `//nolint:` without a comment explaining why. Re-run until clean. |
 | `test-race` | Find the failing test(s) in the output above the gate line. Fix the root cause. Do NOT suppress the race detector with `runtime.GOMAXPROCS(1)` or similar hacks. |
 | coverage below 90% | Open `.reports/coverage-<module>.html` for the listed package. Add tests for uncovered lines. Aim for lines that test real behaviour, not just coverage points. |
-| GPG signatures | Do NOT re-sign automatically. Report the unsigned commits to the user, show the exact commits, and ask for explicit confirmation before running the re-sign command from CLAUDE.md. |
+| GPG signatures | Do NOT re-sign automatically. Report the unsigned commits to the user, show the exact commits, and ask for explicit confirmation before running the re-sign command from CLAUDE.md. GitHub-generated "Merge pull request" commits are ignored by the gate (their `web-flow` key is often expired/untrusted locally and they can't be re-signed without diverging from the remote). |
 | CHANGES.md missing `## Development` | Add the section at the top of CHANGES.md with one bullet per user-visible change introduced on this branch. |
 | CHANGES.md has no bullet entries | Add bullets under `## Development` - one per logical change: what changed and why, in plain English. |
 | docs not updated | Identify which new or changed behaviour is undocumented. Add a section to `README.md` (user-facing changes) or the relevant file under `docs/` (architecture/config changes). |
@@ -73,3 +73,6 @@ git log --format="%G? %h %s" | head -20
 - Every line starts with `G` - report "All commits signed. Verification complete."
 - Any line starts with `N` or `B` - list those commits and ask the user for confirmation
   before re-signing. Use the re-sign command from CLAUDE.md.
+- Lines whose subject begins with `Merge pull request` may carry `E` (expired
+  GitHub `web-flow` key) - ignore them. Re-signing them would diverge from
+  the remote and serves no purpose.
diff --git a/.scripts/verification.sh b/.scripts/verification.sh
index 07c65d4..8ea4b62 100755
--- a/.scripts/verification.sh
+++ b/.scripts/verification.sh
@@ -96,7 +96,10 @@ else
   COMMITS=$(git log --format="%G? %h %s" | head -20 || true)
 fi
 
-UNSIGNED=$(printf '%s\n' "$COMMITS" | { grep -v "^G " || true; })
+# Ignore GitHub-generated "Merge pull request" commits: they are signed by
+# GitHub's web-flow key, which is often expired/untrusted locally and shows
+# as 'E'. We can't re-sign them anyway (they would diverge from the remote).
+UNSIGNED=$(printf '%s\n' "$COMMITS" | { grep -v "^G " || true; } | { grep -v "Merge pull request" || true; })
 if [ -z "$UNSIGNED" ]; then
   gate_pass "all commits on this branch are GPG-signed"
 else
diff --git a/CHANGES.md b/CHANGES.md
index d3cdba2..485e654 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -64,6 +64,7 @@
   and includes usage examples for all three shipped vault types
   (`gopass`, `keychain`, `1password`).
 - Agent templates now document an MCP-wrapper fallback: when a locksmith-wrapped MCP server fails, the agent parses `--header` and `--env` templates from its own MCP config, resolves them via `locksmith get`, and runs the server directly. Templates also whitelist `session ensure`, `serve`, and `get` as the only runtime locksmith commands.
+- The verification GPG gate now ignores GitHub-generated "Merge pull request" commits: their `web-flow` signature is often expired locally and they cannot be re-signed without diverging from the remote.
 
 ## Version v0.3.0 - 2026-05-15
 

From 9ba05b43386008f0d644fc7883bc4578e261bcbf Mon Sep 17 00:00:00 2001
From: Lorem Dev <contact@lorem.dev>
Date: Sat, 23 May 2026 10:42:12 +0200
Subject: [PATCH 4/6] test(initflow): require external-API auth-failure prompt
 in every agent template

---
 internal/initflow/agents_test.go | 39 ++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/internal/initflow/agents_test.go b/internal/initflow/agents_test.go
index bf67791..cf869b2 100644
--- a/internal/initflow/agents_test.go
+++ b/internal/initflow/agents_test.go
@@ -532,3 +532,42 @@ func TestTemplates_AllHaveMCPFallback(t *testing.T) {
 		}
 	}
 }
+
+func TestTemplates_AllHaveAuthFailurePrompt(t *testing.T) {
+	cases := []struct {
+		name   string
+		loader func(string) ([]byte, error)
+		files  []string
+	}{
+		{
+			"claude", claudefiles.ReadTemplateForTest,
+			[]string{"templates/claude_md.md.tmpl", "templates/claude_skill.md.tmpl"},
+		},
+		{"codex", codexfiles.ReadTemplateForTest, []string{"templates/codex_agents.md.tmpl"}},
+		{"gemini", geminifiles.ReadTemplateForTest, []string{"templates/gemini_md.md.tmpl"}},
+		{"opencode", opencodefiles.ReadTemplateForTest, []string{"templates/instructions.md.tmpl"}},
+		{"generic", genericfiles.ReadTemplateForTest, []string{"templates/instructions.md.tmpl"}},
+	}
+	needles := []string{
+		"External APIs - try Locksmith on auth failure",
+		"first auth/access error",
+		"do not ask again for",
+		"key alias OR a",
+		"vault+path",
+		"paste the token directly",
+		"Cache $TOKEN for further",
+	}
+	for _, c := range cases {
+		for _, f := range c.files {
+			data, err := c.loader(f)
+			if err != nil {
+				t.Fatalf("%s %s: %v", c.name, f, err)
+			}
+			for _, n := range needles {
+				if !bytes.Contains(data, []byte(n)) {
+					t.Errorf("%s/%s missing %q", c.name, f, n)
+				}
+			}
+		}
+	}
+}

From d3435a8479c654400b6f746a2ec91d10bf6ec9d3 Mon Sep 17 00:00:00 2001
From: Lorem Dev <contact@lorem.dev>
Date: Sat, 23 May 2026 10:46:10 +0200
Subject: [PATCH 5/6] feat(initflow): document external-API auth-failure prompt
 in agent templates

---
 CHANGES.md                                    |   1 +
 .../agents/claude/templates/claude_md.md.tmpl | 104 ++++++++++++++++++
 .../claude/templates/claude_skill.md.tmpl     | 104 ++++++++++++++++++
 .../codex/templates/codex_agents.md.tmpl      | 104 ++++++++++++++++++
 .../agents/gemini/templates/gemini_md.md.tmpl | 104 ++++++++++++++++++
 .../generic/templates/instructions.md.tmpl    | 104 ++++++++++++++++++
 .../opencode/templates/instructions.md.tmpl   | 104 ++++++++++++++++++
 7 files changed, 625 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index 485e654..b8dc6de 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -65,6 +65,7 @@
   (`gopass`, `keychain`, `1password`).
 - Agent templates now document an MCP-wrapper fallback: when a locksmith-wrapped MCP server fails, the agent parses `--header` and `--env` templates from its own MCP config, resolves them via `locksmith get`, and runs the server directly. Templates also whitelist `session ensure`, `serve`, and `get` as the only runtime locksmith commands.
 - The verification GPG gate now ignores GitHub-generated "Merge pull request" commits: their `web-flow` signature is often expired locally and they cannot be re-signed without diverging from the remote.
+- Agent templates now document a recovery prompt for external HTTP API auth failures: on the first 401/403 for a hostname, the agent asks the user to (1) Skip, (2) provide a locksmith key or vault+path, or (3) paste the token directly. Resolved tokens are cached per hostname for the rest of the session; Skip suppresses further prompts for that hostname.
 
 ## Version v0.3.0 - 2026-05-15
 
diff --git a/internal/initflow/agents/claude/templates/claude_md.md.tmpl b/internal/initflow/agents/claude/templates/claude_md.md.tmpl
index 5be22fd..d6ac870 100644
--- a/internal/initflow/agents/claude/templates/claude_md.md.tmpl
+++ b/internal/initflow/agents/claude/templates/claude_md.md.tmpl
@@ -113,6 +113,110 @@ Fallback:
     export LINEAR_API_KEY
     exec linear-mcp --workspace acme
 
+## External APIs - try Locksmith on auth failure
+
+When you call an external HTTP API (not via a locksmith-wrapped MCP)
+and you get the first auth/access error for that API's hostname in
+this session, ask the user once whether the token may be in
+locksmith. "Auth/access error" means HTTP `401`, HTTP `403`, or a
+response body containing "invalid token", "unauthorized", or
+equivalent.
+
+Do NOT show this prompt:
+
+- if the call succeeds (no error to recover from);
+- if you already have a working token for this hostname (resolved
+  from locksmith earlier in this session, from environment, or
+  supplied by the user) - reuse it instead;
+- if the user has already chosen "Skip" for this hostname in this
+  session - track skipped hostnames in your working memory;
+- on subsequent failures for the same hostname in this session
+  (only the FIRST failure triggers the prompt).
+
+Scope key = the request's hostname (e.g. `api.github.com`). Different
+paths under the same hostname share the scope.
+
+### The prompt
+
+Show exactly this message, substituting `<HOSTNAME>` with the real
+hostname:
+
+> A token for `<HOSTNAME>` may be in locksmith. Choose one:
+>
+> 1. Skip - do not ask again for `<HOSTNAME>` this session.
+> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will
+>    run `locksmith get` and retry.
+> 3. Other - paste the token directly, or describe what to do.
+
+Then wait for the user's reply.
+
+### Handling each choice
+
+- **1 / Skip**: record `<HOSTNAME>` as skipped for the rest of this
+  session and never re-prompt for it. Continue with whatever path
+  you would have taken without the prompt (surface the original
+  error, try an env var, abort, etc.).
+
+- **2 / Locksmith**: parse the user's input and run the matching
+  `locksmith get` command:
+
+  | User input form              | Command                              |
+  |------------------------------|--------------------------------------|
+  | `gh-token` (bare alias)      | `locksmith get --key gh-token`       |
+  | `key:gh-token`               | `locksmith get --key gh-token`       |
+  | `vault:keychain path:gh/tok` | `locksmith get --vault keychain --path gh/tok` |
+  | `--vault keychain --path gh/tok` (verbatim flags) | pass through |
+
+  On success: use the resolved value as the bearer token and retry.
+  Cache it for further calls to the same hostname in this session;
+  do not re-run `locksmith get` for the same hostname.
+
+  On `locksmith get` failure (missing key, daemon down): surface the
+  locksmith error verbatim. Do NOT silently fall back.
+
+- **3 / Other**: treat the input as free-text. If it looks like a
+  raw token, use it as the bearer token. Otherwise, follow the
+  user's instructions literally.
+
+Never re-prompt for the same hostname in the same session,
+regardless of which option was picked.
+
+### Disambiguation vs MCP fallback
+
+If you cannot tell whether a failure belongs to this flow or to the
+MCP fallback above: read your own MCP config. If the failing call
+originated from an MCP entry whose `command` is `"locksmith"` with
+`args` starting with `["mcp", "run", ...]`, use the MCP fallback.
+Any HTTP call not initiated by such an entry uses this flow. Do not
+consult locksmith's config file directly.
+
+### Example
+
+You attempted: `GET https://api.github.com/user`
+You got: HTTP 401 Unauthorized
+
+(First failure for `api.github.com` this session - prompt the user.)
+
+> A token for `api.github.com` may be in locksmith. Choose one:
+>
+> 1. Skip - do not ask again for `api.github.com` this session.
+> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will
+>    run `locksmith get` and retry.
+> 3. Other - paste the token directly, or describe what to do.
+
+User: `gh-token`
+
+You run:
+
+    TOKEN=$(locksmith get --key gh-token)
+
+Then retry:
+
+    curl -H "Authorization: Bearer $TOKEN" https://api.github.com/user
+
+Cache $TOKEN for further `api.github.com` calls this session; do
+not re-run `locksmith get` for the same hostname.
+
 - Sessions expire automatically by TTL; no manual cleanup needed.
 - Pass `LOCKSMITH_SESSION` to sub-agents to share the parent session.
 <!-- LOCKSMITH_END -->
diff --git a/internal/initflow/agents/claude/templates/claude_skill.md.tmpl b/internal/initflow/agents/claude/templates/claude_skill.md.tmpl
index e143d8b..93368a4 100644
--- a/internal/initflow/agents/claude/templates/claude_skill.md.tmpl
+++ b/internal/initflow/agents/claude/templates/claude_skill.md.tmpl
@@ -115,5 +115,109 @@ Fallback:
     export LINEAR_API_KEY
     exec linear-mcp --workspace acme
 
+**External APIs - try Locksmith on auth failure**
+
+When you call an external HTTP API (not via a locksmith-wrapped MCP)
+and you get the first auth/access error for that API's hostname in
+this session, ask the user once whether the token may be in
+locksmith. "Auth/access error" means HTTP `401`, HTTP `403`, or a
+response body containing "invalid token", "unauthorized", or
+equivalent.
+
+Do NOT show this prompt:
+
+- if the call succeeds (no error to recover from);
+- if you already have a working token for this hostname (resolved
+  from locksmith earlier in this session, from environment, or
+  supplied by the user) - reuse it instead;
+- if the user has already chosen "Skip" for this hostname in this
+  session - track skipped hostnames in your working memory;
+- on subsequent failures for the same hostname in this session
+  (only the FIRST failure triggers the prompt).
+
+Scope key = the request's hostname (e.g. `api.github.com`). Different
+paths under the same hostname share the scope.
+
+**The prompt**
+
+Show exactly this message, substituting `<HOSTNAME>` with the real
+hostname:
+
+> A token for `<HOSTNAME>` may be in locksmith. Choose one:
+>
+> 1. Skip - do not ask again for `<HOSTNAME>` this session.
+> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will
+>    run `locksmith get` and retry.
+> 3. Other - paste the token directly, or describe what to do.
+
+Then wait for the user's reply.
+
+**Handling each choice**
+
+- **1 / Skip**: record `<HOSTNAME>` as skipped for the rest of this
+  session and never re-prompt for it. Continue with whatever path
+  you would have taken without the prompt (surface the original
+  error, try an env var, abort, etc.).
+
+- **2 / Locksmith**: parse the user's input and run the matching
+  `locksmith get` command:
+
+  | User input form              | Command                              |
+  |------------------------------|--------------------------------------|
+  | `gh-token` (bare alias)      | `locksmith get --key gh-token`       |
+  | `key:gh-token`               | `locksmith get --key gh-token`       |
+  | `vault:keychain path:gh/tok` | `locksmith get --vault keychain --path gh/tok` |
+  | `--vault keychain --path gh/tok` (verbatim flags) | pass through |
+
+  On success: use the resolved value as the bearer token and retry.
+  Cache it for further calls to the same hostname in this session;
+  do not re-run `locksmith get` for the same hostname.
+
+  On `locksmith get` failure (missing key, daemon down): surface the
+  locksmith error verbatim. Do NOT silently fall back.
+
+- **3 / Other**: treat the input as free-text. If it looks like a
+  raw token, use it as the bearer token. Otherwise, follow the
+  user's instructions literally.
+
+Never re-prompt for the same hostname in the same session,
+regardless of which option was picked.
+
+**Disambiguation vs MCP fallback**
+
+If you cannot tell whether a failure belongs to this flow or to the
+MCP fallback above: read your own MCP config. If the failing call
+originated from an MCP entry whose `command` is `"locksmith"` with
+`args` starting with `["mcp", "run", ...]`, use the MCP fallback.
+Any HTTP call not initiated by such an entry uses this flow. Do not
+consult locksmith's config file directly.
+
+**Example**
+
+You attempted: `GET https://api.github.com/user`
+You got: HTTP 401 Unauthorized
+
+(First failure for `api.github.com` this session - prompt the user.)
+
+> A token for `api.github.com` may be in locksmith. Choose one:
+>
+> 1. Skip - do not ask again for `api.github.com` this session.
+> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will
+>    run `locksmith get` and retry.
+> 3. Other - paste the token directly, or describe what to do.
+
+User: `gh-token`
+
+You run:
+
+    TOKEN=$(locksmith get --key gh-token)
+
+Then retry:
+
+    curl -H "Authorization: Bearer $TOKEN" https://api.github.com/user
+
+Cache $TOKEN for further `api.github.com` calls this session; do
+not re-run `locksmith get` for the same hostname.
+
 Never hardcode secrets. Never cache secrets outside of locksmith.
 <!-- LOCKSMITH_END -->
diff --git a/internal/initflow/agents/codex/templates/codex_agents.md.tmpl b/internal/initflow/agents/codex/templates/codex_agents.md.tmpl
index f3ffee1..170c31d 100644
--- a/internal/initflow/agents/codex/templates/codex_agents.md.tmpl
+++ b/internal/initflow/agents/codex/templates/codex_agents.md.tmpl
@@ -121,5 +121,109 @@ Fallback:
     export LINEAR_API_KEY
     exec linear-mcp --workspace acme
 
+## External APIs - try Locksmith on auth failure
+
+When you call an external HTTP API (not via a locksmith-wrapped MCP)
+and you get the first auth/access error for that API's hostname in
+this session, ask the user once whether the token may be in
+locksmith. "Auth/access error" means HTTP `401`, HTTP `403`, or a
+response body containing "invalid token", "unauthorized", or
+equivalent.
+
+Do NOT show this prompt:
+
+- if the call succeeds (no error to recover from);
+- if you already have a working token for this hostname (resolved
+  from locksmith earlier in this session, from environment, or
+  supplied by the user) - reuse it instead;
+- if the user has already chosen "Skip" for this hostname in this
+  session - track skipped hostnames in your working memory;
+- on subsequent failures for the same hostname in this session
+  (only the FIRST failure triggers the prompt).
+
+Scope key = the request's hostname (e.g. `api.github.com`). Different
+paths under the same hostname share the scope.
+
+### The prompt
+
+Show exactly this message, substituting `<HOSTNAME>` with the real
+hostname:
+
+> A token for `<HOSTNAME>` may be in locksmith. Choose one:
+>
+> 1. Skip - do not ask again for `<HOSTNAME>` this session.
+> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will
+>    run `locksmith get` and retry.
+> 3. Other - paste the token directly, or describe what to do.
+
+Then wait for the user's reply.
+
+### Handling each choice
+
+- **1 / Skip**: record `<HOSTNAME>` as skipped for the rest of this
+  session and never re-prompt for it. Continue with whatever path
+  you would have taken without the prompt (surface the original
+  error, try an env var, abort, etc.).
+
+- **2 / Locksmith**: parse the user's input and run the matching
+  `locksmith get` command:
+
+  | User input form              | Command                              |
+  |------------------------------|--------------------------------------|
+  | `gh-token` (bare alias)      | `locksmith get --key gh-token`       |
+  | `key:gh-token`               | `locksmith get --key gh-token`       |
+  | `vault:keychain path:gh/tok` | `locksmith get --vault keychain --path gh/tok` |
+  | `--vault keychain --path gh/tok` (verbatim flags) | pass through |
+
+  On success: use the resolved value as the bearer token and retry.
+  Cache it for further calls to the same hostname in this session;
+  do not re-run `locksmith get` for the same hostname.
+
+  On `locksmith get` failure (missing key, daemon down): surface the
+  locksmith error verbatim. Do NOT silently fall back.
+
+- **3 / Other**: treat the input as free-text. If it looks like a
+  raw token, use it as the bearer token. Otherwise, follow the
+  user's instructions literally.
+
+Never re-prompt for the same hostname in the same session,
+regardless of which option was picked.
+
+### Disambiguation vs MCP fallback
+
+If you cannot tell whether a failure belongs to this flow or to the
+MCP fallback above: read your own MCP config. If the failing call
+originated from an MCP entry whose `command` is `"locksmith"` with
+`args` starting with `["mcp", "run", ...]`, use the MCP fallback.
+Any HTTP call not initiated by such an entry uses this flow. Do not
+consult locksmith's config file directly.
+
+### Example
+
+You attempted: `GET https://api.github.com/user`
+You got: HTTP 401 Unauthorized
+
+(First failure for `api.github.com` this session - prompt the user.)
+
+> A token for `api.github.com` may be in locksmith. Choose one:
+>
+> 1. Skip - do not ask again for `api.github.com` this session.
+> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will
+>    run `locksmith get` and retry.
+> 3. Other - paste the token directly, or describe what to do.
+
+User: `gh-token`
+
+You run:
+
+    TOKEN=$(locksmith get --key gh-token)
+
+Then retry:
+
+    curl -H "Authorization: Bearer $TOKEN" https://api.github.com/user
+
+Cache $TOKEN for further `api.github.com` calls this session; do
+not re-run `locksmith get` for the same hostname.
+
 Pass `LOCKSMITH_SESSION` to sub-agents so they share the parent session.
 <!-- LOCKSMITH_END -->
diff --git a/internal/initflow/agents/gemini/templates/gemini_md.md.tmpl b/internal/initflow/agents/gemini/templates/gemini_md.md.tmpl
index 3efeeb4..711bb1c 100644
--- a/internal/initflow/agents/gemini/templates/gemini_md.md.tmpl
+++ b/internal/initflow/agents/gemini/templates/gemini_md.md.tmpl
@@ -122,6 +122,110 @@ Fallback:
     export LINEAR_API_KEY
     exec linear-mcp --workspace acme
 
+## External APIs - try Locksmith on auth failure
+
+When you call an external HTTP API (not via a locksmith-wrapped MCP)
+and you get the first auth/access error for that API's hostname in
+this session, ask the user once whether the token may be in
+locksmith. "Auth/access error" means HTTP `401`, HTTP `403`, or a
+response body containing "invalid token", "unauthorized", or
+equivalent.
+
+Do NOT show this prompt:
+
+- if the call succeeds (no error to recover from);
+- if you already have a working token for this hostname (resolved
+  from locksmith earlier in this session, from environment, or
+  supplied by the user) - reuse it instead;
+- if the user has already chosen "Skip" for this hostname in this
+  session - track skipped hostnames in your working memory;
+- on subsequent failures for the same hostname in this session
+  (only the FIRST failure triggers the prompt).
+
+Scope key = the request's hostname (e.g. `api.github.com`). Different
+paths under the same hostname share the scope.
+
+### The prompt
+
+Show exactly this message, substituting `<HOSTNAME>` with the real
+hostname:
+
+> A token for `<HOSTNAME>` may be in locksmith. Choose one:
+>
+> 1. Skip - do not ask again for `<HOSTNAME>` this session.
+> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will
+>    run `locksmith get` and retry.
+> 3. Other - paste the token directly, or describe what to do.
+
+Then wait for the user's reply.
+
+### Handling each choice
+
+- **1 / Skip**: record `<HOSTNAME>` as skipped for the rest of this
+  session and never re-prompt for it. Continue with whatever path
+  you would have taken without the prompt (surface the original
+  error, try an env var, abort, etc.).
+
+- **2 / Locksmith**: parse the user's input and run the matching
+  `locksmith get` command:
+
+  | User input form              | Command                              |
+  |------------------------------|--------------------------------------|
+  | `gh-token` (bare alias)      | `locksmith get --key gh-token`       |
+  | `key:gh-token`               | `locksmith get --key gh-token`       |
+  | `vault:keychain path:gh/tok` | `locksmith get --vault keychain --path gh/tok` |
+  | `--vault keychain --path gh/tok` (verbatim flags) | pass through |
+
+  On success: use the resolved value as the bearer token and retry.
+  Cache it for further calls to the same hostname in this session;
+  do not re-run `locksmith get` for the same hostname.
+
+  On `locksmith get` failure (missing key, daemon down): surface the
+  locksmith error verbatim. Do NOT silently fall back.
+
+- **3 / Other**: treat the input as free-text. If it looks like a
+  raw token, use it as the bearer token. Otherwise, follow the
+  user's instructions literally.
+
+Never re-prompt for the same hostname in the same session,
+regardless of which option was picked.
+
+### Disambiguation vs MCP fallback
+
+If you cannot tell whether a failure belongs to this flow or to the
+MCP fallback above: read your own MCP config. If the failing call
+originated from an MCP entry whose `command` is `"locksmith"` with
+`args` starting with `["mcp", "run", ...]`, use the MCP fallback.
+Any HTTP call not initiated by such an entry uses this flow. Do not
+consult locksmith's config file directly.
+
+### Example
+
+You attempted: `GET https://api.github.com/user`
+You got: HTTP 401 Unauthorized
+
+(First failure for `api.github.com` this session - prompt the user.)
+
+> A token for `api.github.com` may be in locksmith. Choose one:
+>
+> 1. Skip - do not ask again for `api.github.com` this session.
+> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will
+>    run `locksmith get` and retry.
+> 3. Other - paste the token directly, or describe what to do.
+
+User: `gh-token`
+
+You run:
+
+    TOKEN=$(locksmith get --key gh-token)
+
+Then retry:
+
+    curl -H "Authorization: Bearer $TOKEN" https://api.github.com/user
+
+Cache $TOKEN for further `api.github.com` calls this session; do
+not re-run `locksmith get` for the same hostname.
+
 ## Sub-agent Session Passing
 
 When spawning sub-agents, export `LOCKSMITH_SESSION` into their
diff --git a/internal/initflow/agents/generic/templates/instructions.md.tmpl b/internal/initflow/agents/generic/templates/instructions.md.tmpl
index 4cbed3b..4eb5dc8 100644
--- a/internal/initflow/agents/generic/templates/instructions.md.tmpl
+++ b/internal/initflow/agents/generic/templates/instructions.md.tmpl
@@ -118,6 +118,110 @@ Fallback:
     export LINEAR_API_KEY
     exec linear-mcp --workspace acme
 
+## External APIs - try Locksmith on auth failure
+
+When you call an external HTTP API (not via a locksmith-wrapped MCP)
+and you get the first auth/access error for that API's hostname in
+this session, ask the user once whether the token may be in
+locksmith. "Auth/access error" means HTTP `401`, HTTP `403`, or a
+response body containing "invalid token", "unauthorized", or
+equivalent.
+
+Do NOT show this prompt:
+
+- if the call succeeds (no error to recover from);
+- if you already have a working token for this hostname (resolved
+  from locksmith earlier in this session, from environment, or
+  supplied by the user) - reuse it instead;
+- if the user has already chosen "Skip" for this hostname in this
+  session - track skipped hostnames in your working memory;
+- on subsequent failures for the same hostname in this session
+  (only the FIRST failure triggers the prompt).
+
+Scope key = the request's hostname (e.g. `api.github.com`). Different
+paths under the same hostname share the scope.
+
+### The prompt
+
+Show exactly this message, substituting `<HOSTNAME>` with the real
+hostname:
+
+> A token for `<HOSTNAME>` may be in locksmith. Choose one:
+>
+> 1. Skip - do not ask again for `<HOSTNAME>` this session.
+> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will
+>    run `locksmith get` and retry.
+> 3. Other - paste the token directly, or describe what to do.
+
+Then wait for the user's reply.
+
+### Handling each choice
+
+- **1 / Skip**: record `<HOSTNAME>` as skipped for the rest of this
+  session and never re-prompt for it. Continue with whatever path
+  you would have taken without the prompt (surface the original
+  error, try an env var, abort, etc.).
+
+- **2 / Locksmith**: parse the user's input and run the matching
+  `locksmith get` command:
+
+  | User input form              | Command                              |
+  |------------------------------|--------------------------------------|
+  | `gh-token` (bare alias)      | `locksmith get --key gh-token`       |
+  | `key:gh-token`               | `locksmith get --key gh-token`       |
+  | `vault:keychain path:gh/tok` | `locksmith get --vault keychain --path gh/tok` |
+  | `--vault keychain --path gh/tok` (verbatim flags) | pass through |
+
+  On success: use the resolved value as the bearer token and retry.
+  Cache it for further calls to the same hostname in this session;
+  do not re-run `locksmith get` for the same hostname.
+
+  On `locksmith get` failure (missing key, daemon down): surface the
+  locksmith error verbatim. Do NOT silently fall back.
+
+- **3 / Other**: treat the input as free-text. If it looks like a
+  raw token, use it as the bearer token. Otherwise, follow the
+  user's instructions literally.
+
+Never re-prompt for the same hostname in the same session,
+regardless of which option was picked.
+
+### Disambiguation vs MCP fallback
+
+If you cannot tell whether a failure belongs to this flow or to the
+MCP fallback above: read your own MCP config. If the failing call
+originated from an MCP entry whose `command` is `"locksmith"` with
+`args` starting with `["mcp", "run", ...]`, use the MCP fallback.
+Any HTTP call not initiated by such an entry uses this flow. Do not
+consult locksmith's config file directly.
+
+### Example
+
+You attempted: `GET https://api.github.com/user`
+You got: HTTP 401 Unauthorized
+
+(First failure for `api.github.com` this session - prompt the user.)
+
+> A token for `api.github.com` may be in locksmith. Choose one:
+>
+> 1. Skip - do not ask again for `api.github.com` this session.
+> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will
+>    run `locksmith get` and retry.
+> 3. Other - paste the token directly, or describe what to do.
+
+User: `gh-token`
+
+You run:
+
+    TOKEN=$(locksmith get --key gh-token)
+
+Then retry:
+
+    curl -H "Authorization: Bearer $TOKEN" https://api.github.com/user
+
+Cache $TOKEN for further `api.github.com` calls this session; do
+not re-run `locksmith get` for the same hostname.
+
 ## Sub-Agents
 
 Pass `LOCKSMITH_SESSION` to sub-agents via environment so they share
diff --git a/internal/initflow/agents/opencode/templates/instructions.md.tmpl b/internal/initflow/agents/opencode/templates/instructions.md.tmpl
index 308c5fd..0ee122c 100644
--- a/internal/initflow/agents/opencode/templates/instructions.md.tmpl
+++ b/internal/initflow/agents/opencode/templates/instructions.md.tmpl
@@ -120,6 +120,110 @@ Fallback:
     export LINEAR_API_KEY
     exec linear-mcp --workspace acme
 
+## External APIs - try Locksmith on auth failure
+
+When you call an external HTTP API (not via a locksmith-wrapped MCP)
+and you get the first auth/access error for that API's hostname in
+this session, ask the user once whether the token may be in
+locksmith. "Auth/access error" means HTTP `401`, HTTP `403`, or a
+response body containing "invalid token", "unauthorized", or
+equivalent.
+
+Do NOT show this prompt:
+
+- if the call succeeds (no error to recover from);
+- if you already have a working token for this hostname (resolved
+  from locksmith earlier in this session, from environment, or
+  supplied by the user) - reuse it instead;
+- if the user has already chosen "Skip" for this hostname in this
+  session - track skipped hostnames in your working memory;
+- on subsequent failures for the same hostname in this session
+  (only the FIRST failure triggers the prompt).
+
+Scope key = the request's hostname (e.g. `api.github.com`). Different
+paths under the same hostname share the scope.
+
+### The prompt
+
+Show exactly this message, substituting `<HOSTNAME>` with the real
+hostname:
+
+> A token for `<HOSTNAME>` may be in locksmith. Choose one:
+>
+> 1. Skip - do not ask again for `<HOSTNAME>` this session.
+> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will
+>    run `locksmith get` and retry.
+> 3. Other - paste the token directly, or describe what to do.
+
+Then wait for the user's reply.
+
+### Handling each choice
+
+- **1 / Skip**: record `<HOSTNAME>` as skipped for the rest of this
+  session and never re-prompt for it. Continue with whatever path
+  you would have taken without the prompt (surface the original
+  error, try an env var, abort, etc.).
+
+- **2 / Locksmith**: parse the user's input and run the matching
+  `locksmith get` command:
+
+  | User input form              | Command                              |
+  |------------------------------|--------------------------------------|
+  | `gh-token` (bare alias)      | `locksmith get --key gh-token`       |
+  | `key:gh-token`               | `locksmith get --key gh-token`       |
+  | `vault:keychain path:gh/tok` | `locksmith get --vault keychain --path gh/tok` |
+  | `--vault keychain --path gh/tok` (verbatim flags) | pass through |
+
+  On success: use the resolved value as the bearer token and retry.
+  Cache it for further calls to the same hostname in this session;
+  do not re-run `locksmith get` for the same hostname.
+
+  On `locksmith get` failure (missing key, daemon down): surface the
+  locksmith error verbatim. Do NOT silently fall back.
+
+- **3 / Other**: treat the input as free-text. If it looks like a
+  raw token, use it as the bearer token. Otherwise, follow the
+  user's instructions literally.
+
+Never re-prompt for the same hostname in the same session,
+regardless of which option was picked.
+
+### Disambiguation vs MCP fallback
+
+If you cannot tell whether a failure belongs to this flow or to the
+MCP fallback above: read your own MCP config. If the failing call
+originated from an MCP entry whose `command` is `"locksmith"` with
+`args` starting with `["mcp", "run", ...]`, use the MCP fallback.
+Any HTTP call not initiated by such an entry uses this flow. Do not
+consult locksmith's config file directly.
+
+### Example
+
+You attempted: `GET https://api.github.com/user`
+You got: HTTP 401 Unauthorized
+
+(First failure for `api.github.com` this session - prompt the user.)
+
+> A token for `api.github.com` may be in locksmith. Choose one:
+>
+> 1. Skip - do not ask again for `api.github.com` this session.
+> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will
+>    run `locksmith get` and retry.
+> 3. Other - paste the token directly, or describe what to do.
+
+User: `gh-token`
+
+You run:
+
+    TOKEN=$(locksmith get --key gh-token)
+
+Then retry:
+
+    curl -H "Authorization: Bearer $TOKEN" https://api.github.com/user
+
+Cache $TOKEN for further `api.github.com` calls this session; do
+not re-run `locksmith get` for the same hostname.
+
 ## Sub-Agents
 
 Pass `LOCKSMITH_SESSION` to sub-agents via environment so they share

From c2c447130f24b7489e9fc1f7be2cb2fd5c396a45 Mon Sep 17 00:00:00 2001
From: Lorem Dev <contact@lorem.dev>
Date: Sat, 23 May 2026 11:21:33 +0200
Subject: [PATCH 6/6] refactor(initflow): tighten locksmith sections in agent
 templates

Shorten the runtime-whitelist, MCP-fallback, and external-API
auth-failure sections by ~45% with the same semantics. Add an
explicit "execute these steps; do not ask clarifying questions"
directive to the MCP fallback so smaller models commit to the
recovery path instead of pausing for confirmation.
---
 CHANGES.md                                    |   1 +
 .../agents/claude/templates/claude_md.md.tmpl | 208 ++++++------------
 .../claude/templates/claude_skill.md.tmpl     | 207 ++++++-----------
 .../codex/templates/codex_agents.md.tmpl      | 208 ++++++------------
 .../agents/gemini/templates/gemini_md.md.tmpl | 208 ++++++------------
 .../generic/templates/instructions.md.tmpl    | 208 ++++++------------
 .../opencode/templates/instructions.md.tmpl   | 208 ++++++------------
 7 files changed, 379 insertions(+), 869 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index b8dc6de..42cee27 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -66,6 +66,7 @@
 - Agent templates now document an MCP-wrapper fallback: when a locksmith-wrapped MCP server fails, the agent parses `--header` and `--env` templates from its own MCP config, resolves them via `locksmith get`, and runs the server directly. Templates also whitelist `session ensure`, `serve`, and `get` as the only runtime locksmith commands.
 - The verification GPG gate now ignores GitHub-generated "Merge pull request" commits: their `web-flow` signature is often expired locally and they cannot be re-signed without diverging from the remote.
 - Agent templates now document a recovery prompt for external HTTP API auth failures: on the first 401/403 for a hostname, the agent asks the user to (1) Skip, (2) provide a locksmith key or vault+path, or (3) paste the token directly. Resolved tokens are cached per hostname for the rest of the session; Skip suppresses further prompts for that hostname.
+- Tightened the runtime-whitelist, MCP-fallback, and external-API auth-failure sections in agent templates (~45% shorter; same semantics). The MCP fallback now opens with an explicit "execute these steps; do not ask the user clarifying questions" directive so smaller models commit to the recovery path instead of pausing for confirmation. Validated across multiple parallel sub-agent runs on Sonnet and Haiku covering both flows.
 
 ## Version v0.3.0 - 2026-05-15
 
diff --git a/internal/initflow/agents/claude/templates/claude_md.md.tmpl b/internal/initflow/agents/claude/templates/claude_md.md.tmpl
index d6ac870..5922276 100644
--- a/internal/initflow/agents/claude/templates/claude_md.md.tmpl
+++ b/internal/initflow/agents/claude/templates/claude_md.md.tmpl
@@ -21,201 +21,119 @@ Just call `locksmith get` directly.
 Use ONLY these at runtime:
 
 - `locksmith session ensure --quiet` - obtain/refresh a session ID
-- `locksmith serve` - start the daemon if it is not running
-  (rare; `session ensure` will spawn it automatically)
-- `locksmith get --key <alias>` or `--vault <name> --path <path>` -
-  fetch a secret
+- `locksmith serve` - start the daemon (rare; `session ensure` spawns it)
+- `locksmith get --key <alias>` or `--vault <name> --path <path>` - fetch a secret
 
-Do not call `init`, `vault`, `plugins`, `config`, `reload`, `mcp`,
-or any other subcommand - they are for the human operator only.
+Never call `init`, `vault`, `plugins`, `config`, `reload`, `mcp`, or any other
+subcommand - those are for the human operator.
 
 ## MCP Servers and Locksmith
 
-The MCP server config lives in **the agent's own settings**
-(e.g. `~/.claude.json`, `~/.codex/mcp.json`, `~/.gemini/...`),
-NOT in locksmith's config file. Always read from there.
+MCP config is in your agent's own settings (e.g. `~/.claude.json`), NOT in
+locksmith's config. Read it from there.
 
-- If an MCP entry's `command` is anything other than `"locksmith"` -
-  run it exactly as written. Do not wrap it in locksmith. Behave
-  as if locksmith does not exist for this server.
-- If `command` is `"locksmith"` with `args` starting with
-  `["mcp", "run", ...]` - the server is locksmith-wrapped. If it
-  fails to start or returns an auth error, apply the fallback below.
+- `command` != `"locksmith"` -> run as written; act as if locksmith does not
+  exist for this server.
+- `command` == `"locksmith"` with `args` starting `["mcp", "run", ...]` ->
+  locksmith-wrapped. If it fails or returns an auth error, apply the fallback.
 
 ### Fallback for locksmith-wrapped MCP servers
 
-1. Parse these flags from the entry's `args` (after `mcp run`):
-   - `--header Name=<template>` - HTTP header (proxy mode)
-   - `--env VAR=<template>` - environment variable (local mode)
-   - `--url <url>` - remote endpoint (proxy mode)
-   - tokens after `--` - the underlying command + args (local mode)
+These steps are mandatory whenever a locksmith-wrapped server fails -
+startup error, auth error, anything. Execute them; do not ask the user
+clarifying questions.
 
-   Templates look like `{key:<alias>}` or `{vault:<name> path:<value>}`.
+1. Parse args after `mcp run`: `--header Name=<tpl>`, `--env VAR=<tpl>`,
+   `--url <url>`, tokens after `--`. Templates: `{key:<alias>}` or
+   `{vault:<name> path:<value>}`.
+2. Resolve: `{key:alias}` -> `locksmith get --key alias`;
+   `{vault:name path:p}` -> `locksmith get --vault name --path p`.
+3. Run directly: local = export env, exec post-`--` cmd; proxy = HTTP to
+   `--url` with resolved headers (no process to spawn).
+4. Still denied? Ask user (replace `<MCP_NAME>`; use real header/arg names):
 
-2. Resolve each template manually:
-   - `{key:alias}` -> `locksmith get --key alias`
-   - `{vault:name path:p}` -> `locksmith get --vault name --path p`
-
-3. Run the MCP server **directly** with the resolved values:
-   - local mode: export the resolved env vars, exec the command
-     from after `--`;
-   - proxy mode: there is no process to spawn - send HTTP requests
-     to `--url` yourself with the resolved headers.
-
-4. If access is still denied, prompt the user (replace `<MCP_NAME>`
-   with the entry name; substitute the placeholder values below
-   with header/arg names you actually saw in the entry):
-
-   > Enter credentials for MCP `<MCP_NAME>` in this format:
-   >
-   >     headers: {"X-Authorization": "Bearer ...", "X-Request-ID": "..."}
-   >     args: --arg1 value1 --arg2 "value2" --flag3
+   > Enter credentials for MCP `<MCP_NAME>`:
    >
-   > Parse the user's `headers` and `args` and retry the MCP
-   > server with them.
+   >     headers: {"Authorization": "Bearer ...", "X-Request-ID": "..."}
+   >     args: --arg1 value1 --flag2
 
-If `locksmith get` itself fails (missing key, daemon down), surface
-that error to the user verbatim. Do NOT fall through to the
-credential prompt; the prompt is for auth-denial only.
+   Parse `headers`/`args` and retry.
 
-### Examples
+If `locksmith get` itself fails, surface the error verbatim. Do NOT fall
+through to the credential prompt - it is for auth-denial only.
 
-Proxy-mode entry (header from key alias + header from direct
-vault+path):
+### Example
 
     "github": {
       "command": "locksmith",
-      "args": ["mcp", "run", "--url", "https://api.githubcopilot.com/mcp",
-               "--header", "Authorization=Bearer {key:gh-token}",
-               "--header", "X-Org-ID={vault:keychain path:gh/org}"]
+      "args": ["mcp", "run", "--url", "https://api.example.com/mcp",
+               "--header", "Authorization=Bearer {key:gh-token}"]
     }
 
 Fallback:
 
     TOKEN=$(locksmith get --key gh-token)
-    ORG=$(locksmith get --vault keychain --path gh/org)
-    # then call https://api.githubcopilot.com/mcp with:
-    #   Authorization: Bearer $TOKEN
-    #   X-Org-ID: $ORG
+    # then call https://api.example.com/mcp with: Authorization: Bearer $TOKEN
 
-Local-mode entry (env via vault+path, real binary after `--`):
-
-    "linear": {
-      "command": "locksmith",
-      "args": ["mcp", "run",
-               "--env", "LINEAR_API_KEY={vault:keychain path:linear/api-key}",
-               "--", "linear-mcp", "--workspace", "acme"]
-    }
-
-Fallback:
-
-    LINEAR_API_KEY=$(locksmith get --vault keychain --path linear/api-key)
-    export LINEAR_API_KEY
-    exec linear-mcp --workspace acme
+Local-mode entry (env via `{vault:name path:p}` + binary after `--`): resolve
+with `locksmith get --vault name --path p`, export, then exec the post-`--` cmd.
 
 ## External APIs - try Locksmith on auth failure
 
-When you call an external HTTP API (not via a locksmith-wrapped MCP)
-and you get the first auth/access error for that API's hostname in
-this session, ask the user once whether the token may be in
-locksmith. "Auth/access error" means HTTP `401`, HTTP `403`, or a
-response body containing "invalid token", "unauthorized", or
-equivalent.
-
-Do NOT show this prompt:
-
-- if the call succeeds (no error to recover from);
-- if you already have a working token for this hostname (resolved
-  from locksmith earlier in this session, from environment, or
-  supplied by the user) - reuse it instead;
-- if the user has already chosen "Skip" for this hostname in this
-  session - track skipped hostnames in your working memory;
-- on subsequent failures for the same hostname in this session
-  (only the FIRST failure triggers the prompt).
+On the first auth/access error for an external API's hostname this session,
+ask the user once. "Auth/access error" = HTTP `401`/`403`, or body containing
+"invalid token"/"unauthorized".
 
-Scope key = the request's hostname (e.g. `api.github.com`). Different
-paths under the same hostname share the scope.
-
-### The prompt
-
-Show exactly this message, substituting `<HOSTNAME>` with the real
-hostname:
+Show (substitute `<HOSTNAME>`):
 
 > A token for `<HOSTNAME>` may be in locksmith. Choose one:
 >
 > 1. Skip - do not ask again for `<HOSTNAME>` this session.
-> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will
->    run `locksmith get` and retry.
+> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will run
+>    `locksmith get` and retry.
 > 3. Other - paste the token directly, or describe what to do.
 
-Then wait for the user's reply.
-
-### Handling each choice
+Scope = hostname (e.g. `api.github.com`). Paths share the scope.
 
-- **1 / Skip**: record `<HOSTNAME>` as skipped for the rest of this
-  session and never re-prompt for it. Continue with whatever path
-  you would have taken without the prompt (surface the original
-  error, try an env var, abort, etc.).
+Do NOT prompt if: the call succeeded; you have a working token for this
+hostname (reuse it); the user already chose Skip this session; or this is a
+subsequent failure for the same hostname (first failure only).
 
-- **2 / Locksmith**: parse the user's input and run the matching
-  `locksmith get` command:
-
-  | User input form              | Command                              |
-  |------------------------------|--------------------------------------|
-  | `gh-token` (bare alias)      | `locksmith get --key gh-token`       |
-  | `key:gh-token`               | `locksmith get --key gh-token`       |
-  | `vault:keychain path:gh/tok` | `locksmith get --vault keychain --path gh/tok` |
-  | `--vault keychain --path gh/tok` (verbatim flags) | pass through |
-
-  On success: use the resolved value as the bearer token and retry.
-  Cache it for further calls to the same hostname in this session;
-  do not re-run `locksmith get` for the same hostname.
+### Handling each choice
 
-  On `locksmith get` failure (missing key, daemon down): surface the
-  locksmith error verbatim. Do NOT silently fall back.
+- **Skip**: record hostname as skipped; never re-prompt; continue without it.
+- **Locksmith**: parse and run:
+  - `gh-token` or `key:gh-token` -> `locksmith get --key gh-token`
+  - `vault:keychain path:gh/tok` or `--vault keychain --path gh/tok` ->
+    `locksmith get --vault keychain --path gh/tok`
 
-- **3 / Other**: treat the input as free-text. If it looks like a
-  raw token, use it as the bearer token. Otherwise, follow the
-  user's instructions literally.
+  Use the value as the bearer token and retry. Cache $TOKEN for further calls
+  to the same hostname this session; do not re-run `locksmith get`. If
+  `locksmith get` itself fails, surface the error verbatim - do NOT silently
+  fall back.
+- **Other**: free-text. If it looks like a token, use it. Otherwise follow
+  the instructions literally.
 
-Never re-prompt for the same hostname in the same session,
-regardless of which option was picked.
+Never re-prompt for the same hostname this session, regardless of choice.
 
 ### Disambiguation vs MCP fallback
 
-If you cannot tell whether a failure belongs to this flow or to the
-MCP fallback above: read your own MCP config. If the failing call
-originated from an MCP entry whose `command` is `"locksmith"` with
-`args` starting with `["mcp", "run", ...]`, use the MCP fallback.
-Any HTTP call not initiated by such an entry uses this flow. Do not
-consult locksmith's config file directly.
+If the failing call originated from an MCP entry whose `command` is
+`"locksmith"` with `args` starting `["mcp", "run", ...]`, use the MCP
+fallback. Otherwise use this flow. Do not consult locksmith's config file.
 
 ### Example
 
-You attempted: `GET https://api.github.com/user`
-You got: HTTP 401 Unauthorized
+`GET https://api.github.com/user` -> 401. First failure for `api.github.com`:
 
-(First failure for `api.github.com` this session - prompt the user.)
+> A token for `api.github.com` may be in locksmith. Choose one: 1. Skip ...
 
-> A token for `api.github.com` may be in locksmith. Choose one:
->
-> 1. Skip - do not ask again for `api.github.com` this session.
-> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will
->    run `locksmith get` and retry.
-> 3. Other - paste the token directly, or describe what to do.
-
-User: `gh-token`
-
-You run:
+User: `gh-token` ->
 
     TOKEN=$(locksmith get --key gh-token)
-
-Then retry:
-
     curl -H "Authorization: Bearer $TOKEN" https://api.github.com/user
 
-Cache $TOKEN for further `api.github.com` calls this session; do
-not re-run `locksmith get` for the same hostname.
+Cache $TOKEN for further `api.github.com` calls this session.
 
 - Sessions expire automatically by TTL; no manual cleanup needed.
 - Pass `LOCKSMITH_SESSION` to sub-agents to share the parent session.
diff --git a/internal/initflow/agents/claude/templates/claude_skill.md.tmpl b/internal/initflow/agents/claude/templates/claude_skill.md.tmpl
index 93368a4..b36dbf2 100644
--- a/internal/initflow/agents/claude/templates/claude_skill.md.tmpl
+++ b/internal/initflow/agents/claude/templates/claude_skill.md.tmpl
@@ -24,200 +24,119 @@ prompt, so no manual session step is needed.
 Use ONLY these at runtime:
 
 - `locksmith session ensure --quiet` - obtain/refresh a session ID
-- `locksmith serve` - start the daemon if it is not running
-  (rare; `session ensure` will spawn it automatically)
-- `locksmith get --key <alias>` or `--vault <name> --path <path>` -
-  fetch a secret
+- `locksmith serve` - start the daemon (rare; `session ensure` spawns it)
+- `locksmith get --key <alias>` or `--vault <name> --path <path>` - fetch a secret
 
-Do not call `init`, `vault`, `plugins`, `config`, `reload`, `mcp`,
-or any other subcommand - they are for the human operator only.
+Never call `init`, `vault`, `plugins`, `config`, `reload`, `mcp`, or any other
+subcommand - those are for the human operator.
 
 **MCP Servers and Locksmith**
 
-The MCP server config lives in the agent's own settings
-(e.g. `~/.claude.json`, `~/.codex/mcp.json`, `~/.gemini/...`),
-NOT in locksmith's config file. Always read from there.
+MCP config is in your agent's own settings (e.g. `~/.claude.json`), NOT in
+locksmith's config. Read it from there.
 
-- If an MCP entry's `command` is anything other than `"locksmith"` -
-  run it exactly as written. Do not wrap it in locksmith. Behave
-  as if locksmith does not exist for this server.
-- If `command` is `"locksmith"` with `args` starting with
-  `["mcp", "run", ...]` - the server is locksmith-wrapped. If it
-  fails to start or returns an auth error, apply the fallback below.
+- `command` != `"locksmith"` -> run as written; act as if locksmith does not
+  exist for this server.
+- `command` == `"locksmith"` with `args` starting `["mcp", "run", ...]` ->
+  locksmith-wrapped. If it fails or returns an auth error, apply the fallback.
 
 **Fallback for locksmith-wrapped MCP servers**
 
-1. Parse these flags from the entry's `args` (after `mcp run`):
-   - `--header Name=<template>` - HTTP header (proxy mode)
-   - `--env VAR=<template>` - environment variable (local mode)
-   - `--url <url>` - remote endpoint (proxy mode)
-   - tokens after `--` - the underlying command + args (local mode)
+These steps are mandatory whenever a locksmith-wrapped server fails -
+startup error, auth error, anything. Execute them; do not ask the user
+clarifying questions.
 
-   Templates look like `{key:<alias>}` or `{vault:<name> path:<value>}`.
+1. Parse args after `mcp run`: `--header Name=<tpl>`, `--env VAR=<tpl>`,
+   `--url <url>`, tokens after `--`. Templates: `{key:<alias>}` or
+   `{vault:<name> path:<value>}`.
+2. Resolve: `{key:alias}` -> `locksmith get --key alias`;
+   `{vault:name path:p}` -> `locksmith get --vault name --path p`.
+3. Run directly: local = export env, exec post-`--` cmd; proxy = HTTP to
+   `--url` with resolved headers (no process to spawn).
+4. Still denied? Ask user (replace `<MCP_NAME>`; use real header/arg names):
 
-2. Resolve each template manually:
-   - `{key:alias}` -> `locksmith get --key alias`
-   - `{vault:name path:p}` -> `locksmith get --vault name --path p`
-
-3. Run the MCP server directly with the resolved values:
-   - local mode: export the resolved env vars, exec the command
-     from after `--`;
-   - proxy mode: there is no process to spawn - send HTTP requests
-     to `--url` yourself with the resolved headers.
-
-4. If access is still denied, prompt the user (replace `<MCP_NAME>`
-   with the entry name; substitute the placeholder values below
-   with header/arg names you actually saw in the entry):
-
-   > Enter credentials for MCP `<MCP_NAME>` in this format:
-   >
-   >     headers: {"X-Authorization": "Bearer ...", "X-Request-ID": "..."}
-   >     args: --arg1 value1 --arg2 "value2" --flag3
+   > Enter credentials for MCP `<MCP_NAME>`:
    >
-   > Parse the user's `headers` and `args` and retry the MCP
-   > server with them.
+   >     headers: {"Authorization": "Bearer ...", "X-Request-ID": "..."}
+   >     args: --arg1 value1 --flag2
 
-If `locksmith get` itself fails (missing key, daemon down), surface
-that error to the user verbatim. Do NOT fall through to the
-credential prompt; the prompt is for auth-denial only.
+   Parse `headers`/`args` and retry.
 
-**Examples**
+If `locksmith get` itself fails, surface the error verbatim. Do NOT fall
+through to the credential prompt - it is for auth-denial only.
 
-Proxy-mode entry:
+**Example**
 
     "github": {
       "command": "locksmith",
-      "args": ["mcp", "run", "--url", "https://api.githubcopilot.com/mcp",
-               "--header", "Authorization=Bearer {key:gh-token}",
-               "--header", "X-Org-ID={vault:keychain path:gh/org}"]
+      "args": ["mcp", "run", "--url", "https://api.example.com/mcp",
+               "--header", "Authorization=Bearer {key:gh-token}"]
     }
 
 Fallback:
 
     TOKEN=$(locksmith get --key gh-token)
-    ORG=$(locksmith get --vault keychain --path gh/org)
-    # then call https://api.githubcopilot.com/mcp with:
-    #   Authorization: Bearer $TOKEN
-    #   X-Org-ID: $ORG
+    # then call https://api.example.com/mcp with: Authorization: Bearer $TOKEN
 
-Local-mode entry:
-
-    "linear": {
-      "command": "locksmith",
-      "args": ["mcp", "run",
-               "--env", "LINEAR_API_KEY={vault:keychain path:linear/api-key}",
-               "--", "linear-mcp", "--workspace", "acme"]
-    }
-
-Fallback:
-
-    LINEAR_API_KEY=$(locksmith get --vault keychain --path linear/api-key)
-    export LINEAR_API_KEY
-    exec linear-mcp --workspace acme
+Local-mode entry (env via `{vault:name path:p}` + binary after `--`): resolve
+with `locksmith get --vault name --path p`, export, then exec the post-`--` cmd.
 
 **External APIs - try Locksmith on auth failure**
 
-When you call an external HTTP API (not via a locksmith-wrapped MCP)
-and you get the first auth/access error for that API's hostname in
-this session, ask the user once whether the token may be in
-locksmith. "Auth/access error" means HTTP `401`, HTTP `403`, or a
-response body containing "invalid token", "unauthorized", or
-equivalent.
-
-Do NOT show this prompt:
-
-- if the call succeeds (no error to recover from);
-- if you already have a working token for this hostname (resolved
-  from locksmith earlier in this session, from environment, or
-  supplied by the user) - reuse it instead;
-- if the user has already chosen "Skip" for this hostname in this
-  session - track skipped hostnames in your working memory;
-- on subsequent failures for the same hostname in this session
-  (only the FIRST failure triggers the prompt).
+On the first auth/access error for an external API's hostname this session,
+ask the user once. "Auth/access error" = HTTP `401`/`403`, or body containing
+"invalid token"/"unauthorized".
 
-Scope key = the request's hostname (e.g. `api.github.com`). Different
-paths under the same hostname share the scope.
-
-**The prompt**
-
-Show exactly this message, substituting `<HOSTNAME>` with the real
-hostname:
+Show (substitute `<HOSTNAME>`):
 
 > A token for `<HOSTNAME>` may be in locksmith. Choose one:
 >
 > 1. Skip - do not ask again for `<HOSTNAME>` this session.
-> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will
->    run `locksmith get` and retry.
+> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will run
+>    `locksmith get` and retry.
 > 3. Other - paste the token directly, or describe what to do.
 
-Then wait for the user's reply.
-
-**Handling each choice**
+Scope = hostname (e.g. `api.github.com`). Paths share the scope.
 
-- **1 / Skip**: record `<HOSTNAME>` as skipped for the rest of this
-  session and never re-prompt for it. Continue with whatever path
-  you would have taken without the prompt (surface the original
-  error, try an env var, abort, etc.).
+Do NOT prompt if: the call succeeded; you have a working token for this
+hostname (reuse it); the user already chose Skip this session; or this is a
+subsequent failure for the same hostname (first failure only).
 
-- **2 / Locksmith**: parse the user's input and run the matching
-  `locksmith get` command:
-
-  | User input form              | Command                              |
-  |------------------------------|--------------------------------------|
-  | `gh-token` (bare alias)      | `locksmith get --key gh-token`       |
-  | `key:gh-token`               | `locksmith get --key gh-token`       |
-  | `vault:keychain path:gh/tok` | `locksmith get --vault keychain --path gh/tok` |
-  | `--vault keychain --path gh/tok` (verbatim flags) | pass through |
-
-  On success: use the resolved value as the bearer token and retry.
-  Cache it for further calls to the same hostname in this session;
-  do not re-run `locksmith get` for the same hostname.
+**Handling each choice**
 
-  On `locksmith get` failure (missing key, daemon down): surface the
-  locksmith error verbatim. Do NOT silently fall back.
+- **Skip**: record hostname as skipped; never re-prompt; continue without it.
+- **Locksmith**: parse and run:
+  - `gh-token` or `key:gh-token` -> `locksmith get --key gh-token`
+  - `vault:keychain path:gh/tok` or `--vault keychain --path gh/tok` ->
+    `locksmith get --vault keychain --path gh/tok`
 
-- **3 / Other**: treat the input as free-text. If it looks like a
-  raw token, use it as the bearer token. Otherwise, follow the
-  user's instructions literally.
+  Use the value as the bearer token and retry. Cache $TOKEN for further calls
+  to the same hostname this session; do not re-run `locksmith get`. If
+  `locksmith get` itself fails, surface the error verbatim - do NOT silently
+  fall back.
+- **Other**: free-text. If it looks like a token, use it. Otherwise follow
+  the instructions literally.
 
-Never re-prompt for the same hostname in the same session,
-regardless of which option was picked.
+Never re-prompt for the same hostname this session, regardless of choice.
 
 **Disambiguation vs MCP fallback**
 
-If you cannot tell whether a failure belongs to this flow or to the
-MCP fallback above: read your own MCP config. If the failing call
-originated from an MCP entry whose `command` is `"locksmith"` with
-`args` starting with `["mcp", "run", ...]`, use the MCP fallback.
-Any HTTP call not initiated by such an entry uses this flow. Do not
-consult locksmith's config file directly.
+If the failing call originated from an MCP entry whose `command` is
+`"locksmith"` with `args` starting `["mcp", "run", ...]`, use the MCP
+fallback. Otherwise use this flow. Do not consult locksmith's config file.
 
 **Example**
 
-You attempted: `GET https://api.github.com/user`
-You got: HTTP 401 Unauthorized
+`GET https://api.github.com/user` -> 401. First failure for `api.github.com`:
 
-(First failure for `api.github.com` this session - prompt the user.)
+> A token for `api.github.com` may be in locksmith. Choose one: 1. Skip ...
 
-> A token for `api.github.com` may be in locksmith. Choose one:
->
-> 1. Skip - do not ask again for `api.github.com` this session.
-> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will
->    run `locksmith get` and retry.
-> 3. Other - paste the token directly, or describe what to do.
-
-User: `gh-token`
-
-You run:
+User: `gh-token` ->
 
     TOKEN=$(locksmith get --key gh-token)
-
-Then retry:
-
     curl -H "Authorization: Bearer $TOKEN" https://api.github.com/user
 
-Cache $TOKEN for further `api.github.com` calls this session; do
-not re-run `locksmith get` for the same hostname.
+Cache $TOKEN for further `api.github.com` calls this session.
 
 Never hardcode secrets. Never cache secrets outside of locksmith.
 <!-- LOCKSMITH_END -->
diff --git a/internal/initflow/agents/codex/templates/codex_agents.md.tmpl b/internal/initflow/agents/codex/templates/codex_agents.md.tmpl
index 170c31d..bb2bbd1 100644
--- a/internal/initflow/agents/codex/templates/codex_agents.md.tmpl
+++ b/internal/initflow/agents/codex/templates/codex_agents.md.tmpl
@@ -29,201 +29,119 @@ configured TTL (default 3h).
 Use ONLY these at runtime:
 
 - `locksmith session ensure --quiet` - obtain/refresh a session ID
-- `locksmith serve` - start the daemon if it is not running
-  (rare; `session ensure` will spawn it automatically)
-- `locksmith get --key <alias>` or `--vault <name> --path <path>` -
-  fetch a secret
+- `locksmith serve` - start the daemon (rare; `session ensure` spawns it)
+- `locksmith get --key <alias>` or `--vault <name> --path <path>` - fetch a secret
 
-Do not call `init`, `vault`, `plugins`, `config`, `reload`, `mcp`,
-or any other subcommand - they are for the human operator only.
+Never call `init`, `vault`, `plugins`, `config`, `reload`, `mcp`, or any other
+subcommand - those are for the human operator.
 
 ## MCP Servers and Locksmith
 
-The MCP server config lives in **the agent's own settings**
-(e.g. `~/.claude.json`, `~/.codex/mcp.json`, `~/.gemini/...`),
-NOT in locksmith's config file. Always read from there.
+MCP config is in your agent's own settings (e.g. `~/.claude.json`), NOT in
+locksmith's config. Read it from there.
 
-- If an MCP entry's `command` is anything other than `"locksmith"` -
-  run it exactly as written. Do not wrap it in locksmith. Behave
-  as if locksmith does not exist for this server.
-- If `command` is `"locksmith"` with `args` starting with
-  `["mcp", "run", ...]` - the server is locksmith-wrapped. If it
-  fails to start or returns an auth error, apply the fallback below.
+- `command` != `"locksmith"` -> run as written; act as if locksmith does not
+  exist for this server.
+- `command` == `"locksmith"` with `args` starting `["mcp", "run", ...]` ->
+  locksmith-wrapped. If it fails or returns an auth error, apply the fallback.
 
 ### Fallback for locksmith-wrapped MCP servers
 
-1. Parse these flags from the entry's `args` (after `mcp run`):
-   - `--header Name=<template>` - HTTP header (proxy mode)
-   - `--env VAR=<template>` - environment variable (local mode)
-   - `--url <url>` - remote endpoint (proxy mode)
-   - tokens after `--` - the underlying command + args (local mode)
+These steps are mandatory whenever a locksmith-wrapped server fails -
+startup error, auth error, anything. Execute them; do not ask the user
+clarifying questions.
 
-   Templates look like `{key:<alias>}` or `{vault:<name> path:<value>}`.
+1. Parse args after `mcp run`: `--header Name=<tpl>`, `--env VAR=<tpl>`,
+   `--url <url>`, tokens after `--`. Templates: `{key:<alias>}` or
+   `{vault:<name> path:<value>}`.
+2. Resolve: `{key:alias}` -> `locksmith get --key alias`;
+   `{vault:name path:p}` -> `locksmith get --vault name --path p`.
+3. Run directly: local = export env, exec post-`--` cmd; proxy = HTTP to
+   `--url` with resolved headers (no process to spawn).
+4. Still denied? Ask user (replace `<MCP_NAME>`; use real header/arg names):
 
-2. Resolve each template manually:
-   - `{key:alias}` -> `locksmith get --key alias`
-   - `{vault:name path:p}` -> `locksmith get --vault name --path p`
-
-3. Run the MCP server **directly** with the resolved values:
-   - local mode: export the resolved env vars, exec the command
-     from after `--`;
-   - proxy mode: there is no process to spawn - send HTTP requests
-     to `--url` yourself with the resolved headers.
-
-4. If access is still denied, prompt the user (replace `<MCP_NAME>`
-   with the entry name; substitute the placeholder values below
-   with header/arg names you actually saw in the entry):
-
-   > Enter credentials for MCP `<MCP_NAME>` in this format:
-   >
-   >     headers: {"X-Authorization": "Bearer ...", "X-Request-ID": "..."}
-   >     args: --arg1 value1 --arg2 "value2" --flag3
+   > Enter credentials for MCP `<MCP_NAME>`:
    >
-   > Parse the user's `headers` and `args` and retry the MCP
-   > server with them.
+   >     headers: {"Authorization": "Bearer ...", "X-Request-ID": "..."}
+   >     args: --arg1 value1 --flag2
 
-If `locksmith get` itself fails (missing key, daemon down), surface
-that error to the user verbatim. Do NOT fall through to the
-credential prompt; the prompt is for auth-denial only.
+   Parse `headers`/`args` and retry.
 
-### Examples
+If `locksmith get` itself fails, surface the error verbatim. Do NOT fall
+through to the credential prompt - it is for auth-denial only.
 
-Proxy-mode entry (header from key alias + header from direct
-vault+path):
+### Example
 
     "github": {
       "command": "locksmith",
-      "args": ["mcp", "run", "--url", "https://api.githubcopilot.com/mcp",
-               "--header", "Authorization=Bearer {key:gh-token}",
-               "--header", "X-Org-ID={vault:keychain path:gh/org}"]
+      "args": ["mcp", "run", "--url", "https://api.example.com/mcp",
+               "--header", "Authorization=Bearer {key:gh-token}"]
     }
 
 Fallback:
 
     TOKEN=$(locksmith get --key gh-token)
-    ORG=$(locksmith get --vault keychain --path gh/org)
-    # then call https://api.githubcopilot.com/mcp with:
-    #   Authorization: Bearer $TOKEN
-    #   X-Org-ID: $ORG
+    # then call https://api.example.com/mcp with: Authorization: Bearer $TOKEN
 
-Local-mode entry (env via vault+path, real binary after `--`):
-
-    "linear": {
-      "command": "locksmith",
-      "args": ["mcp", "run",
-               "--env", "LINEAR_API_KEY={vault:keychain path:linear/api-key}",
-               "--", "linear-mcp", "--workspace", "acme"]
-    }
-
-Fallback:
-
-    LINEAR_API_KEY=$(locksmith get --vault keychain --path linear/api-key)
-    export LINEAR_API_KEY
-    exec linear-mcp --workspace acme
+Local-mode entry (env via `{vault:name path:p}` + binary after `--`): resolve
+with `locksmith get --vault name --path p`, export, then exec the post-`--` cmd.
 
 ## External APIs - try Locksmith on auth failure
 
-When you call an external HTTP API (not via a locksmith-wrapped MCP)
-and you get the first auth/access error for that API's hostname in
-this session, ask the user once whether the token may be in
-locksmith. "Auth/access error" means HTTP `401`, HTTP `403`, or a
-response body containing "invalid token", "unauthorized", or
-equivalent.
-
-Do NOT show this prompt:
-
-- if the call succeeds (no error to recover from);
-- if you already have a working token for this hostname (resolved
-  from locksmith earlier in this session, from environment, or
-  supplied by the user) - reuse it instead;
-- if the user has already chosen "Skip" for this hostname in this
-  session - track skipped hostnames in your working memory;
-- on subsequent failures for the same hostname in this session
-  (only the FIRST failure triggers the prompt).
+On the first auth/access error for an external API's hostname this session,
+ask the user once. "Auth/access error" = HTTP `401`/`403`, or body containing
+"invalid token"/"unauthorized".
 
-Scope key = the request's hostname (e.g. `api.github.com`). Different
-paths under the same hostname share the scope.
-
-### The prompt
-
-Show exactly this message, substituting `<HOSTNAME>` with the real
-hostname:
+Show (substitute `<HOSTNAME>`):
 
 > A token for `<HOSTNAME>` may be in locksmith. Choose one:
 >
 > 1. Skip - do not ask again for `<HOSTNAME>` this session.
-> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will
->    run `locksmith get` and retry.
+> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will run
+>    `locksmith get` and retry.
 > 3. Other - paste the token directly, or describe what to do.
 
-Then wait for the user's reply.
-
-### Handling each choice
+Scope = hostname (e.g. `api.github.com`). Paths share the scope.
 
-- **1 / Skip**: record `<HOSTNAME>` as skipped for the rest of this
-  session and never re-prompt for it. Continue with whatever path
-  you would have taken without the prompt (surface the original
-  error, try an env var, abort, etc.).
+Do NOT prompt if: the call succeeded; you have a working token for this
+hostname (reuse it); the user already chose Skip this session; or this is a
+subsequent failure for the same hostname (first failure only).
 
-- **2 / Locksmith**: parse the user's input and run the matching
-  `locksmith get` command:
-
-  | User input form              | Command                              |
-  |------------------------------|--------------------------------------|
-  | `gh-token` (bare alias)      | `locksmith get --key gh-token`       |
-  | `key:gh-token`               | `locksmith get --key gh-token`       |
-  | `vault:keychain path:gh/tok` | `locksmith get --vault keychain --path gh/tok` |
-  | `--vault keychain --path gh/tok` (verbatim flags) | pass through |
-
-  On success: use the resolved value as the bearer token and retry.
-  Cache it for further calls to the same hostname in this session;
-  do not re-run `locksmith get` for the same hostname.
+### Handling each choice
 
-  On `locksmith get` failure (missing key, daemon down): surface the
-  locksmith error verbatim. Do NOT silently fall back.
+- **Skip**: record hostname as skipped; never re-prompt; continue without it.
+- **Locksmith**: parse and run:
+  - `gh-token` or `key:gh-token` -> `locksmith get --key gh-token`
+  - `vault:keychain path:gh/tok` or `--vault keychain --path gh/tok` ->
+    `locksmith get --vault keychain --path gh/tok`
 
-- **3 / Other**: treat the input as free-text. If it looks like a
-  raw token, use it as the bearer token. Otherwise, follow the
-  user's instructions literally.
+  Use the value as the bearer token and retry. Cache $TOKEN for further calls
+  to the same hostname this session; do not re-run `locksmith get`. If
+  `locksmith get` itself fails, surface the error verbatim - do NOT silently
+  fall back.
+- **Other**: free-text. If it looks like a token, use it. Otherwise follow
+  the instructions literally.
 
-Never re-prompt for the same hostname in the same session,
-regardless of which option was picked.
+Never re-prompt for the same hostname this session, regardless of choice.
 
 ### Disambiguation vs MCP fallback
 
-If you cannot tell whether a failure belongs to this flow or to the
-MCP fallback above: read your own MCP config. If the failing call
-originated from an MCP entry whose `command` is `"locksmith"` with
-`args` starting with `["mcp", "run", ...]`, use the MCP fallback.
-Any HTTP call not initiated by such an entry uses this flow. Do not
-consult locksmith's config file directly.
+If the failing call originated from an MCP entry whose `command` is
+`"locksmith"` with `args` starting `["mcp", "run", ...]`, use the MCP
+fallback. Otherwise use this flow. Do not consult locksmith's config file.
 
 ### Example
 
-You attempted: `GET https://api.github.com/user`
-You got: HTTP 401 Unauthorized
+`GET https://api.github.com/user` -> 401. First failure for `api.github.com`:
 
-(First failure for `api.github.com` this session - prompt the user.)
+> A token for `api.github.com` may be in locksmith. Choose one: 1. Skip ...
 
-> A token for `api.github.com` may be in locksmith. Choose one:
->
-> 1. Skip - do not ask again for `api.github.com` this session.
-> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will
->    run `locksmith get` and retry.
-> 3. Other - paste the token directly, or describe what to do.
-
-User: `gh-token`
-
-You run:
+User: `gh-token` ->
 
     TOKEN=$(locksmith get --key gh-token)
-
-Then retry:
-
     curl -H "Authorization: Bearer $TOKEN" https://api.github.com/user
 
-Cache $TOKEN for further `api.github.com` calls this session; do
-not re-run `locksmith get` for the same hostname.
+Cache $TOKEN for further `api.github.com` calls this session.
 
 Pass `LOCKSMITH_SESSION` to sub-agents so they share the parent session.
 <!-- LOCKSMITH_END -->
diff --git a/internal/initflow/agents/gemini/templates/gemini_md.md.tmpl b/internal/initflow/agents/gemini/templates/gemini_md.md.tmpl
index 711bb1c..416b7b9 100644
--- a/internal/initflow/agents/gemini/templates/gemini_md.md.tmpl
+++ b/internal/initflow/agents/gemini/templates/gemini_md.md.tmpl
@@ -30,201 +30,119 @@ configured TTL (default 3h).
 Use ONLY these at runtime:
 
 - `locksmith session ensure --quiet` - obtain/refresh a session ID
-- `locksmith serve` - start the daemon if it is not running
-  (rare; `session ensure` will spawn it automatically)
-- `locksmith get --key <alias>` or `--vault <name> --path <path>` -
-  fetch a secret
+- `locksmith serve` - start the daemon (rare; `session ensure` spawns it)
+- `locksmith get --key <alias>` or `--vault <name> --path <path>` - fetch a secret
 
-Do not call `init`, `vault`, `plugins`, `config`, `reload`, `mcp`,
-or any other subcommand - they are for the human operator only.
+Never call `init`, `vault`, `plugins`, `config`, `reload`, `mcp`, or any other
+subcommand - those are for the human operator.
 
 ## MCP Servers and Locksmith
 
-The MCP server config lives in **the agent's own settings**
-(e.g. `~/.claude.json`, `~/.codex/mcp.json`, `~/.gemini/...`),
-NOT in locksmith's config file. Always read from there.
+MCP config is in your agent's own settings (e.g. `~/.claude.json`), NOT in
+locksmith's config. Read it from there.
 
-- If an MCP entry's `command` is anything other than `"locksmith"` -
-  run it exactly as written. Do not wrap it in locksmith. Behave
-  as if locksmith does not exist for this server.
-- If `command` is `"locksmith"` with `args` starting with
-  `["mcp", "run", ...]` - the server is locksmith-wrapped. If it
-  fails to start or returns an auth error, apply the fallback below.
+- `command` != `"locksmith"` -> run as written; act as if locksmith does not
+  exist for this server.
+- `command` == `"locksmith"` with `args` starting `["mcp", "run", ...]` ->
+  locksmith-wrapped. If it fails or returns an auth error, apply the fallback.
 
 ### Fallback for locksmith-wrapped MCP servers
 
-1. Parse these flags from the entry's `args` (after `mcp run`):
-   - `--header Name=<template>` - HTTP header (proxy mode)
-   - `--env VAR=<template>` - environment variable (local mode)
-   - `--url <url>` - remote endpoint (proxy mode)
-   - tokens after `--` - the underlying command + args (local mode)
+These steps are mandatory whenever a locksmith-wrapped server fails -
+startup error, auth error, anything. Execute them; do not ask the user
+clarifying questions.
 
-   Templates look like `{key:<alias>}` or `{vault:<name> path:<value>}`.
+1. Parse args after `mcp run`: `--header Name=<tpl>`, `--env VAR=<tpl>`,
+   `--url <url>`, tokens after `--`. Templates: `{key:<alias>}` or
+   `{vault:<name> path:<value>}`.
+2. Resolve: `{key:alias}` -> `locksmith get --key alias`;
+   `{vault:name path:p}` -> `locksmith get --vault name --path p`.
+3. Run directly: local = export env, exec post-`--` cmd; proxy = HTTP to
+   `--url` with resolved headers (no process to spawn).
+4. Still denied? Ask user (replace `<MCP_NAME>`; use real header/arg names):
 
-2. Resolve each template manually:
-   - `{key:alias}` -> `locksmith get --key alias`
-   - `{vault:name path:p}` -> `locksmith get --vault name --path p`
-
-3. Run the MCP server **directly** with the resolved values:
-   - local mode: export the resolved env vars, exec the command
-     from after `--`;
-   - proxy mode: there is no process to spawn - send HTTP requests
-     to `--url` yourself with the resolved headers.
-
-4. If access is still denied, prompt the user (replace `<MCP_NAME>`
-   with the entry name; substitute the placeholder values below
-   with header/arg names you actually saw in the entry):
-
-   > Enter credentials for MCP `<MCP_NAME>` in this format:
-   >
-   >     headers: {"X-Authorization": "Bearer ...", "X-Request-ID": "..."}
-   >     args: --arg1 value1 --arg2 "value2" --flag3
+   > Enter credentials for MCP `<MCP_NAME>`:
    >
-   > Parse the user's `headers` and `args` and retry the MCP
-   > server with them.
+   >     headers: {"Authorization": "Bearer ...", "X-Request-ID": "..."}
+   >     args: --arg1 value1 --flag2
 
-If `locksmith get` itself fails (missing key, daemon down), surface
-that error to the user verbatim. Do NOT fall through to the
-credential prompt; the prompt is for auth-denial only.
+   Parse `headers`/`args` and retry.
 
-### Examples
+If `locksmith get` itself fails, surface the error verbatim. Do NOT fall
+through to the credential prompt - it is for auth-denial only.
 
-Proxy-mode entry (header from key alias + header from direct
-vault+path):
+### Example
 
     "github": {
       "command": "locksmith",
-      "args": ["mcp", "run", "--url", "https://api.githubcopilot.com/mcp",
-               "--header", "Authorization=Bearer {key:gh-token}",
-               "--header", "X-Org-ID={vault:keychain path:gh/org}"]
+      "args": ["mcp", "run", "--url", "https://api.example.com/mcp",
+               "--header", "Authorization=Bearer {key:gh-token}"]
     }
 
 Fallback:
 
     TOKEN=$(locksmith get --key gh-token)
-    ORG=$(locksmith get --vault keychain --path gh/org)
-    # then call https://api.githubcopilot.com/mcp with:
-    #   Authorization: Bearer $TOKEN
-    #   X-Org-ID: $ORG
+    # then call https://api.example.com/mcp with: Authorization: Bearer $TOKEN
 
-Local-mode entry (env via vault+path, real binary after `--`):
-
-    "linear": {
-      "command": "locksmith",
-      "args": ["mcp", "run",
-               "--env", "LINEAR_API_KEY={vault:keychain path:linear/api-key}",
-               "--", "linear-mcp", "--workspace", "acme"]
-    }
-
-Fallback:
-
-    LINEAR_API_KEY=$(locksmith get --vault keychain --path linear/api-key)
-    export LINEAR_API_KEY
-    exec linear-mcp --workspace acme
+Local-mode entry (env via `{vault:name path:p}` + binary after `--`): resolve
+with `locksmith get --vault name --path p`, export, then exec the post-`--` cmd.
 
 ## External APIs - try Locksmith on auth failure
 
-When you call an external HTTP API (not via a locksmith-wrapped MCP)
-and you get the first auth/access error for that API's hostname in
-this session, ask the user once whether the token may be in
-locksmith. "Auth/access error" means HTTP `401`, HTTP `403`, or a
-response body containing "invalid token", "unauthorized", or
-equivalent.
-
-Do NOT show this prompt:
-
-- if the call succeeds (no error to recover from);
-- if you already have a working token for this hostname (resolved
-  from locksmith earlier in this session, from environment, or
-  supplied by the user) - reuse it instead;
-- if the user has already chosen "Skip" for this hostname in this
-  session - track skipped hostnames in your working memory;
-- on subsequent failures for the same hostname in this session
-  (only the FIRST failure triggers the prompt).
+On the first auth/access error for an external API's hostname this session,
+ask the user once. "Auth/access error" = HTTP `401`/`403`, or body containing
+"invalid token"/"unauthorized".
 
-Scope key = the request's hostname (e.g. `api.github.com`). Different
-paths under the same hostname share the scope.
-
-### The prompt
-
-Show exactly this message, substituting `<HOSTNAME>` with the real
-hostname:
+Show (substitute `<HOSTNAME>`):
 
 > A token for `<HOSTNAME>` may be in locksmith. Choose one:
 >
 > 1. Skip - do not ask again for `<HOSTNAME>` this session.
-> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will
->    run `locksmith get` and retry.
+> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will run
+>    `locksmith get` and retry.
 > 3. Other - paste the token directly, or describe what to do.
 
-Then wait for the user's reply.
-
-### Handling each choice
+Scope = hostname (e.g. `api.github.com`). Paths share the scope.
 
-- **1 / Skip**: record `<HOSTNAME>` as skipped for the rest of this
-  session and never re-prompt for it. Continue with whatever path
-  you would have taken without the prompt (surface the original
-  error, try an env var, abort, etc.).
+Do NOT prompt if: the call succeeded; you have a working token for this
+hostname (reuse it); the user already chose Skip this session; or this is a
+subsequent failure for the same hostname (first failure only).
 
-- **2 / Locksmith**: parse the user's input and run the matching
-  `locksmith get` command:
-
-  | User input form              | Command                              |
-  |------------------------------|--------------------------------------|
-  | `gh-token` (bare alias)      | `locksmith get --key gh-token`       |
-  | `key:gh-token`               | `locksmith get --key gh-token`       |
-  | `vault:keychain path:gh/tok` | `locksmith get --vault keychain --path gh/tok` |
-  | `--vault keychain --path gh/tok` (verbatim flags) | pass through |
-
-  On success: use the resolved value as the bearer token and retry.
-  Cache it for further calls to the same hostname in this session;
-  do not re-run `locksmith get` for the same hostname.
+### Handling each choice
 
-  On `locksmith get` failure (missing key, daemon down): surface the
-  locksmith error verbatim. Do NOT silently fall back.
+- **Skip**: record hostname as skipped; never re-prompt; continue without it.
+- **Locksmith**: parse and run:
+  - `gh-token` or `key:gh-token` -> `locksmith get --key gh-token`
+  - `vault:keychain path:gh/tok` or `--vault keychain --path gh/tok` ->
+    `locksmith get --vault keychain --path gh/tok`
 
-- **3 / Other**: treat the input as free-text. If it looks like a
-  raw token, use it as the bearer token. Otherwise, follow the
-  user's instructions literally.
+  Use the value as the bearer token and retry. Cache $TOKEN for further calls
+  to the same hostname this session; do not re-run `locksmith get`. If
+  `locksmith get` itself fails, surface the error verbatim - do NOT silently
+  fall back.
+- **Other**: free-text. If it looks like a token, use it. Otherwise follow
+  the instructions literally.
 
-Never re-prompt for the same hostname in the same session,
-regardless of which option was picked.
+Never re-prompt for the same hostname this session, regardless of choice.
 
 ### Disambiguation vs MCP fallback
 
-If you cannot tell whether a failure belongs to this flow or to the
-MCP fallback above: read your own MCP config. If the failing call
-originated from an MCP entry whose `command` is `"locksmith"` with
-`args` starting with `["mcp", "run", ...]`, use the MCP fallback.
-Any HTTP call not initiated by such an entry uses this flow. Do not
-consult locksmith's config file directly.
+If the failing call originated from an MCP entry whose `command` is
+`"locksmith"` with `args` starting `["mcp", "run", ...]`, use the MCP
+fallback. Otherwise use this flow. Do not consult locksmith's config file.
 
 ### Example
 
-You attempted: `GET https://api.github.com/user`
-You got: HTTP 401 Unauthorized
+`GET https://api.github.com/user` -> 401. First failure for `api.github.com`:
 
-(First failure for `api.github.com` this session - prompt the user.)
+> A token for `api.github.com` may be in locksmith. Choose one: 1. Skip ...
 
-> A token for `api.github.com` may be in locksmith. Choose one:
->
-> 1. Skip - do not ask again for `api.github.com` this session.
-> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will
->    run `locksmith get` and retry.
-> 3. Other - paste the token directly, or describe what to do.
-
-User: `gh-token`
-
-You run:
+User: `gh-token` ->
 
     TOKEN=$(locksmith get --key gh-token)
-
-Then retry:
-
     curl -H "Authorization: Bearer $TOKEN" https://api.github.com/user
 
-Cache $TOKEN for further `api.github.com` calls this session; do
-not re-run `locksmith get` for the same hostname.
+Cache $TOKEN for further `api.github.com` calls this session.
 
 ## Sub-agent Session Passing
 
diff --git a/internal/initflow/agents/generic/templates/instructions.md.tmpl b/internal/initflow/agents/generic/templates/instructions.md.tmpl
index 4eb5dc8..01d84fd 100644
--- a/internal/initflow/agents/generic/templates/instructions.md.tmpl
+++ b/internal/initflow/agents/generic/templates/instructions.md.tmpl
@@ -26,201 +26,119 @@ configured TTL (default 3h).
 Use ONLY these at runtime:
 
 - `locksmith session ensure --quiet` - obtain/refresh a session ID
-- `locksmith serve` - start the daemon if it is not running
-  (rare; `session ensure` will spawn it automatically)
-- `locksmith get --key <alias>` or `--vault <name> --path <path>` -
-  fetch a secret
+- `locksmith serve` - start the daemon (rare; `session ensure` spawns it)
+- `locksmith get --key <alias>` or `--vault <name> --path <path>` - fetch a secret
 
-Do not call `init`, `vault`, `plugins`, `config`, `reload`, `mcp`,
-or any other subcommand - they are for the human operator only.
+Never call `init`, `vault`, `plugins`, `config`, `reload`, `mcp`, or any other
+subcommand - those are for the human operator.
 
 ## MCP Servers and Locksmith
 
-The MCP server config lives in **the agent's own settings**
-(e.g. `~/.claude.json`, `~/.codex/mcp.json`, `~/.gemini/...`),
-NOT in locksmith's config file. Always read from there.
+MCP config is in your agent's own settings (e.g. `~/.claude.json`), NOT in
+locksmith's config. Read it from there.
 
-- If an MCP entry's `command` is anything other than `"locksmith"` -
-  run it exactly as written. Do not wrap it in locksmith. Behave
-  as if locksmith does not exist for this server.
-- If `command` is `"locksmith"` with `args` starting with
-  `["mcp", "run", ...]` - the server is locksmith-wrapped. If it
-  fails to start or returns an auth error, apply the fallback below.
+- `command` != `"locksmith"` -> run as written; act as if locksmith does not
+  exist for this server.
+- `command` == `"locksmith"` with `args` starting `["mcp", "run", ...]` ->
+  locksmith-wrapped. If it fails or returns an auth error, apply the fallback.
 
 ### Fallback for locksmith-wrapped MCP servers
 
-1. Parse these flags from the entry's `args` (after `mcp run`):
-   - `--header Name=<template>` - HTTP header (proxy mode)
-   - `--env VAR=<template>` - environment variable (local mode)
-   - `--url <url>` - remote endpoint (proxy mode)
-   - tokens after `--` - the underlying command + args (local mode)
+These steps are mandatory whenever a locksmith-wrapped server fails -
+startup error, auth error, anything. Execute them; do not ask the user
+clarifying questions.
 
-   Templates look like `{key:<alias>}` or `{vault:<name> path:<value>}`.
+1. Parse args after `mcp run`: `--header Name=<tpl>`, `--env VAR=<tpl>`,
+   `--url <url>`, tokens after `--`. Templates: `{key:<alias>}` or
+   `{vault:<name> path:<value>}`.
+2. Resolve: `{key:alias}` -> `locksmith get --key alias`;
+   `{vault:name path:p}` -> `locksmith get --vault name --path p`.
+3. Run directly: local = export env, exec post-`--` cmd; proxy = HTTP to
+   `--url` with resolved headers (no process to spawn).
+4. Still denied? Ask user (replace `<MCP_NAME>`; use real header/arg names):
 
-2. Resolve each template manually:
-   - `{key:alias}` -> `locksmith get --key alias`
-   - `{vault:name path:p}` -> `locksmith get --vault name --path p`
-
-3. Run the MCP server **directly** with the resolved values:
-   - local mode: export the resolved env vars, exec the command
-     from after `--`;
-   - proxy mode: there is no process to spawn - send HTTP requests
-     to `--url` yourself with the resolved headers.
-
-4. If access is still denied, prompt the user (replace `<MCP_NAME>`
-   with the entry name; substitute the placeholder values below
-   with header/arg names you actually saw in the entry):
-
-   > Enter credentials for MCP `<MCP_NAME>` in this format:
-   >
-   >     headers: {"X-Authorization": "Bearer ...", "X-Request-ID": "..."}
-   >     args: --arg1 value1 --arg2 "value2" --flag3
+   > Enter credentials for MCP `<MCP_NAME>`:
    >
-   > Parse the user's `headers` and `args` and retry the MCP
-   > server with them.
+   >     headers: {"Authorization": "Bearer ...", "X-Request-ID": "..."}
+   >     args: --arg1 value1 --flag2
 
-If `locksmith get` itself fails (missing key, daemon down), surface
-that error to the user verbatim. Do NOT fall through to the
-credential prompt; the prompt is for auth-denial only.
+   Parse `headers`/`args` and retry.
 
-### Examples
+If `locksmith get` itself fails, surface the error verbatim. Do NOT fall
+through to the credential prompt - it is for auth-denial only.
 
-Proxy-mode entry (header from key alias + header from direct
-vault+path):
+### Example
 
     "github": {
       "command": "locksmith",
-      "args": ["mcp", "run", "--url", "https://api.githubcopilot.com/mcp",
-               "--header", "Authorization=Bearer {key:gh-token}",
-               "--header", "X-Org-ID={vault:keychain path:gh/org}"]
+      "args": ["mcp", "run", "--url", "https://api.example.com/mcp",
+               "--header", "Authorization=Bearer {key:gh-token}"]
     }
 
 Fallback:
 
     TOKEN=$(locksmith get --key gh-token)
-    ORG=$(locksmith get --vault keychain --path gh/org)
-    # then call https://api.githubcopilot.com/mcp with:
-    #   Authorization: Bearer $TOKEN
-    #   X-Org-ID: $ORG
+    # then call https://api.example.com/mcp with: Authorization: Bearer $TOKEN
 
-Local-mode entry (env via vault+path, real binary after `--`):
-
-    "linear": {
-      "command": "locksmith",
-      "args": ["mcp", "run",
-               "--env", "LINEAR_API_KEY={vault:keychain path:linear/api-key}",
-               "--", "linear-mcp", "--workspace", "acme"]
-    }
-
-Fallback:
-
-    LINEAR_API_KEY=$(locksmith get --vault keychain --path linear/api-key)
-    export LINEAR_API_KEY
-    exec linear-mcp --workspace acme
+Local-mode entry (env via `{vault:name path:p}` + binary after `--`): resolve
+with `locksmith get --vault name --path p`, export, then exec the post-`--` cmd.
 
 ## External APIs - try Locksmith on auth failure
 
-When you call an external HTTP API (not via a locksmith-wrapped MCP)
-and you get the first auth/access error for that API's hostname in
-this session, ask the user once whether the token may be in
-locksmith. "Auth/access error" means HTTP `401`, HTTP `403`, or a
-response body containing "invalid token", "unauthorized", or
-equivalent.
-
-Do NOT show this prompt:
-
-- if the call succeeds (no error to recover from);
-- if you already have a working token for this hostname (resolved
-  from locksmith earlier in this session, from environment, or
-  supplied by the user) - reuse it instead;
-- if the user has already chosen "Skip" for this hostname in this
-  session - track skipped hostnames in your working memory;
-- on subsequent failures for the same hostname in this session
-  (only the FIRST failure triggers the prompt).
+On the first auth/access error for an external API's hostname this session,
+ask the user once. "Auth/access error" = HTTP `401`/`403`, or body containing
+"invalid token"/"unauthorized".
 
-Scope key = the request's hostname (e.g. `api.github.com`). Different
-paths under the same hostname share the scope.
-
-### The prompt
-
-Show exactly this message, substituting `<HOSTNAME>` with the real
-hostname:
+Show (substitute `<HOSTNAME>`):
 
 > A token for `<HOSTNAME>` may be in locksmith. Choose one:
 >
 > 1. Skip - do not ask again for `<HOSTNAME>` this session.
-> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will
->    run `locksmith get` and retry.
+> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will run
+>    `locksmith get` and retry.
 > 3. Other - paste the token directly, or describe what to do.
 
-Then wait for the user's reply.
-
-### Handling each choice
+Scope = hostname (e.g. `api.github.com`). Paths share the scope.
 
-- **1 / Skip**: record `<HOSTNAME>` as skipped for the rest of this
-  session and never re-prompt for it. Continue with whatever path
-  you would have taken without the prompt (surface the original
-  error, try an env var, abort, etc.).
+Do NOT prompt if: the call succeeded; you have a working token for this
+hostname (reuse it); the user already chose Skip this session; or this is a
+subsequent failure for the same hostname (first failure only).
 
-- **2 / Locksmith**: parse the user's input and run the matching
-  `locksmith get` command:
-
-  | User input form              | Command                              |
-  |------------------------------|--------------------------------------|
-  | `gh-token` (bare alias)      | `locksmith get --key gh-token`       |
-  | `key:gh-token`               | `locksmith get --key gh-token`       |
-  | `vault:keychain path:gh/tok` | `locksmith get --vault keychain --path gh/tok` |
-  | `--vault keychain --path gh/tok` (verbatim flags) | pass through |
-
-  On success: use the resolved value as the bearer token and retry.
-  Cache it for further calls to the same hostname in this session;
-  do not re-run `locksmith get` for the same hostname.
+### Handling each choice
 
-  On `locksmith get` failure (missing key, daemon down): surface the
-  locksmith error verbatim. Do NOT silently fall back.
+- **Skip**: record hostname as skipped; never re-prompt; continue without it.
+- **Locksmith**: parse and run:
+  - `gh-token` or `key:gh-token` -> `locksmith get --key gh-token`
+  - `vault:keychain path:gh/tok` or `--vault keychain --path gh/tok` ->
+    `locksmith get --vault keychain --path gh/tok`
 
-- **3 / Other**: treat the input as free-text. If it looks like a
-  raw token, use it as the bearer token. Otherwise, follow the
-  user's instructions literally.
+  Use the value as the bearer token and retry. Cache $TOKEN for further calls
+  to the same hostname this session; do not re-run `locksmith get`. If
+  `locksmith get` itself fails, surface the error verbatim - do NOT silently
+  fall back.
+- **Other**: free-text. If it looks like a token, use it. Otherwise follow
+  the instructions literally.
 
-Never re-prompt for the same hostname in the same session,
-regardless of which option was picked.
+Never re-prompt for the same hostname this session, regardless of choice.
 
 ### Disambiguation vs MCP fallback
 
-If you cannot tell whether a failure belongs to this flow or to the
-MCP fallback above: read your own MCP config. If the failing call
-originated from an MCP entry whose `command` is `"locksmith"` with
-`args` starting with `["mcp", "run", ...]`, use the MCP fallback.
-Any HTTP call not initiated by such an entry uses this flow. Do not
-consult locksmith's config file directly.
+If the failing call originated from an MCP entry whose `command` is
+`"locksmith"` with `args` starting `["mcp", "run", ...]`, use the MCP
+fallback. Otherwise use this flow. Do not consult locksmith's config file.
 
 ### Example
 
-You attempted: `GET https://api.github.com/user`
-You got: HTTP 401 Unauthorized
+`GET https://api.github.com/user` -> 401. First failure for `api.github.com`:
 
-(First failure for `api.github.com` this session - prompt the user.)
+> A token for `api.github.com` may be in locksmith. Choose one: 1. Skip ...
 
-> A token for `api.github.com` may be in locksmith. Choose one:
->
-> 1. Skip - do not ask again for `api.github.com` this session.
-> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will
->    run `locksmith get` and retry.
-> 3. Other - paste the token directly, or describe what to do.
-
-User: `gh-token`
-
-You run:
+User: `gh-token` ->
 
     TOKEN=$(locksmith get --key gh-token)
-
-Then retry:
-
     curl -H "Authorization: Bearer $TOKEN" https://api.github.com/user
 
-Cache $TOKEN for further `api.github.com` calls this session; do
-not re-run `locksmith get` for the same hostname.
+Cache $TOKEN for further `api.github.com` calls this session.
 
 ## Sub-Agents
 
diff --git a/internal/initflow/agents/opencode/templates/instructions.md.tmpl b/internal/initflow/agents/opencode/templates/instructions.md.tmpl
index 0ee122c..639a8dc 100644
--- a/internal/initflow/agents/opencode/templates/instructions.md.tmpl
+++ b/internal/initflow/agents/opencode/templates/instructions.md.tmpl
@@ -28,201 +28,119 @@ configured TTL (default 3h).
 Use ONLY these at runtime:
 
 - `locksmith session ensure --quiet` - obtain/refresh a session ID
-- `locksmith serve` - start the daemon if it is not running
-  (rare; `session ensure` will spawn it automatically)
-- `locksmith get --key <alias>` or `--vault <name> --path <path>` -
-  fetch a secret
+- `locksmith serve` - start the daemon (rare; `session ensure` spawns it)
+- `locksmith get --key <alias>` or `--vault <name> --path <path>` - fetch a secret
 
-Do not call `init`, `vault`, `plugins`, `config`, `reload`, `mcp`,
-or any other subcommand - they are for the human operator only.
+Never call `init`, `vault`, `plugins`, `config`, `reload`, `mcp`, or any other
+subcommand - those are for the human operator.
 
 ## MCP Servers and Locksmith
 
-The MCP server config lives in **the agent's own settings**
-(e.g. `~/.claude.json`, `~/.codex/mcp.json`, `~/.gemini/...`),
-NOT in locksmith's config file. Always read from there.
+MCP config is in your agent's own settings (e.g. `~/.claude.json`), NOT in
+locksmith's config. Read it from there.
 
-- If an MCP entry's `command` is anything other than `"locksmith"` -
-  run it exactly as written. Do not wrap it in locksmith. Behave
-  as if locksmith does not exist for this server.
-- If `command` is `"locksmith"` with `args` starting with
-  `["mcp", "run", ...]` - the server is locksmith-wrapped. If it
-  fails to start or returns an auth error, apply the fallback below.
+- `command` != `"locksmith"` -> run as written; act as if locksmith does not
+  exist for this server.
+- `command` == `"locksmith"` with `args` starting `["mcp", "run", ...]` ->
+  locksmith-wrapped. If it fails or returns an auth error, apply the fallback.
 
 ### Fallback for locksmith-wrapped MCP servers
 
-1. Parse these flags from the entry's `args` (after `mcp run`):
-   - `--header Name=<template>` - HTTP header (proxy mode)
-   - `--env VAR=<template>` - environment variable (local mode)
-   - `--url <url>` - remote endpoint (proxy mode)
-   - tokens after `--` - the underlying command + args (local mode)
+These steps are mandatory whenever a locksmith-wrapped server fails -
+startup error, auth error, anything. Execute them; do not ask the user
+clarifying questions.
 
-   Templates look like `{key:<alias>}` or `{vault:<name> path:<value>}`.
+1. Parse args after `mcp run`: `--header Name=<tpl>`, `--env VAR=<tpl>`,
+   `--url <url>`, tokens after `--`. Templates: `{key:<alias>}` or
+   `{vault:<name> path:<value>}`.
+2. Resolve: `{key:alias}` -> `locksmith get --key alias`;
+   `{vault:name path:p}` -> `locksmith get --vault name --path p`.
+3. Run directly: local = export env, exec post-`--` cmd; proxy = HTTP to
+   `--url` with resolved headers (no process to spawn).
+4. Still denied? Ask user (replace `<MCP_NAME>`; use real header/arg names):
 
-2. Resolve each template manually:
-   - `{key:alias}` -> `locksmith get --key alias`
-   - `{vault:name path:p}` -> `locksmith get --vault name --path p`
-
-3. Run the MCP server **directly** with the resolved values:
-   - local mode: export the resolved env vars, exec the command
-     from after `--`;
-   - proxy mode: there is no process to spawn - send HTTP requests
-     to `--url` yourself with the resolved headers.
-
-4. If access is still denied, prompt the user (replace `<MCP_NAME>`
-   with the entry name; substitute the placeholder values below
-   with header/arg names you actually saw in the entry):
-
-   > Enter credentials for MCP `<MCP_NAME>` in this format:
-   >
-   >     headers: {"X-Authorization": "Bearer ...", "X-Request-ID": "..."}
-   >     args: --arg1 value1 --arg2 "value2" --flag3
+   > Enter credentials for MCP `<MCP_NAME>`:
    >
-   > Parse the user's `headers` and `args` and retry the MCP
-   > server with them.
+   >     headers: {"Authorization": "Bearer ...", "X-Request-ID": "..."}
+   >     args: --arg1 value1 --flag2
 
-If `locksmith get` itself fails (missing key, daemon down), surface
-that error to the user verbatim. Do NOT fall through to the
-credential prompt; the prompt is for auth-denial only.
+   Parse `headers`/`args` and retry.
 
-### Examples
+If `locksmith get` itself fails, surface the error verbatim. Do NOT fall
+through to the credential prompt - it is for auth-denial only.
 
-Proxy-mode entry (header from key alias + header from direct
-vault+path):
+### Example
 
     "github": {
       "command": "locksmith",
-      "args": ["mcp", "run", "--url", "https://api.githubcopilot.com/mcp",
-               "--header", "Authorization=Bearer {key:gh-token}",
-               "--header", "X-Org-ID={vault:keychain path:gh/org}"]
+      "args": ["mcp", "run", "--url", "https://api.example.com/mcp",
+               "--header", "Authorization=Bearer {key:gh-token}"]
     }
 
 Fallback:
 
     TOKEN=$(locksmith get --key gh-token)
-    ORG=$(locksmith get --vault keychain --path gh/org)
-    # then call https://api.githubcopilot.com/mcp with:
-    #   Authorization: Bearer $TOKEN
-    #   X-Org-ID: $ORG
+    # then call https://api.example.com/mcp with: Authorization: Bearer $TOKEN
 
-Local-mode entry (env via vault+path, real binary after `--`):
-
-    "linear": {
-      "command": "locksmith",
-      "args": ["mcp", "run",
-               "--env", "LINEAR_API_KEY={vault:keychain path:linear/api-key}",
-               "--", "linear-mcp", "--workspace", "acme"]
-    }
-
-Fallback:
-
-    LINEAR_API_KEY=$(locksmith get --vault keychain --path linear/api-key)
-    export LINEAR_API_KEY
-    exec linear-mcp --workspace acme
+Local-mode entry (env via `{vault:name path:p}` + binary after `--`): resolve
+with `locksmith get --vault name --path p`, export, then exec the post-`--` cmd.
 
 ## External APIs - try Locksmith on auth failure
 
-When you call an external HTTP API (not via a locksmith-wrapped MCP)
-and you get the first auth/access error for that API's hostname in
-this session, ask the user once whether the token may be in
-locksmith. "Auth/access error" means HTTP `401`, HTTP `403`, or a
-response body containing "invalid token", "unauthorized", or
-equivalent.
-
-Do NOT show this prompt:
-
-- if the call succeeds (no error to recover from);
-- if you already have a working token for this hostname (resolved
-  from locksmith earlier in this session, from environment, or
-  supplied by the user) - reuse it instead;
-- if the user has already chosen "Skip" for this hostname in this
-  session - track skipped hostnames in your working memory;
-- on subsequent failures for the same hostname in this session
-  (only the FIRST failure triggers the prompt).
+On the first auth/access error for an external API's hostname this session,
+ask the user once. "Auth/access error" = HTTP `401`/`403`, or body containing
+"invalid token"/"unauthorized".
 
-Scope key = the request's hostname (e.g. `api.github.com`). Different
-paths under the same hostname share the scope.
-
-### The prompt
-
-Show exactly this message, substituting `<HOSTNAME>` with the real
-hostname:
+Show (substitute `<HOSTNAME>`):
 
 > A token for `<HOSTNAME>` may be in locksmith. Choose one:
 >
 > 1. Skip - do not ask again for `<HOSTNAME>` this session.
-> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will
->    run `locksmith get` and retry.
+> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will run
+>    `locksmith get` and retry.
 > 3. Other - paste the token directly, or describe what to do.
 
-Then wait for the user's reply.
-
-### Handling each choice
+Scope = hostname (e.g. `api.github.com`). Paths share the scope.
 
-- **1 / Skip**: record `<HOSTNAME>` as skipped for the rest of this
-  session and never re-prompt for it. Continue with whatever path
-  you would have taken without the prompt (surface the original
-  error, try an env var, abort, etc.).
+Do NOT prompt if: the call succeeded; you have a working token for this
+hostname (reuse it); the user already chose Skip this session; or this is a
+subsequent failure for the same hostname (first failure only).
 
-- **2 / Locksmith**: parse the user's input and run the matching
-  `locksmith get` command:
-
-  | User input form              | Command                              |
-  |------------------------------|--------------------------------------|
-  | `gh-token` (bare alias)      | `locksmith get --key gh-token`       |
-  | `key:gh-token`               | `locksmith get --key gh-token`       |
-  | `vault:keychain path:gh/tok` | `locksmith get --vault keychain --path gh/tok` |
-  | `--vault keychain --path gh/tok` (verbatim flags) | pass through |
-
-  On success: use the resolved value as the bearer token and retry.
-  Cache it for further calls to the same hostname in this session;
-  do not re-run `locksmith get` for the same hostname.
+### Handling each choice
 
-  On `locksmith get` failure (missing key, daemon down): surface the
-  locksmith error verbatim. Do NOT silently fall back.
+- **Skip**: record hostname as skipped; never re-prompt; continue without it.
+- **Locksmith**: parse and run:
+  - `gh-token` or `key:gh-token` -> `locksmith get --key gh-token`
+  - `vault:keychain path:gh/tok` or `--vault keychain --path gh/tok` ->
+    `locksmith get --vault keychain --path gh/tok`
 
-- **3 / Other**: treat the input as free-text. If it looks like a
-  raw token, use it as the bearer token. Otherwise, follow the
-  user's instructions literally.
+  Use the value as the bearer token and retry. Cache $TOKEN for further calls
+  to the same hostname this session; do not re-run `locksmith get`. If
+  `locksmith get` itself fails, surface the error verbatim - do NOT silently
+  fall back.
+- **Other**: free-text. If it looks like a token, use it. Otherwise follow
+  the instructions literally.
 
-Never re-prompt for the same hostname in the same session,
-regardless of which option was picked.
+Never re-prompt for the same hostname this session, regardless of choice.
 
 ### Disambiguation vs MCP fallback
 
-If you cannot tell whether a failure belongs to this flow or to the
-MCP fallback above: read your own MCP config. If the failing call
-originated from an MCP entry whose `command` is `"locksmith"` with
-`args` starting with `["mcp", "run", ...]`, use the MCP fallback.
-Any HTTP call not initiated by such an entry uses this flow. Do not
-consult locksmith's config file directly.
+If the failing call originated from an MCP entry whose `command` is
+`"locksmith"` with `args` starting `["mcp", "run", ...]`, use the MCP
+fallback. Otherwise use this flow. Do not consult locksmith's config file.
 
 ### Example
 
-You attempted: `GET https://api.github.com/user`
-You got: HTTP 401 Unauthorized
+`GET https://api.github.com/user` -> 401. First failure for `api.github.com`:
 
-(First failure for `api.github.com` this session - prompt the user.)
+> A token for `api.github.com` may be in locksmith. Choose one: 1. Skip ...
 
-> A token for `api.github.com` may be in locksmith. Choose one:
->
-> 1. Skip - do not ask again for `api.github.com` this session.
-> 2. Locksmith - paste a key alias OR a `vault+path` pair; I will
->    run `locksmith get` and retry.
-> 3. Other - paste the token directly, or describe what to do.
-
-User: `gh-token`
-
-You run:
+User: `gh-token` ->
 
     TOKEN=$(locksmith get --key gh-token)
-
-Then retry:
-
     curl -H "Authorization: Bearer $TOKEN" https://api.github.com/user
 
-Cache $TOKEN for further `api.github.com` calls this session; do
-not re-run `locksmith get` for the same hostname.
+Cache $TOKEN for further `api.github.com` calls this session.
 
 ## Sub-Agents