Sammorrowdrums/sandman readme rewrite (#34)

* docs: Sandman-esque README with tiered MCP progressive discovery

Rewrite README as a Neil Gaiman Sandman-inspired narrative introducing
the three tiers of progressive MCP tool discovery:

- The Skill Dealer (Tier 1): self-referential skill-gated tool visibility
- The Nuclear Football (Tier 2): shell-native CLI progressive discovery
- Codey C. Maude (Tier 3): sandboxed code mode for read-only tools

Add character and banner artwork in images/.

Technical details are accurate — the narrative weaves around the actual
architecture of skill registries, JSON-RPC tool-cli, and isolated-vm
V8 sandboxes.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* docs: replace ASCII art diagrams with mermaid

GitHub renders mermaid code blocks natively, so these diagrams will
display properly regardless of font or viewer. Replaces the three
ASCII box-drawing diagrams (skill flow, tool-cli architecture, and
overall tier architecture) with equivalent mermaid flowcharts and
sequence diagrams.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* docs: fix quote wording — add 'losing'

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* docs: note relationship to Anthropic tool search

Skill invocation pushes tools to the model (unsolicited tool definitions
via setActiveTools) rather than having the model pull them via search.
Both solve cache invalidation from large tool lists, but from opposite
directions.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* docs: add MCP server developer guide for progressive discovery

Guide for MCP server developers covering:
- skill:// resource format (frontmatter, allowed-tools, SKILL.md body)
- Registering skill resources with the MCP SDK
- Best practices for grouping tools into skills
- Tool annotations (readOnlyHint) and outputSchema for Code Mode
- Returning structuredContent for typed sandbox access
- Complete working example with all three tiers

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* docs: add npm badges and dual-lock framing to Nuclear Football

Add npm badges for mcpi, mcpi-ext, and tool-cli packages at the top.
Rework the Nuclear Football section to include the dual-lock metaphor:
agent holds the briefcase (reach), harness holds the launch authority
(safety). Every call routes through the harness for observability and
HITL gating.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* docs: update server guide with proposed spec format and references

Add the skills-as-groups proposal frontmatter format alongside the
current allowed-tools format. Document both with examples showing
metadata.io.modelcontextprotocol/tools (space-separated) vs
allowed-tools (YAML array). Add Further Reading section linking to
the spec proposal, progressive discovery docs, and mechanism docs.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* feat: support proposed spec frontmatter in skill discovery

Parse both frontmatter formats for skill tool declarations:
- Proposed: metadata.io.modelcontextprotocol/tools (space-separated)
- Current: allowed-tools (YAML array)

Prefers the proposed format when both are present. This enables
mcpi-ext to work with servers adopting the skills-as-groups proposal
(github/github-mcp-server#2465) while maintaining backward compat
with the current allowed-tools format.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* style: fix prettier formatting in server developer guide

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: SamMorrowDrums

README.md

@@ -1,5 +1,9 @@
 # mcpi-ext
 
+[![npm](https://img.shields.io/npm/v/@sammorrowdrums/mcpi)](https://www.npmjs.com/package/@sammorrowdrums/mcpi)
+[![npm](https://img.shields.io/npm/v/@sammorrowdrums/mcpi-ext)](https://www.npmjs.com/package/@sammorrowdrums/mcpi-ext)
+[![npm](https://img.shields.io/npm/v/@sammorrowdrums/tool-cli)](https://www.npmjs.com/package/@sammorrowdrums/tool-cli)
+
 > **Experimental.** This extension implements progressive MCP tool discovery via skills for [mcpi](https://github.com/SamMorrowDrums/mcpi) (an experimental pi fork). See the [skills-as-groups proposal](https://github.com/modelcontextprotocol/experimental-ext-grouping/pull/13) for the proposed MCP spec addition, and the [progressive tool discovery docs](https://github.com/SamMorrowDrums/mcpi/blob/main/docs/progressive-tool-discovery.md) for implementation details.
 
 ```sh
@@ -44,6 +48,8 @@ MCP servers ship `skill://` resources — SKILL.md files declaring which tools a
 
 When the model calls `load_skill`, the skill's instructions arrive and its tools are unblocked. The model discovers tools from the skill body and can call them immediately. The MCP server itself declares how its tools should be discovered.
 
+Anthropic's [tool search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool) solves a similar problem from the model side -- deferring tool loading to avoid cache invalidation from large tool lists. But where tool search has the model _pull_ tools on demand, skill invocation _pushes_ them: when `load_skill` fires, the harness sends unsolicited tool definitions to the model API alongside the skill instructions. The model doesn't search for tools -- the right tools arrive because the skill declared them.
+
 📖 [**How it works →**](docs/skills.md) — deferred gating, `defer_loading` provider support, `tool_call` hook enforcement.
 
 > _"What you do not need to know," said the Skill Dealer, shuffling the deck, "you will not be burdened with knowing."_
@@ -63,7 +69,9 @@ When the model calls `load_skill`, the skill's instructions arrive and its tools
 📖 [**How it works →**](docs/tool-cli.md) — architecture, progressive discovery, shell composability.
 📦 [**Standalone package →**](https://github.com/SamMorrowDrums/tool-cli) — `ToolProvider` interface, server, and implementor guidance for other languages.
 
-> _They pass the Football from hand to hand. It is heavy with potential. Every tool on every server is one command away — but you must type the command yourself._
+This is the dual-lock design: the agent holds the briefcase -- reach to every server, every tool, every chain of commands. But the harness holds the launch authority. The HTTP layer isn't a separate service with its own auth; it runs inside the extension process. Every call routes back through the harness, giving full observability and a single HITL choke point. Bestow executive control to the agent, but keep the safety in the infrastructure.
+
+> _They pass the Football from hand to hand. It is heavy with potential. Every tool on every server is one command away — but you must type the command yourself. And somewhere behind you, the harness is watching._
 
 ![tool-cli in action — progressive discovery piped through grep](images/tool-cli-grep.png)