Sammorrowdrums/sandman readme rewrite

[SamMorrowDrums]

No description provided.

[Copilot]

Pull request overview

This PR rewrites the project README to present the “tiered progressive discovery” architecture (Skills, tool-cli, Code Mode) with updated onboarding instructions, and adds a new guide for MCP server authors explaining how to integrate with the extension’s discovery/gating model.

Changes:

• Major README rewrite with architecture narrative, diagrams, and updated Quick Start commands.
• Added docs/server-developer-guide.md describing skill resources, tool annotations, and outputSchema/structuredContent expectations for Code Mode.
• Added/embedded new image assets and npm package badges in README.

Show a summary per file

File	Description
README.md	Replaces the minimal README with a detailed architecture + onboarding doc (Skills/tool-cli/Code Mode), diagrams, images, and updated Quick Start.
docs/server-developer-guide.md	New documentation for MCP server developers on skills, gating, annotations, and structured outputs for progressive discovery/code mode.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comments suppressed due to low confidence (4)

README.md:25

• The markdown table syntax here uses a double leading pipe (|| ...). That renders as an empty first column (or breaks table rendering depending on the renderer). Use single leading pipes (| ...) for each row and the separator line.

> _They will tell you that MCP has a context problem. That the protocol gives too many tools, that the model drowns in schemas it doesn't need, that the cost of knowing everything is losing the ability to do anything well._
>
> _They are wrong._
>
> _MCP doesn't have a context problem. It has an imagination problem. The protocol already contains everything you need — `skill://` resources, tool annotations, `outputSchema`, progressive discovery. The pieces are all there, lying in the open like runes on a hillside. You just have to read them._

README.md:149

• This markdown table also uses || at the start of each row, which introduces an unintended empty first column. Switch these rows to standard |-prefixed table syntax so the table renders consistently.

The harness controls what the model sees. MCP servers just expose their tools and skills. The extension decides _when_ and _how_ to reveal them.

### Every call flows through the harness

README.md:186

• Quick Start now recommends npm install, but the repo still includes an aube-lock.yaml at the root. If aube is no longer part of the supported workflow, consider removing/archiving that lockfile (or calling out in the README that it’s legacy) to avoid confusing new contributors.

        "ghcr.io/github/github-mcp-server:skill-discovery",
        "stdio"
      ],
      "env": {

README.md:41

• The README describes skill-gated tools as being hidden until load_skill, but the implementation notes this requires pi >= 0.70.0 for dynamic tool refresh. It would help to document the minimum pi version (or the fallback behavior on older pi versions) so users don’t get surprised.

| 1 — Skills    | **The Skill Dealer**     | `skill://` resources gate tools via `allowed-tools`   |
| 2 — tool-cli  | **The Nuclear Football** | CLI progressive discovery via shell                   |
| 3 — Code Mode | **Codey C. Maude**       | Sandboxed JS over read-only tools with `outputSchema` |

---

## I. The Skill Dealer

• Files reviewed: 2/2 changed files
• Comments generated: 3