docs(DX-1): single-source tool docs (D1), rename v0.1 example (D4), breadcrumb + charter

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## Unreleased
+
+- The v0.1 example `examples/shadcn-ui.dspack.json` is renamed to
+  `examples/shadcn-ui-v01.dspack.json` (DX-1, D4): the old unversioned
+  filename collided with the dspack repository's v0.4
+  `examples/shadcn-ui.dspack.json`, so the same path could silently mean
+  two different spec versions depending on the repository. All in-repo
+  references (README, demo walkthrough, pre-merge checklist, smoke
+  script) are updated; `scripts/smoke.sh` now exercises the v0.4 synced
+  example. No published-package behavior changes.
+
 ## 0.3.2
 
 The vendored `@aestheticfunction/dspack-gen/core` bundle moves from the

README.md

@@ -2,6 +2,10 @@
 
 **Stop asking AI agents to guess your design system. Give them a contract they can query.**
 
+> Part of the [dspack ecosystem](https://github.com/aestheticfunction) — the organization profile has the full map of how the repositories fit together.
+>
+> **Kind:** application (MCP server, npm `@aestheticfunction/ds-mcp`, bin `ds-mcp`) · **Audience:** people using AI coding agents against a design system, and MCP client authors · **Neighbors:** implements the [dspack](https://github.com/aestheticfunction/dspack) spec; vendors its generation core from [dspack-gen](https://github.com/aestheticfunction/dspack-gen); bootstrap a contract with [dspack-export](https://github.com/aestheticfunction/dspack-export); see the full chain running in [dspack-studio](https://github.com/aestheticfunction/dspack-studio) ([hosted replay](https://studio.aesthetic-function.com))
+
 ---
 
 ## The problem
@@ -46,8 +50,10 @@ https://github.com/user-attachments/assets/510a781b-4214-49b3-b997-9cbecdc36961
    [shadcn/ui v0.4 example](examples/shadcn-ui-v04.dspack.json) to try
    it now — it carries the governance blocks the generation tools need.
    The [v0.2](examples/shadcn-ui-v02.dspack.json) and
-   [v0.1](examples/shadcn-ui.dspack.json) examples remain for the minimal
-   format. Have a React + Tailwind/shadcn codebase? You can
+   [v0.1](examples/shadcn-ui-v01.dspack.json) examples remain for the minimal
+   format. (The v0.1 example was previously named `shadcn-ui.dspack.json`;
+   it was renamed so that no unversioned filename can be confused with the
+   v0.4 contract of the same name in the dspack repository.) Have a React + Tailwind/shadcn codebase? You can
    generate a starting file from it — see
    [Don't have a dspack file yet?](#dont-have-a-dspack-file-yet) below.)
 2. **Start ds-mcp** with the dspack file. It loads the file once and
@@ -75,11 +81,13 @@ Configure your MCP client to connect to ds-mcp. See
 
 ## Don't have a dspack file yet?
 
-If your design system is a React + Tailwind/shadcn codebase, the
-experimental [dspack-export](https://github.com/aestheticfunction/dspack-export)
+If your design system is a React + Tailwind/shadcn or Vue 3 + Vuetify 3
+codebase, the experimental
+[dspack-export](https://github.com/aestheticfunction/dspack-export)
 tool can generate a starting dspack file from it — components, props (with
-cva variant enums and defaults), color/radius tokens from your CSS custom
-properties, dark-theme overrides, and breakpoints:
+cva variant enums and defaults, and Vue `defineProps`/emits/slots),
+color/radius tokens from your CSS custom properties or an imported DTCG
+design-token file, dark-theme overrides, and breakpoints:
 
 ```bash
 git clone https://github.com/aestheticfunction/dspack-export

docs/README.md

@@ -116,17 +116,10 @@ See [GitHub's MCP documentation](https://docs.github.com/en/copilot/customizing-
 
 ## Tools
 
-ds-mcp exposes seven read-only tools:
-
-| Tool | Input | Description |
-|------|-------|-------------|
-| `get-token` | `{ category, name }` | Retrieve a single design token by category and name |
-| `search-tokens` | `{ query }` | Search tokens by name, category, description, or type |
-| `get-component` | `{ id }` | Retrieve a full component definition by ID |
-| `list-components` | none | List all components with ID, name, description, and deprecation status |
-| `get-pattern` | `{ id }` | Retrieve a documented usage pattern by ID |
-| `list-antipatterns` | none | List all anti-patterns the design system has identified |
-| `get-framework-mapping` | `{ framework, componentId? }` | Retrieve framework-specific information, optionally merged with a component binding |
+The complete tool table — eleven read-only tools, with inputs and
+descriptions — lives in the [main README](../README.md#tools). It is
+maintained in exactly one place so the two documents cannot disagree;
+this page covers client configuration only.
 
 ## Security Posture
 

docs/demo-shadcn.md

@@ -140,7 +140,7 @@ the current answer.
 
 ## v0.1 compatibility
 
-The v0.1 example ([shadcn-ui.dspack.json](../examples/shadcn-ui.dspack.json))
+The v0.1 example ([shadcn-ui-v01.dspack.json](../examples/shadcn-ui-v01.dspack.json))
 still works with ds-mcp. When loaded, the agent gets the same 13
 components, 4 patterns, 3 anti-patterns, and framework bindings — but
 without lifecycle status, accessibility constraints, composition rules,

docs/pre-merge-checklist.md

@@ -8,7 +8,7 @@
 
 ## Example dspack
 
-- [ ] `examples/shadcn-ui.dspack.json` loads without errors
+- [ ] `examples/shadcn-ui-v01.dspack.json` loads without errors
 - [ ] 13 components
 - [ ] 4 patterns (destructive-action-confirmation, form-field-layout, contextual-actions-menu, settings-form)
 - [ ] 3 anti-patterns

scripts/smoke.sh

@@ -4,7 +4,7 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 EXAMPLE_DIR="$PROJECT_DIR/examples"
-DSPACK_FILE="$EXAMPLE_DIR/shadcn-ui.dspack.json"
+DSPACK_FILE="$EXAMPLE_DIR/shadcn-ui-v04.dspack.json"
 SERVER="$PROJECT_DIR/dist/index.js"
 
 echo "=== ds-mcp smoke test ==="