docs: a followable demo, npx path, return shape, accurate CONTRIBUTING

CONTRIBUTING.md

@@ -43,7 +43,7 @@ accessibility specialist, or in any other role — your perspective on how a
 tool like this should behave is relevant. The implementation should be
 useful to practitioners, not just to people who understand MCP internals.
 
-That said, the most useful contributions in a pre-alpha repository tend to
+That said, the most useful contributions in a young repository tend to
 be exploratory: questions about intended behavior, descriptions of use
 cases you would want to cover, and feedback on whether the planned tool
 surface would actually help you do something you are trying to do.
@@ -54,7 +54,7 @@ surface would actually help you do something you are trying to do.
 
 ### Bug reports
 
-If you find a defect in the implementation once one exists, open a GitHub
+If you find a defect in the implementation, open a GitHub
 issue using the [bug report template](.github/ISSUE_TEMPLATE/bug-report.md).
 Include enough information to reproduce the problem: what you did, what
 you expected, and what actually happened. Environment details — Node.js
@@ -81,13 +81,14 @@ tool architecture), and ensure `npm test` passes before submitting.
 ### Documentation
 
 Improvements to the documentation in [docs/](docs/README.md),
-[examples/](examples/README.md), or this repository's governance files are
+[examples/](examples/), or this repository's governance files are
 welcome as pull requests at any stage.
 
 ### Example agent configurations
 
-Once a runtime exists, example MCP client configurations and usage patterns
-will live in [examples/](examples/README.md). If you have configurations
+Example MCP client configurations live in
+[docs/README.md](docs/README.md); the example dspack files and prompt
+walkthroughs live in [examples/](examples/). If you have configurations
 that work well in practice and would benefit others, those are useful
 contributions.
 

README.md

@@ -65,17 +65,20 @@ https://github.com/user-attachments/assets/510a781b-4214-49b3-b997-9cbecdc36961
 ## Quick start
 
 ```bash
-# 1. Install
+# 1. Install (or skip: `npx @aestheticfunction/ds-mcp` works without installing)
 npm install -g @aestheticfunction/ds-mcp
 
 # 2. Download the shadcn/ui v0.4 example dspack
 curl -L https://raw.githubusercontent.com/aestheticfunction/ds-mcp/main/examples/shadcn-ui-v04.dspack.json \
-  -o shadcn-ui.dspack.json
+  -o shadcn-ui-v04.dspack.json
 
 # 3. Run with the downloaded file
-ds-mcp --dspack ./shadcn-ui.dspack.json
+ds-mcp --dspack ./shadcn-ui-v04.dspack.json
 ```
 
+The filename keeps its spec version deliberately: a bare `shadcn-ui.dspack.json`
+means different content in different repositories.
+
 Configure your MCP client to connect to ds-mcp. See
 [docs/README.md](docs/README.md) for client-specific configuration examples.
 
@@ -124,7 +127,12 @@ in the [adoption guide](https://github.com/aestheticfunction/dspack/blob/main/AD
 
 ## Tools
 
-ds-mcp exposes eleven read-only tools:
+ds-mcp exposes eleven read-only tools. Every tool returns its answer as
+pretty-printed JSON inside a single MCP text block —
+`{ content: [{ type: "text", text: "<JSON>" }] }` — and reports failures the
+same way (an error string in that text channel) rather than as an MCP
+protocol error, so clients should parse the text and check for the error
+shape.
 
 | Tool | Input | Description |
 |------|-------|-------------|

SECURITY.md

@@ -35,7 +35,7 @@ where ds-mcp writes to disk, executes a shell command, or communicates
 with an external service under any circumstances, please report it as a
 security concern regardless of whether the behavior appears intentional.
 
-The dspack 0.3 generation tools (`get-generation-context`, `validate-ui`)
+The dspack 0.3/0.4 generation tools (`get-generation-context`, `validate-ui`)
 preserve the invariant: they are pure computation over the loaded document
 via `@aestheticfunction/dspack-gen`'s zero-network `core` subpath, and a
 network-boundary test scans the compiled tool path — including that

docs/demo-shadcn.md

@@ -6,9 +6,17 @@ system contract.
 
 ## Setup
 
-1. ds-mcp running with the shadcn/ui v0.2 example dspack. Download it
-   first (see the [Quick start](../README.md#quick-start)), then run:
-   `ds-mcp --dspack ./shadcn-ui-v02.dspack.json`
+1. ds-mcp running with the shadcn/ui **v0.2** example dspack. This
+   walkthrough is written against v0.2 and its counts are exact for that
+   file; the Quick start downloads the **v0.4** example instead, which
+   carries the governance blocks the generation tools need but has different
+   contents. To follow this page exactly, fetch v0.2 and run it:
+
+   ```bash
+   curl -L https://raw.githubusercontent.com/aestheticfunction/ds-mcp/main/examples/shadcn-ui-v02.dspack.json \
+     -o shadcn-ui-v02.dspack.json
+   ds-mcp --dspack ./shadcn-ui-v02.dspack.json
+   ```
 2. An MCP client connected (Claude Desktop, Claude Code, Cursor, or
    GitHub Copilot).