@reqvire-org/ads 0.0.0-stage → 0.2.9

package/docs/MCP.md

@@ -0,0 +1,690 @@
+# ADS over MCP
+
+`ads mcp [directory]` serves a project's local design system over stdio. It uses
+the same `ds.config.json`, token inspection and core checks as the CLI. It reads
+source and build artifacts. Optionally it manages one configured project
+preview watcher and serves the built-in browser showcase, so the client needs
+only one launch command. Source editing is disabled by default; `--mutations`
+enables guarded ADS edits. MCP does not install skills or add a production runtime.
+
+## Built-in showcase client
+
+Starting `ads mcp` automatically serves a loopback showcase. Its URL is printed
+on stderr and returned by `ads_status.showcaseUrl`/`project.showcase.url`.
+The agent keeps its stdio connection; the browser connects to `/mcp` on the same
+runtime using HTTP and the current modern protocol. Both share the configured
+preview watcher and artifacts. Stdout remains exclusively JSON-RPC.
+
+For browser-only work, run `ads showcase` inside the project. It starts the same
+runtime without stdio. `--port 4185` selects a port; otherwise the OS chooses an
+available one. `ads mcp --no-showcase` disables the website for headless clients.
+The website binds to 127.0.0.1 and accepts its own origin only. It serves packaged
+client assets and MCP, with no arbitrary file reader or command launcher.
+Shutdown closes both transports, subscriptions and the managed compiler.
+
+The shell is minimal: header, section tabs, collapsible left menu, theme switch,
+status/diagnostics when needed, and the App slot. Its MCP client does discovery,
+tool calls, resource forwarding and notification handling. Token categories come
+from `ads_tokens.categories` (discovered token scenarios); all four sections also
+come from the same `ads_scenarios` registry.
+It invokes the selected App tool and uses the official Apps bridge to render its
+HTML in an opaque sandbox. Project UI is never imported into the shell.
+
+The built-in client refreshes menus after catalogue changes and automatically
+refreshes the active scenario inside the same reusable App after a current
+successful build. Failed builds show
+file/line diagnostics and identify a retained view as stale. Themes and available
+space flow through host context. Other coding-agent hosts retain their own reload
+policy. A disconnected subscription marks retained output stale and tears down
+App watchers; refresh the page after restarting ADS. Compilation remains necessary for project TSX/Linaria, performed by the
+managed project compiler on demand and after relevant source changes.
+
+Switching entries overlays a centered loading spinner, then reveals the new
+scenario inside the existing App. Loading and diagnostic overlays do not move the
+preview. Token presentation comes from project-owned scenarios, fixtures and
+public review patterns, using the project's real foundation CSS and extracted
+styles. The tool contains no token sample templates or named token ordering.
+The generic definition inspector remains available without a scenario build.
+
+There are no required browser-page files in the project. Colocated scenarios and
+fixtures, optional public review-layout patterns, and the project's compiler
+entry supply the presentation. Use the existing runtime URL when MCP is connected
+instead of starting a second compiler for that project.
+
+## Connect Codex or Claude
+
+Use the published package through `npx`. No ADS checkout or global installation
+is needed. Open your client in the project folder containing `ds.config.json`.
+
+For **Codex**, add this to the project's `.codex/config.toml`:
+
+```toml
+[mcp_servers.ads]
+command = "npx"
+args = ["-y", "@reqvire-org/ads", "mcp"]
+```
+
+For **Claude Code**, add this to the project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ads": {
+      "command": "npx",
+      "args": ["-y", "@reqvire-org/ads", "mcp"]
+    }
+  }
+}
+```
+
+Restart/reconnect the client, then ask it to inspect your design system.
+`npx` uses the project's installed ADS version when present, or downloads the
+published package when absent. `-y` prevents an install prompt from blocking
+MCP startup. Node and npm must be available to the client.
+
+For **Claude Desktop**, use the same JSON in its MCP configuration and append
+the project path to `args`, since it does not open inside your project:
+`["-y", "@reqvire-org/ads", "mcp", "/absolute/project"]`.
+The same directory argument targets a nested frontend from another working
+directory. ADS reads that project's `ds.config.json`.
+
+The client launches the stdio server and its showcase automatically. No separate
+terminal or explorer process is needed. For browser-only inspection, run
+`npx @reqvire-org/ads showcase` inside the project and open the printed URL.
+
+These configurations follow [Codex's stdio documentation](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)
+and [Claude's MCP configuration](https://code.claude.com/docs/en/mcp).
+For tool development, use the separate [local linking workflow](GUIDE.md#develop-ads-locally)
+and [diagnostic explorer](../mcp-explorer/README.md).
+
+In the ADS checkout, `npm run ads-mcp` builds and starts the local server with
+guarded mutations; `npm run ads-read-mcp` starts it with editing disabled. Both
+also start the showcase and managed preview compiler. Append `-- --port 4191`
+to choose **http://127.0.0.1:4191/**. When a client launches these npm scripts,
+use `npm --silent run ads-mcp` or `npm --silent run ads-read-mcp` to keep stdout
+exclusive to JSON-RPC. Consumer projects use their installed tool; these checkout
+scripts rebuild ADS source first.
+
+## Protocol surface
+
+Checked against the current [base specification, 2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28),
+the stable [Skills extension](https://github.com/modelcontextprotocol/ext-skills/blob/main/specification/stable/skills.mdx),
+and [Apps revision 2026-01-26](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx).
+Skills and Apps are optional negotiated extensions. ADS keeps older protocol paths
+for clients that do not offer those capabilities.
+
+| Content | Protocol surface |
+|---------|------------------|
+| Discovery, checks and preview selection | `tools/list`, `tools/call`; small structured results |
+| Source, guides, tokens, build reports, manifests and compiled bytes | `resources/list`, `resources/read`; URI-addressed text or binary content |
+| Packaged agent workflows and their complete file manifests | `skills/list`, `skills/get` on the Skills extension; ordinary resource/tool access on older clients |
+| Skill folders and direct children | `resources/directory/read`, gated by `directoryRead: true`; directory MIME type `inode/directory` |
+| Reusable user-selected workflow messages | `prompts/list`, `prompts/get` |
+| Interactive previews | Tool `_meta.ui.resourceUri` points to a `ui://` HTML App resource; rendering uses the Apps lifecycle and resource bridge |
+| Source/catalogue, build and resource changes | List-change and resource-update notifications; modern `subscriptions/listen`, legacy resource subscriptions |
+
+Directory reads cover the packaged skill trees, including references and starter
+assets. They are not an arbitrary project filesystem browser. File manifests
+carry byte sizes and SHA-256 digests; each read returns the advertised snapshot.
+Invalid skill/directory URIs and listing cursors use protocol invalid-parameter
+errors. Expired asset URIs fail as unavailable resources, not successful previews.
+
+The server exposes these capabilities; each client chooses its UI, resource
+retrieval, prompt picker and skill activation. The showcase uses the modern
+protocol. The diagnostic explorer defaults to compatible mode; select
+**2026 · native Skills** to test native skill discovery and folder browsing.
+
+## Tools and resources
+
+### Inspect the design system
+
+Call `ads_status` to identify the connected project and preview build state.
+For example, find Button with
+`ads_catalog({ "query": "Button", "kind": "components", "limit": 5 })`, then
+open one of its returned preview IDs with `ads_show_scenario`. Results link to
+the owning source and guides; `ads_scenarios` lists available previews.
+
+`ads_tokens` inspects definitions and values. `ads_show_tokens` renders the
+project's token scenarios. If the client cannot render Apps, use the returned
+showcase URL. Build reports identify current, stale and failed output; browser
+review and project checks still verify behavior.
+
+The server supplies agent guidance through its instructions, tool descriptions,
+`ads://project/guide` and packaged ADS skills.
+
+| Tool | Purpose |
+|------|---------|
+| `ads_status` | Project paths, watcher/build states, preview revisions and diagnostics, skills |
+| `ads_catalog` | Bounded search for real public components/patterns and source/guide URIs |
+| `ads_tokens` | Bounded token-definition and theme inspection |
+| `ads_check` | Current core architectural diagnostics; registered Oxlint/build tests remain separate |
+| `ads_skills` | Workflow names/descriptions without loading instructions |
+| `ads_read_skill` | Explicit text instruction/support-file reads in bounded chunks |
+| `ads_show_tokens` | Render a discovered token scenario; legacy compilers retain the definition inspector |
+| `ads_scenarios` | Bounded token/component/pattern/composition scenario discovery |
+| `ads_show_scenario` | Render an exact discovered scenario with its own fixtures |
+| `ads_show_<id>` | Optional explicitly configured grouped App |
+| `ads_units` | Discover edit owners and the files belonging to one unit |
+| `ads_read_file` | Read bounded source ranges, with owning unit and full-file digest |
+| `ads_apply_patch` | Opt-in Git unified diff for one ADS unit, with dry-run validation |
+
+Listings have bounded pages and opaque cursors. The source catalogue exposes
+public exports from `components/` and `patterns/`; it does not execute TSX to
+guess component props. Read the exported API and owning guide. An export name
+alone does not prove that a preview renders that particular element.
+
+`ads://project/status`, `/build`, `/tokens`, `/catalog`, `/scenarios`, and `/checks` carry complete JSON
+detail. Allowed project documentation/source and skill files are separate
+resources. No arbitrary filesystem reader is exposed. Prefer bounded tools for
+large catalogues; explicit resource reads can enter model context and a client
+may truncate large payloads.
+
+## Guarded editing
+
+Enable editing in the MCP launch arguments and reconnect:
+
+```sh
+npx -y @reqvire-org/ads mcp --mutations
+```
+
+`ads_status.mutations` reports the mode, checks, limits and latest result. Editing
+is disabled by default. The editing tool accepts **one Git unified diff for one
+ADS unit**, not replacement file bodies or a caller-selected batch of owners.
+
+Find the owner with `ads_units({ "query": "Button" })`, then request its file
+manifest with `ads_units({ "unit": "components/core/Button" })`. IDs derive from
+the flat/directory colocation convention. A component or pattern unit includes
+its implementation and colocated scenarios, fixtures, tests and guides. A
+composition owns its scenario and mock inputs. Imported components and patterns
+remain separate owners. `tokens` is one foundation unit covering token definitions,
+themes and token scenarios/fixtures, whose coverage spans shared source files.
+Preview IDs remain separate: several token previews belong to `tokens`.
+
+The same discovery covers the rest of the project ADS:
+
+| Unit | Scope |
+|------|-------|
+| `foundation` | Shared ADS entry styles and root helpers |
+| `documentation` | ADS guides/licenses and the project's README, GUIDE, MCP, Architecture and ADS Markdown guides |
+| `assets/brand`, `assets/fonts`, other `assets/*` groups | Original SVG, image, font and other asset files |
+| `configuration` | `ds.config.json`, package/TypeScript/bundler/lint configuration, registered ADS guard modules, compiler/check entrypoints and their static local dependencies |
+
+Configuration ownership follows the project's registrations. It does not absorb
+components merely because a guard or compiler reads them. Guard registration,
+implementation, helpers and the associated check script can change together.
+Unregistered application code and installed dependencies retain their own owners.
+
+Read relevant source with `ads_read_file({ "path": "design-system/components/core/Button.tsx" })`.
+Reads are bounded to 12,000 UTF-16 characters. `offset`, `nextOffset`, `startLine`
+and `totalChars` support focused follow-up reads. The digest describes the whole
+file, but the agent does not need to read or send that whole file or supply its
+digest to apply a patch.
+
+```json
+{
+  "unit": "components/core/Button",
+  "dryRun": true,
+  "patch": "<Git unified diff for this unit>"
+}
+```
+
+Send this to `ads_apply_patch`. Use ordinary `diff --git`, `--- a/path`,
+`+++ b/path` and `@@ -old,count +new,count @@` text hunks with project-relative
+paths. Context and removed lines must match the current source at the stated
+positions; ADS uses no fuzzy matching. `/dev/null` identifies a created or deleted
+file. New files naturally contain their added lines. Original binary images,
+fonts and other assets use `git diff --binary --full-index`; Git 2.29 or newer must be installed
+to validate/apply those blocks. Rename metadata and permission changes are
+unsupported; owned deletion/creation can move a file within its unit.
+
+For a large or binary diff, write the Git patch to a regular file in
+`.ds/patches/`, then send a reference instead of its bytes:
+
+```json
+{
+  "unit": "assets/fonts",
+  "dryRun": false,
+  "patchFile": ".ds/patches/font.patch"
+}
+```
+
+Provide exactly one of `patch` or `patchFile`. This file is a proposed diff,
+not an edit to live ADS source. Binary `ads_read_file` results return the digest and
+byte count without encoded content. Git verifies the original binary blob and
+reconstructs the result inside the validation copy.
+
+A small change needs only its hunk. A complete new component may include its
+implementation, public re-export, scenario and fixture in the same unit patch,
+so coverage is checked against a complete candidate. New units use a new
+`components/`, `patterns/` or `composition/` owner ID following the same colocation
+convention. A patch cannot include a peer unit, capture existing peers beneath
+a new directory owner, or change unrelated public-entry statements. Shared
+public-entry changes are limited to re-exports from the selected unit.
+
+Set `dryRun` to `false` to apply. ADS reconstructs complete candidate files locally
+and validates a temporary project copy with core guards and registered Oxlint
+rules, including warnings. By default it also runs available `lint:project`
+(or `lint`), `typecheck` and `build:mcp-previews` scripts. Override only that
+additional list through project-owned configuration:
+
+```json
+{ "mcp": { "mutationChecks": ["lint", "typecheck", "build:mcp-previews"] } }
+```
+
+Every listed script must exist. An empty list still runs mandatory ADS and Oxlint
+checks. Scripts use the project's npm/Bun runner; installed dependencies are
+shared with the validation copy. These are trusted project commands, not an OS
+sandbox. An explicit `configuration` patch can change project commands, registered
+rules and reviewed exceptions; validation runs the proposed configuration and
+scripts. Mandatory core and generated Oxlint checks still run on every write.
+Configuration changes cannot bundle unrelated component edits. Checks that
+rewrite source are rejected. Each command has a 60-second limit; the diagnostic
+explorer allows up to 15 minutes for the complete request.
+
+Ordinary source and asset files owned by the selected unit are editable. Generated
+outputs, dependency directories, Git metadata and symlink/hardlink targets are
+excluded. Change original branding artwork; ADS validates generation in the
+candidate and refreshes derived icons after application. Source-level suppression
+directives are rejected outside `configuration`; express reviewed exceptions in
+project settings. The project continues to own its architecture and extensions.
+
+One unit patch is limited to 32 entries and 256 KiB inline, or 16 MiB through
+`patchFile`. Each original/resulting file is limited to 16 MiB. Validation snapshots
+are bounded to 20,000 files and 128 MiB, and retain the original project's Git
+tracking checks. Malformed or mismatched patches, changed project inputs and
+cancelled checks leave source unchanged. Write failures roll back applied entries.
+
+Acceptance refreshes discovery, generated branding and previews. Configuration
+changes restart the shared managed compiler in place; the MCP connection stays
+open. Failed preview builds report diagnostics and stale output. Inspect current
+build status and real UI; source checks do not establish visual correctness.
+
+The mutation tool is marked as a model-only write in Apps metadata. Both browser
+hosts reject App-initiated calls to it; other hosts must respect that visibility.
+MCP enforces this editing path. Direct filesystem edits remain subject to the
+project's normal lint/build gates.
+
+## Experimental Apps
+
+`ads_scenarios` discovers path-derived IDs for token, component, pattern and
+composition scenarios. `ads_catalog` links public exports to their coverage.
+`ads_show_scenario({id})` selects an independently mountable entry with its own
+fixtures. `ads_show_tokens({category})` selects a discovered token scenario;
+omitting category selects the first token entry. The tool contains no project
+token templates or copied values.
+
+### One App, shared resources
+
+With the resource compiler enabled, both tools link **`ui://ads/preview`**. Their
+small structured result identifies the selection and current build:
+
+```json
+{
+  "scenario": { "id": "components/core/Button", "kind": "components" },
+  "manifestUri": "ads://preview/manifest",
+  "manifestRevision": "<sha256 revision>",
+  "build": { "state": "ready", "current": true },
+  "showcaseUrl": "http://127.0.0.1:4185/?scenario=components%2Fcore%2FButton"
+}
+```
+
+The example omits catalogue/build detail. Executable bytes are not embedded in
+the tool result. `resources/read` supplies these registered resources:
+
+| URI | Content and owner |
+|-----|-------------------|
+| `ui://ads/preview` | Tool-owned App bootstrap, official App SDK and resource loader |
+| `ads://preview/manifest` | Project compiler's versioned scenario/dependency graph |
+| `ads://assets/<hash>.js` | Compiled shared runtime or scenario module |
+| `ads://assets/<hash>.css` | Extracted foundation or scenario styles |
+| `ads://assets/<hash>.woff2` (and other asset types) | Binary font/image/worker assets |
+| `ui://ads/previews/<id>` | Same App seeded with that scenario for direct resource access |
+
+The manifest has `schemaVersion: 1`, `framework`, `revision`, watcher `session`,
+`scenarios: [{id,title,kind,module}]`, and an `assets` map. Each asset records its
+MIME type, byte size, SHA-256 digest, kind, static imports, dynamic imports, styles
+and asset references. URIs are immutable identities; manifests publish atomically
+after all files exist. The server validates the graph and served bytes. Binary
+resources use MCP `blob` content rather than text encoding.
+
+The loader runs **inside the App iframe**. It reads through the host's resource
+bridge, verifies bytes, materializes Blob URLs and native ESM import maps, loads
+CSS/fonts, then invokes the selected module's `mount(container)`. It caches
+unchanged resources and shared runtime modules within that App. Dynamic imports
+load their own dependency closure when invoked. Vite's self-contained worker
+output remains a separate asset; workers must be stopped by their owner.
+The preview adapter uses `worker.format: "iife"`: Chrome rejects module Blob
+worker fetches in opaque origins, so the resource compiler adapts those
+self-contained preview constructors to classic workers. Production worker mode
+is untouched. Worker output with unresolved module imports requires a different
+compiler adapter and is rejected rather than falsely reported ready.
+
+The built-in showcase keeps this App alive across selections. It unmounts the
+previous scenario before mounting the next; scenario state resets while runtime
+and unchanged styles/fonts are reused. External hosts may create a fresh App for
+each tool call. Each fresh App loads independently through the same contract.
+There is no special local direct-artifact rendering path.
+
+### Host boundary and compatibility
+
+The showcase's packaged shell retains its own minimal CSS and navigation. It
+contains no project runtime, fonts, styles or rendered UI. A second loopback
+origin hosts the sandbox proxy; that proxy creates an opaque inner App iframe
+and forwards the standard Apps bridge messages. The diagnostic explorer follows
+the same sandbox model. Only the App materializes and executes project resources.
+
+Hosts need Apps support, server resource forwarding, native ESM/import maps and
+a CSP permitting declared `blob:` script/style/font/worker resources. Project
+previews declare no network connections. The host may enforce stricter policy;
+missing capabilities or blocked loads must show an error. Use the returned local
+showcase URL when an external host cannot render the App. Actual local browser
+and native-client evidence is recorded in [compatibility notes](#protocols-notifications-and-compatibility).
+
+Host context selects the project's light/dark theme and conveys available space.
+It does not silently replace project tokens/fonts with a host palette.
+Compositions retain the complete project skin. App readiness uses standard Apps
+initialization plus optional structured `ads-preview` logging (`loading`, `ready`,
+`error`); no custom parent-window readiness message is required.
+
+### Configure the project compiler
+
+```json
+{
+  "framework": "react",
+  "mcp": {
+    "previewManifest": ".ds/preview/manifest.json",
+    "previewWatch": {
+      "command": "node",
+      "args": ["scripts/build-mcp-previews.mjs", "--watch"]
+    }
+  }
+}
+```
+
+This launches the compiler directly for either npm- or Bun-managed projects.
+The starter adapter selects the runner for validation scripts from the project's
+`packageManager` field or Bun lockfile. Node remains required by ADS.
+
+Use `preact` for native Preact and a matching JSX/mount adapter. The project owns
+framework compilation and Linaria extraction. The starter's
+`scripts/build-mcp-previews.mjs` demonstrates the complete integration:
+
+- `runScenarioCompiler()` from `@reqvire-org/ads/scenarios/compiler` handles
+  scheduling, validation, source freshness, successful caches and build reporting.
+- Its `buildGraph(entries, options, track)` adapter runs one multi-entry Vite build
+  with `previewEntriesPlugin()` and `createPreviewResources()` from
+  `@reqvire-org/ads/scenarios/vite`.
+- Keep `preserveEntrySignatures: "strict"`, `cssCodeSplit: true`,
+  `assetsInlineLimit: 0`, `modulePreload: false`, and `write: false`. Include the
+  supplied dependency-tracking plugin and the project's Linaria/framework plugins.
+- `showcase/mcp/main.tsx` exports `mountScenario(Scenario, container)` and returns
+  an unmount callback. It imports the same project foundation used in production.
+  It creates no App bridge; ADS supplies that bridge once.
+
+On first demand, the adapter builds a shared graph for all registered scenarios.
+A selection loads only its static dependency closure. Validation and compilation
+run together; both must succeed before publication. `.ds/preview-cache.json`
+reuses successful validation/output only when inputs, compiler/tool code,
+lockfile, recorded dependencies and content digests match. A source edit
+revalidates and recompiles the graph; Vite shares common modules across entries.
+Normal application builds retain their own chunking and optimization.
+
+The graph lives beside the configured manifest, under `assets/`. Tiny
+`.ds/scenarios/<id>/index.html` descriptors retain the reporter/registry contract;
+they are not standalone runnable previews. Six previous graph revisions retain
+old assets for in-flight reads; older references expire with a refresh error.
+An App permits 20 build revisions to bound retained native ESM modules. The
+built-in host then recreates the App automatically; external hosts receive an
+explicit reopen diagnostic. Manifest size is capped at 2 MiB and individual resources
+at 16 MiB; those development transport limits do not alter production bundles.
+
+### Existing HTML compilers
+
+Missing/null `mcp.previewManifest` retains the older per-scenario self-contained
+HTML contract, `ui://ads/scenario`, and generic `ui://ads/tokens` definition
+inspector. `inlineScenarioHtml()` and the scheduler's `build(entry,...)` adapter
+remain available during migration. The older nested widget requires its declared
+`about:` frame CSP; it does not share runtime modules across scenarios.
+Do not set `previewManifest` until the compiler emits the graph and mount adapter.
+
+Explicit `mcp.apps` entries still accept unique lowercase/hyphen IDs, title, kind
+(`components`, `patterns`, `showcase`) and a project-relative self-contained HTML
+file. They remain capped at 2 MiB and do not replace scenario coverage.
+The generic token definition inspector remains available as a resource for source
+and alias diagnostics; `ads_tokens` works even when project previews cannot build.
+
+### One client command, managed preview builds
+
+`mcp.previewWatch` is optional. When configured, `ads mcp` starts the project's
+watch command on connection/use, once per MCP process. The client configuration
+above stays the same; no second terminal or separately managed server is needed.
+For this checkout, build the tool once and let the client launch:
+
+```sh
+npm run build
+node dist/cli.mjs mcp
+```
+
+The resource adapter builds a shared graph on demand and rebuilds it after
+source changes, using one compiler process. Apps load selected dependencies. React and native
+Preact projects supply their own build and mount adapters to the same scheduler. The
+[example build](../scripts/build-mcp-previews.mjs) is project glue, excluded from
+the npm tool. Another project uses its own framework/build. ADS supplies no
+component library and does not auto-generate lookalikes. Unconfigured projects
+still get the token widget.
+
+The configured command runs in the project root. `command` names an executable;
+`args` is a literal argument array, with no shell parsing. Local
+`node_modules/.bin` and the running Node's directory are added to its PATH.
+Use `node` with a project script for a portable direct launch; Windows `.cmd`
+wrappers require their own launcher and are not shell-executed by ADS.
+
+Both build output streams go to stderr, keeping stdout exclusively for MCP.
+Opening an App waits up to 30 seconds for validated current output. A matching
+success cache is republished in the new watcher session without recompilation;
+merely finding an older HTML file is insufficient. A timeout leaves the watcher running: inspect the
+logs and invoke the preview again. `ads_status` distinguishes watcher process
+state from reported build state. Token inspection and other ordinary tools
+remain available after a build failure. An exited watcher needs reconnection;
+an active watcher can recover on the next successful rebuild. Changes to
+`previewWatch`, the compiler adapter or ADS tooling require reconnection to load
+new process code. The shared scheduler rejects publication if its loaded adapter
+files change; normal component, fixture and style edits remain automatic.
+
+ADS stops the managed watcher and its compiler subprocesses when stdin closes or
+it receives SIGINT/SIGTERM. The project must keep its watcher in the foreground,
+rather than launching detached background processes. The configuration is
+trusted project setup; MCP tools accept no executable or command arguments.
+To manage builds yourself, omit `previewWatch` or set it to `null`, then run the
+project's existing build/watch command independently.
+
+### When a component changes
+
+Edit the owned component/pattern and its fixture. The managed watcher rebuilds
+the artifacts when their source changes. It is a child process supervised by
+MCP; the client launches only `ads mcp`. The project's compiler owns extraction
+and rebuilding, while MCP watches the resulting artifacts and serves them.
+
+The MCP server detects the new artifact and sends resource-change notifications.
+The built-in host forwards the current selection after a successful build;
+the App reads the new manifest and remounts the scenario. Invoking the preview
+tool again also works in compatible external hosts. The App checks freshness
+every two seconds when notifications are unavailable. Legacy HTML adapters
+retain their own reload behavior.
+No ADS package release or skill reinstall is needed for project component changes.
+
+### When code or styles break
+
+A preview publisher reports `building`, `ready` or `error` to
+`.ds/build-status.json`. `ads_status.build` and the `ads://project/build` resource
+expose those states, each preview's build revision, last successful revision,
+availability, freshness and diagnostics. Diagnostic positions are one-based.
+Tool summaries include the first three diagnostics per preview, capped at 1,000
+characters each, with counts and truncation flags; the build resource retains
+the complete bounded report.
+A watcher session separates revisions across restarts, and an artifact digest
+checks that the served output matches the reported successful build.
+
+On each status transition MCP sends `notifications/resources/updated` to build
+resource subscribers. Legacy connections use `resources/subscribe`; modern
+connections use the SDK's `subscriptions/listen`. The notification identifies
+the resource to read; it does not carry the diagnostics. This follows the
+[resource subscription contract](https://modelcontextprotocol.io/specification/2025-11-25/server/resources#subscriptions).
+An unchanged resource catalogue needs no list-change notification for a build
+status update. The host controls whether a notification starts an agent turn.
+
+Preview tools wait while a reported build is pending. A reported failure returns
+`isError: true`, readable file/line messages and structured build diagnostics,
+including the build resource URI. Scenario-specific App resources also refuse a
+failed build even when older output remains on disk. The reusable bootstrap and
+retained immutable assets stay readable so an existing App can report freshness;
+readability alone does not establish a current preview. After a successful rebuild the same
+tool works again without restarting MCP. If the watcher itself exits, its
+failure is reported and the client must reconnect after fixing the command.
+
+Already-mounted Apps show rebuilding, failure or a newer available revision
+when the host permits server resource reads. They check build status every two
+seconds and stop on teardown. Resource Apps automatically mount a new successful
+graph without replacing their iframe; failed builds leave the earlier view marked
+stale. The built-in host recreates the App after its retained-module limit. Other hosts can also reinvoke the tool or reload the App. Token source
+inspection is independent of component build failures.
+
+Builders without status reporting remain usable, with freshness explicitly
+`unreported` (`current: false`, `stale: null`). A running process or an existing
+HTML file is not proof of current source. `ads_check` separately reports source/CSS
+syntax and architecture violations. Typechecks, behavior tests and browser
+review still cover runtime exceptions, incorrect layout and motion. MCP does
+not repair source automatically.
+
+### Custom builder integration (advanced)
+
+The standard graph adapter already uses this reporter through
+`runScenarioCompiler`; use [the compiler setup](#configure-the-project-compiler)
+for that path. Custom builders can integrate the framework-independent reporter
+with their own publication step. A selective HTML builder, for example, uses one
+shared reporter for the compiler process:
+
+```js
+import { createBuildReporter } from "@reqvire-org/ads/mcp/build";
+import { loadConfig } from "@reqvire-org/ads";
+
+import { inspectScenarios } from "@reqvire-org/ads/scenarios";
+// loadConfig is also exported by @reqvire-org/ads.
+const { scenarios } = inspectScenarios(loadConfig(process.cwd()));
+const reports = createBuildReporter(process.cwd(), {
+  apps: scenarios.map(entry => ({ id: entry.id, file: entry.artifact })),
+});
+
+async function rebuild(entry) {
+  const revision = reports.begin(entry.id);
+  try {
+    await buildProjectPreview(entry); // project-owned compilation, extraction and checks
+    reports.ready(entry.id, revision); // only after writing complete output
+  } catch (error) {
+    reports.error(entry.id, revision, error);
+  }
+}
+```
+
+For selective builds, MCP also supplies `ADS_MCP_REQUEST_FILE`: an atomically
+updated JSON file `{session, active, files: [project-relative artifact paths]}`.
+`active` is the most recently selected artifact path; prioritize it when draining
+affected builds. The shared scheduler handles this. Custom builders may ignore
+that optional field. Watch/read
+it, validate the session against `ADS_MCP_BUILD_SESSION`, and match paths against
+the discovered registry before building. Newly requested paths need a build;
+source changes invalidate and rebuild requested entries. A builder that compiles
+all entries may ignore this request file. It is removed when MCP stops.
+
+ADS provides `ADS_MCP_BUILD_SESSION` and `ADS_MCP_BUILD_STATUS` to a managed child;
+the reporter uses them automatically. Standalone builders use the same project
+file and a new session. Updates are atomic and bounded to 256 KiB, with at most
+20 diagnostics per preview. The builder must report failures from its checks as
+well as its compiler. Call `begin` when source is invalidated, and capture a
+separate revision for each actual build; a completion from an older revision
+cannot clear a newer invalidation or error.
+
+This checkout's [Vite example](../scripts/build-mcp-previews.mjs) reports initial and
+incremental builds, compiler/output errors and immediate invalidation. Another
+project wires the reporter into its existing build hooks; ADS does not infer
+success from free-form console output or install another compiler.
+
+Invoke an App's entry **tool** to ask a capable host to render it. Reading its
+HTML resource is a data read, not evidence of a rendered view. When Apps are
+unavailable, tool results provide a bounded descriptor and the runtime's
+showcase URL. The same MCP process already serves that website, unless started
+with `--no-showcase`.
+See the [MCP Apps specification](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx).
+
+## Prompts
+
+| Prompt | Required argument | Use |
+|--------|-------------------|-----|
+| `ads-design` | `request` | Plan and implement a project-owned ADS change |
+| `ads-inspect` | `element` | Discover an existing element, its API and relevant view |
+| `ads-show` | `target` | Choose tokens or an exact discovered scenario ID |
+| Each of the five ADS skill names | `request` | Select that workflow and its skill resource |
+
+Example: get `ads-inspect` with `element="Button states in both themes"`, or
+`ads-assimilate` with `request` containing the upstream component-library URL.
+Prompts explain Data/UX/Skin ownership, public API reuse, fixture boundaries,
+which tools select widgets, progressive skill reads and validation. They guide
+reasoning rather than inventing another component implementation.
+
+Hosts choose whether prompt pickers/methods reach the agent. If unavailable,
+the agent can use the same tools and selected skill resources directly. Prompt
+retrieval itself does not execute the workflow or change project files.
+
+## Skills
+
+The npm distribution includes the five ADS skills, references, empty designer
+scaffold, credits and upstream notices. Each `skill://ads/<name>/SKILL.md` has
+a complete manifest of file URIs, UTF-8 byte lengths and SHA-256 digests.
+Supporting files are read lazily via `resources/read`; directory browsing is
+available on the newer protocol. The packaged scaffold's `.gitignore` remains
+addressable at its original resource URI.
+
+On protocol `2026-07-28`, discovery advertises `io.modelcontextprotocol/skills`
+with directory reading and implements `skills/list`, `skills/get`, and
+`resources/directory/read`. Older connections retain ordinary skill resources,
+`ads_skills` and `ads_read_skill`; their metadata listing does not pretend to be
+native skill activation. Relative references resolve from the skill URI.
+
+The host controls integrity verification, user approval and activation. Reading
+`SKILL.md` through ordinary resources/tools does not prove activation. Local
+installation with `npx skills` remains supported independently. See the
+[Skills extension specification](https://github.com/modelcontextprotocol/ext-skills/blob/main/specification/stable/skills.mdx).
+
+## Protocols, notifications and compatibility
+
+The same SDK server factory serves `2024-11-05`, `2025-03-26`, `2025-06-18` and
+`2025-11-25` through the initialize lifecycle, and `2026-07-28` through modern
+discovery/per-request metadata. An older client is not forced onto the modern
+protocol. Apps use their separate `2026-01-26` UI handshake.
+
+Project source changes invalidate catalogue caches and notify resource
+list/read subscribers. Artifact and build-status changes notify preview/build
+subscribers without rediscovering unchanged source. Configured preview changes
+also notify the tool catalog.
+Publishing a changed asset catalogue also sends a resource-list notification;
+status-only transitions with unchanged resource identities need only updates.
+The server polls file metadata once a second, so replaced files and newly added
+directories are detected. On modern connections, notifications use the SDK's
+`subscriptions/listen`; legacy clients retain list-change and subscribed-resource
+notifications. Hosts may require a manual refresh. The older generic definition
+inspector also provides an explicit Refresh action; project token scenarios
+supply their own controls.
+
+Client support varies by product and version. Ordinary tools and resources
+remain available without Apps or native Skills support. ADS uses bounded tool
+results and separate resource reads; previews also return showcase links for
+clients without Apps. Native Skills support is optional.
+
+Automated tests verify both protocol eras, resource/skill integrity, prompt
+retrieval, bounded tools, initial preview readiness, managed rebuilds, process
+cleanup and resource notifications. SDK and
+browser-host tests are distinct from a real Codex/Claude session. In a new host,
+verify tools, explicit resources, an App entry tool and its UI handshake,
+Refresh/theme behavior, notifications, prompts, then native Skills separately.
+Record the client build and negotiated protocol; HTML delivery or ordinary
+instruction reads alone do not establish Apps/Skills activation.