@reqvire-org/ads 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ilija Ljubicic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,285 @@
-# Temporary Holding Version
+# ADS — Agentic Design System
+
+**A design system your agent can see and shape. Your components. Your look. Your code.**
+
+ADS gives coding agents MCP tools and skills to build and maintain a design system
+inside your project. Agents can inspect components, tokens and patterns, render
+live previews, and submit guarded patches validated before they land.
+
+Humans and agents review the same real UI. ADS supplies architectural rules and
+build checks; your project owns the implementation, visual design and branding.
+
+**Inspired by any library. Bound to none. Owned by your project.**
+
+ADS requires Linaria for component and pattern styling; your project chooses its
+UI framework and visual design. The [architecture](docs/ARCHITECTURE.md) explains
+Data, UX, Skin, and the performance reasons behind that choice.
+
+ADS supports **React and native Preact** with the same architecture guards and
+MCP preview flow. The empty starter uses React; this repository’s working example
+uses Preact. See [implementation support](docs/GUIDE.md#implementation-support).
+
+## Set up your project
+
+Run **inside your project**, where `package.json` lives. Requires Node 22.12 or newer.
+
+```sh
+npx @reqvire-org/ads init --framework react
+npm install
+npm run build
+```
+
+Use `--framework preact` for native Preact. Init saves the choice in
+`ds.config.json`; later runs can use plain `ads init`. A copied starter that
+already declares its framework can also omit the flag.
+
+For a Bun project, run the same `init` command, then:
+
+```sh
+bun install
+bun run build
+```
+
+`init` detects npm or Bun from your project. It adds ADS and Oxlint as development
+dependencies, sets up an empty local ADS if needed, and adds ADS checks before your
+existing build. The default layout is root `design-system/`, alongside `src/`.
+It keeps your app, token values, scripts, and lockfile. Each build
+refreshes lint configuration and checks tokens, styles, imports, renderer
+boundaries, asset ownership, and registered component rules, then generates
+configured brand icons. Commit the updated
+lockfile; generated `.ds/` files are ignored. Init does not install or configure
+Linaria; integrate its extraction with your build as described in the
+[guide](docs/GUIDE.md#linaria-integration).
+
+## Commands
+
+| Command | Use |
+|---------|-----|
+| `ads init --framework react` | Set up ADS in the current project; also accepts `preact`; saved choices can omit the flag |
+| `ads check` | Check tokens, styles, imports, and ADS ownership |
+| `ads tokens` | Inspect token values and themes |
+| `ads assets` | Generate standard web icons from the project's SVG |
+| `ads lint-config` | Generate lint config; normally called by the build |
+| `ads mcp` | Start the stdio MCP server and its local showcase |
+| `ads showcase` | Start the same MCP runtime for browser-only inspection |
+
+Run commands from the project root; they read `ds.config.json` there.
+Use `ads --help` for options. Inspection commands support `--json`; `mcp` reserves
+stdout for JSON-RPC.
+See the [setup guide](docs/GUIDE.md) for other layouts, alias setup, and component rules.
+
+## Connect your agent
+
+Run inside your project. For **Codex**:
+
+```sh
+codex mcp add ads -- npx -y @reqvire-org/ads mcp
+```
+
+For **Claude Code**:
+
+```sh
+claude mcp add --transport stdio --scope project ads -- npx -y @reqvire-org/ads mcp
+```
+
+Restart your client in that project. `npx` uses its installed ADS version or
+downloads the published package. See the [MCP guide](docs/MCP.md#connect-codex-or-claude)
+for config files and Claude Desktop setup.
+
+To let the agent edit the ADS through enforced checks, append `--mutations` to
+the MCP command. It accepts a Git patch for one ADS unit, including its owned scenarios and
+fixtures, and runs the guards before applying it. Foundation styles, original
+assets, guides and project configuration/guard extensions have editable units too. See [guarded editing](docs/MCP.md#guarded-editing).
+
+The server exposes public components/patterns, token values,
+source guides, architecture checks, workflow prompts, and packaged ADS skills.
+It supports older MCP clients and the newer Skills protocol.
+
+Experimental MCP Apps show an interactive token inspector and project-built
+token, component, pattern and composition scenarios. They use the same public implementations and fixtures
+as the showcase. Text and resource access remain available without Apps support.
+Configure a project preview watcher in `ds.config.json` and MCP manages its
+startup, rebuilds and shutdown; the client launches only `ads mcp`.
+Build status and diagnostics remain readable through tools/resources, with
+notifications for subscribed clients and explicit errors from preview tools.
+See the [MCP guide](docs/MCP.md) for Codex/Claude setup, preview builds, prompts,
+notifications, skill discovery, and the client compatibility limits.
+
+To inspect an existing component through MCP:
+
+1. `ads_status` identifies the project, public API, commands and preview build state.
+2. `ads_catalog` finds the component and links its owning source, available guides
+   and preview IDs. `ads_tokens` explains the values it uses.
+3. `ads_scenarios` finds a preview; `ads_show_scenario` opens the real entry with its
+   colocated fixtures. Use `ads_show_tokens` for project-owned token samples.
+4. After a change, check build freshness, run `ads_check` and project checks, then
+   verify the refreshed preview and exercise its relevant states.
+
+This is what makes ADS useful through MCP: small, structured discovery leads to
+the exact source and real UI. Humans and agents review the same implementation,
+and build reports distinguish current previews from stale or failed output.
+Clients without Apps can inspect text/resources and use the regular showcase.
+
+## Showcase
+
+The showcase is **a minimal shell plus an MCP client and Apps host**. It ships
+with ADS tooling. Tokens, Components, Patterns and Composition share its header,
+collapsible left menu, theme switch and preview area. Lists come from MCP results;
+selecting an entry renders its real scenario inside one reusable MCP App. The
+App loads shared runtime, CSS, fonts and selected modules through MCP resources.
+All project code and styles stay inside its sandbox; the shell stays neutral.
+The project owns the implementations and colocated scenarios/fixtures.
+
+Starting `ads mcp` also starts the local showcase. Open the URL returned by
+`ads_status`; use that existing runtime when an agent is already connected.
+For browser-only use, run inside the project:
+
+```sh
+npx @reqvire-org/ads showcase
+```
+
+Or use the installed tool through your project script:
+
+```sh
+npm run dev:showcase
+# or: bun run dev:showcase
+```
+
+For MCP and the showcase together in this checkout, use either command:
+
+```sh
+npm run ads-mcp -- --port 4191       # guarded editing enabled
+npm run ads-read-mcp -- --port 4191  # read-only; run one at a time
+```
+
+Open **http://127.0.0.1:4191/**. Both commands build the local tool first and
+start stdio MCP, the showcase and the managed preview compiler.
+`dev:showcase` starts the browser-only runtime and also builds the local tool.
+Open the printed URL when choosing another port.
+`--port 4185` chooses a fixed port; the default chooses an available port.
+The title and left pane align; the title toggle hides/restores both. Minimize the
+header for a full preview, then refresh to restore it.
+
+A configured project compiler builds a shared scenario graph on first demand
+and watches code, styles, fixtures and assets. The App loads only the selected
+scenario and its dependencies. Notifications update menus and refresh the active
+scenario after a successful build. Failures show diagnostics and identify stale
+output. `ads_tokens` inspects definitions independently of preview builds. Compilation still
+happens automatically; no separate project showcase rebuild is needed.
+
+For an existing app, `init` adds the showcase launch script; it does not install
+a preview compiler. Integrate the [starter compiler and mount adapter](docs/GUIDE.md#showcase)
+with your build. The copied empty starter already includes that setup.
+
+There are no required showcase page files. Add a colocated scenario and fixture
+for tokens and each public UI owner; larger entries live under `composition/`.
+ADS rejects invented token names, tokens without reachable scenarios, and public
+components/patterns without real render coverage. Development inputs stay out
+of production. Full-app harnesses belong in application tests. See the
+[architecture](docs/ARCHITECTURE.md#the-showcase-is-the-shared-design-workspace),
+[contract](docs/ADS.md#showcase-contract) and [setup guide](docs/GUIDE.md#showcase).
+
+## Branding
+
+Change values in `design-system/tokens/`, keeping the
+[shared token names](docs/ADS.md#shared-token-contract), such as `--accent` and
+`--font-sans`.
+
+Keep original artwork and its usage/credits in `design-system/assets/brand/`.
+To generate web icons, add this to `ds.config.json`:
+
+```json
+{ "assets": { "iconSource": "assets/brand/app-icon.svg" } }
+```
+
+After init, your normal build generates favicon SVG/ICO, an Apple touch icon,
+and 192/512px icons in ignored `.ds/assets/`. Mount that directory using your
+app's bundler. With no icon source, generation is skipped. See the
+[branding guide](docs/GUIDE.md#branding) for outputs and build order.
+
+## Import and design with skills
+
+Install skills with `npx skills`:
+
+```sh
+npx skills add reqvire-org/ads --skill ads-designer --skill ads-import --skill ads-assimilate --skill ads-break-ui --skill ads-motion
+```
+
+For local development, install from this checkout:
+
+```sh
+npx skills add ./skills --skill ads-designer --skill ads-import --skill ads-assimilate --skill ads-break-ui --skill ads-motion
+```
+
+Acknowledgments: `ads-designer`'s craft/mobile guidance, `ads-break-ui`, and
+`ads-motion` adapt [Emil Kowalski's MIT-licensed skills](https://github.com/emilkowalski/skills).
+Their local [designer](skills/ads-designer/README.md),
+[break-ui](skills/ads-break-ui/README.md), and [motion](skills/ads-motion/README.md)
+credits record the sources and revision. Each skill keeps the upstream MIT
+notice beside its files.
+
+- [ads-designer](skills/ads-designer/SKILL.md): start an ADS or build UI with your local ADS.
+- [ads-import](skills/ads-import/SKILL.md): import external components, patterns, styles, token values, or brand artwork.
+- [ads-assimilate](skills/ads-assimilate/SKILL.md): implement a native component inspired by an external library.
+- [ads-break-ui](skills/ads-break-ui/SKILL.md): stress-test real components and patterns with difficult content.
+- [ads-motion](skills/ads-motion/SKILL.md): implement, review, audit, or profile component animation.
+
+See the [skill guide](skills/README.md) for examples and source credits.
+
+**There is no CLI `ads import` command yet.** Import uses the skill:
+
+```text
+$ads-import /path/to/source-repo component Toast
+$ads-import /path/to/source-repo tokens
+$ads-import /path/to/source-repo brand
+```
+
+## Development and references
+
+To develop ADS itself against another project, use the
+[npm link workflow](docs/GUIDE.md#develop-ads-locally). Consumer setup above uses the
+published package; local development uses your linked checkout.
+
+To try the ADS MCP tools and experimental widgets locally:
+
+```sh
+npm run dev:mcp-explorer
+```
+
+Open **http://127.0.0.1:4190/**. It connects automatically and lets you render
+real token/component/pattern/composition Apps, switch themes, inspect build errors, and
+try tools, resources, prompts and skills. See the
+[MCP explorer guide](mcp-explorer/README.md) for the small test flow.
+
+This repository uses its own local ADS to try ideas and verify the complete flow.
+The showcase is the visual/interaction review surface; automated tests also
+check tool behavior and the example build:
+
+```sh
+npm test                 # Tool guards and packed npm install/build tests
+npm run build:project    # ADS guards, type checking, example build and showcase
+```
+
+Set `ADS_TEST_BUN=1` when running `npm test` to include packed Bun install/build
+tests. 
+
+Tool source lives in `src/`; tests and the dummy project live in `tests/`. 
+
+See the [tooling contract](docs/ADS.md) and [tool guide](docs/GUIDE.md) for enforcement
+and setup.
+The [dummy project](tests/fixtures/guard-project/README.md) tests the generic guards with passing and failing cases.
+
+There are two different starting points in this checkout:
+
+- [bootstrap-ds/](bootstrap-ds/README.md) is an empty React application starter:
+  token defaults, build setup, empty component/pattern folders, and a project preview compiler adapter. It is bundled with `ads-designer` so an agent can copy it when starting
+  from zero. `ads init` uses its empty foundation files when a project has no ADS.
+- [design-system/](design-system/README.md) is this repository's working example,
+  with real components, patterns, and scenarios inspected through the built-in showcase. It demonstrates the architecture
+  and helps us develop the tooling. Its UI source is excluded from the npm package
+  and is not automatically copied into projects.
+
+Licensed under [MIT](LICENSE). Adapted third-party material retains its upstream
+notices.
+
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/dist/assets.mjs

@@ -0,0 +1,52 @@
+import { existsSync, lstatSync, readdirSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { isInside } from "./config.mjs";
+import { brandFiles, brandSourceDiagnostic } from "./brand-assets.mjs";
+
+function assetFiles(directory, prefix = "") {
+  const stat = lstatSync(directory, { throwIfNoEntry: false });
+  if (!stat || stat.isSymbolicLink() || !stat.isDirectory()) return [];
+  const files = [];
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    if (entry.isSymbolicLink()) continue;
+    const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) files.push(...assetFiles(path.join(directory, entry.name), relative));
+    else if (entry.isFile()) files.push(relative);
+  }
+  return files.sort();
+}
+
+export function inspectAssets({ root, dsRoot, config, trackingRoot = root }) {
+  const diagnostics = [];
+  const sourceDiagnostic = brandSourceDiagnostic({ root, dsRoot, config });
+  if (sourceDiagnostic) diagnostics.push(sourceDiagnostic);
+  function report(rule, file, message) { diagnostics.push({ rule, file: path.relative(root, file).replaceAll("\\", "/") || ".", line: 1, column: 1, message }); }
+  const assetRoot = path.join(dsRoot, "assets");
+  // Every mount is compared with the canonical ADS assets. Public mounts are
+  // independent consumers and may legitimately share a filename with each other.
+  const owned = new Set(assetFiles(assetRoot));
+  const mounts = [...new Set([path.join(dsRoot, "showcase/public/assets"), ...config.assets.publicDirs.map((directory) => path.resolve(root, directory))])].filter((directory) => directory !== assetRoot);
+  for (const directory of [assetRoot, ...mounts]) {
+    for (const file of assetFiles(directory)) {
+      if (config.assets.generatedFiles.includes(file)) report("asset-generated", path.join(directory, file), "Generated assets must be produced by the build, not kept in source asset directories.");
+      if (config.assets.iconSource && brandFiles.includes(file)) report("asset-collision", path.join(directory, file), `Asset ${file} conflicts with a generated brand output. Keep this mount's source in assets/brand/ and generate the variant.`);
+      if (directory !== assetRoot && owned.has(file)) report("asset-collision", path.join(directory, file), `Asset ${file} also exists in ${path.relative(root, assetRoot)}. Keep one source owner for this mount.`);
+    }
+  }
+  const tracked = spawnSync("git", ["ls-files", "-z", "--", "."], { cwd: trackingRoot, encoding: "utf8" });
+  if (tracked.status !== 0) {
+    // Let Git decide its discovery boundary: a .git above a mount point is
+    // not necessarily this project's repository. Non-Git projects have no
+    // tracked output to inspect; actual inspection failures remain errors.
+    if (tracked.status === 128 && /not a git repository/i.test(tracked.stderr ?? "")) return diagnostics;
+    report("asset-inspection", root, `Cannot inspect tracked build outputs: ${tracked.error?.message ?? tracked.stderr.trim()}`);
+    return diagnostics;
+  }
+  const generated = [...config.assets.generatedPaths.map((entry) => path.resolve(root, entry)), path.join(root, ".ds"), path.join(dsRoot, "dist-kit"), path.join(dsRoot, "dist-showcase")];
+  for (const file of tracked.stdout.split("\0").filter(Boolean)) {
+    const absolute = path.resolve(root, file);
+    if ((existsSync(absolute) || trackingRoot !== root && existsSync(path.resolve(trackingRoot, file))) && generated.some((directory) => isInside(directory, absolute))) report("tracked-generated", absolute, "Generated build output is tracked as source. Ignore the configured generated path.");
+  }
+  return diagnostics;
+}

package/dist/bootstrap-ds/ADS.md

@@ -0,0 +1,203 @@
+# Design-system contract
+
+This is the local contract for the copied starter. The project owns its source,
+token values, and branding. Tool updates preserve those values and customized
+code; source and theme imports are explicit operations.
+
+For the architectural rationale, see the
+[ADS architecture](https://github.com/reqvire-org/ads/blob/main/docs/ARCHITECTURE.md).
+The rules and commands needed to use this starter are included locally.
+
+## Ownership
+
+| Layer | Owns | Location |
+|-------|------|----------|
+| Tokens | Colors, typography, spacing, radii, motion, elevation | `tokens/` |
+| Primitives | Generic controls, states, interaction and accessibility | `components/` |
+| Patterns | Reusable layout and composition | `patterns/` |
+| Scenarios | Colocated development entries and inputs | Beside their owner; larger entries in `composition/` |
+| Showcase host | Navigation and MCP client | Packaged ADS tooling |
+| Preview compiler adapter | Framework mount/unmount and foundation imports | `showcase/mcp/` |
+| Application | Domain data, routing, effects and callbacks | Consuming application |
+
+The starter declares React in `ds.config.json`. Keep that choice, JSX, runtime
+dependencies and the preview mount adapter consistent. Init records a choice for
+an unconfigured project; it does not convert copied React source to Preact.
+
+The starter has no components or patterns yet. Add only what the product needs.
+Keep the ADS in root `design-system/`, beside application `src/`.
+Keep public exports in `design-system/index.ts`; consumers use its `@ds` alias.
+`styles.css` is the foundation CSS entry and contains token imports only.
+
+## Visual and interaction policy
+
+Use semantic CSS tokens for visual values. Raw values belong in the token files.
+Projects sharing this ADS use the same token names, meanings, and value types;
+their concrete values and theme overrides can differ. Reuse existing local values
+when importing components/patterns, add missing shared definitions, and import
+source token values only when adopting that theme is requested.
+Token names and prefixes are fixed by ADS architecture; foreign brand prefixes
+are rejected. Shared assignments belong in token files. Components own
+`--ds-*`, patterns `--ux-*`, and the showcase `--showcase-*`; token files cannot
+assign those local variables or override component state.
+Own primitive markup, focus, hover, selected, disabled, loading, and motion in
+the primitive. Use typed props for variations. Keep reusable structure and skin
+in colocated Linaria blocks using `css` and `cx` from `@linaria/atomic`.
+Linaria is required for component and pattern styling. This starter already
+configures extraction in both builds; `ads init` does not install or configure it.
+
+Use `ads-*` classes and `--ds-*` variables for primitives, and `ux-*` for patterns,
+including the ADS-owned frame. Scenario files define no CSS or custom
+class names and must not target component internals. Avoid inline visual styles and arbitrary visual
+string props. Omit `style` from inherited DOM prop types. Document narrow measured
+geometry exceptions if a component needs them.
+
+Use semantic HTML and test relevant keyboard/focus behavior. Motion should
+consume duration/easing tokens and respect reduced motion. Brand changes belong
+in tokens or documented component hooks. The starter uses system fonts and has
+no icon component; add a shared icon primitive when it is needed.
+
+## Showcase
+
+The showcase is a minimal shell plus an MCP client and Apps host, shipped with
+ADS tooling. It discovers token/component/pattern/composition
+scenarios from MCP tool results, invokes preview tools and responds to resource
+notifications. The project does not author a second catalogue or browser app.
+
+`ads mcp` starts the loopback website alongside stdio. Open the URL returned by
+`ads_status`. Without an agent connection, `ads showcase` starts the same runtime
+for browser use. Both transports share one configured preview compiler.
+
+The shell owns section tabs, collapsible navigation, theme controls and the App
+slot. Components, patterns, token values, scenarios, fixtures and their Linaria
+styles remain project-owned. Only the sandboxed App loads and applies project
+runtime, CSS and fonts, through MCP resources. App presentation comes from the
+selected compiled scenario; reusable review layouts live in public ADS patterns. Do not recreate
+production widgets inside the client or scenario.
+
+There are four sections: Tokens, Components, Patterns and Composition. There are
+no required `TokensPage`/`ComponentsPage`/`PatternsPage`/`CompositionPage` files.
+Legacy custom browsing pages remain checked when present, but new projects use
+the built-in client. Its tooling CSS is separate from the project style contract.
+
+The shared resource compiler builds one graph for all discovered scenarios on
+first demand. Selections reuse the App and load their dependency closure. The
+project's `mountScenario(Scenario, container)` adapter returns an unmount callback
+that releases owned roots, listeners, timers, portals and workers. Switching or
+rebuilding a scenario resets its state while retaining unchanged shared modules.
+Host context selects the project theme; it does not replace the project's skin.
+
+
+Colocate development entries and fixture inputs:
+
+```text
+design-system/
+  tokens/
+    typography.css
+    Typography.scenario.tsx
+    Typography.fixture.ts
+  components/core/Button/
+    Button.tsx
+    Scenario.tsx
+    fixture.ts
+  patterns/Editor/
+    Editor.tsx
+    Scenario.tsx
+    fixture.ts
+  composition/Workspace/
+    Scenario.tsx
+    fixture.ts
+  showcase/mcp/                 Project compiler adapter
+    main.tsx
+```
+
+Flat owners may use `Button.scenario.tsx` and `Button.fixture.ts` instead.
+`Scenario.tsx` exports a default independently mountable view and literal metadata
+`export const scenario = { title: "Button states", covers: ["Button"] };`.
+Token entries under the configured token directory also declare `tokens`:
+`export const scenario = { title: "Typography", covers: ["TokenSamples"], tokens: fixture.tokens };`.
+Metadata may read literal const fixture fields; it cannot run expressions,
+functions, wildcard lists or token discovery. The same fixture list must be
+consumed by the default entry. `covers: []` is valid for a minimal token value
+inspection entry without public UI; styled samples use a real public review
+pattern. Names and sample text belong to the fixture, values to foundation CSS.
+It imports real public UI through `@ds` and its local fixture. The adapter supplies
+initial state, callbacks and simulated services. The default entry needs no
+mandatory caller inputs or prior page initialization. Related parts may share a
+scenario containing their required public parent. Larger composition scenarios
+reuse production screen patterns; that screen reuse remains skill guidance.
+
+IDs derive from the ADS-relative path: `components/core/Button/Scenario.tsx` and
+`components/core/Button.scenario.tsx` both identify `components/core/Button`.
+Use one form per owner. Renaming moves the ID. No manually assigned ID or parallel
+registry is maintained. Fixture files use `fixture.ts`/`<Owner>.fixture.ts`; JS,
+TSX or JSON equivalents are supported. An empty fixture is valid without inputs. Extra development helpers use
+`scenario/` or `fixtures/` subfolders, or `<Owner>.scenario-adapter.ts`.
+
+`scenario-contract`, `scenario-render` and `scenario-coverage` checks require valid
+entries and reachable public render references for every public renderable
+component/pattern, including unused exports and Linaria styled exports. Types, constants and utility functions
+are excluded. Coverage is a static source policy; it does not prove runtime
+mounting, correct props, every branch/state or visual parity. The older
+`showcase-coverage` policy also checks application render references.
+
+`token-scenario-reference` rejects undeclared token names in metadata and reachable
+inputs. `token-scenario-render` rejects claimed tokens with no reachable input
+reference; `token-scenario-coverage` requires every discovered foundation token
+to have coverage. A new or removed token therefore needs a scenario/fixture
+update. All three are errors in `ads check`, run by `lint:ds` and the build.
+Coverage is static reachability, not proof that every branch actually renders
+or applies the right CSS property. Browser review still verifies the samples.
+
+Scenarios and fixture helpers are development-only wherever colocated. Runtime
+source and the public barrel cannot import or re-export them. Showcase/scenario
+code defines no CSS, custom classes or native controls; use public ADS APIs.
+Neither ADS implementations nor scenarios import application code. Live business
+data belongs to application adapters; ADS receives inputs or injected callbacks.
+Direct global `fetch`, XHR, WebSocket and EventSource use is rejected. Renderer
+workers, lazy imports and injected services remain supported; custom HTTP clients
+and computed API access need project checks and review.
+
+Tests may import local fixtures. Load real foundation CSS in DOM/browser tests
+instead of assigning shared tokens in JavaScript. Full application harnesses
+belong in application test support. Run ADS/project checks before application,
+preview builds; review meaningful states in both themes and sizes.
+
+## Branding
+
+Keep original artwork, variants, usage, credits, and licenses in
+`design-system/assets/brand/`. This starter has only guidance there, no artwork.
+Font assets belong in `assets/fonts/`; add optional `tokens/fonts.css` first in
+the import-only foundation entry. The fixed import order is fonts (when
+present), colors, typography, spacing, elevation, base.
+
+Select an SVG with `assets.iconSource` in `ds.config.json`, relative to the ADS
+folder. Initialized builds run checks and Oxlint, then `ads assets`, then existing
+build steps. Standard icons go into ignored `.ds/assets/`; integrate that
+directory with the application's asset mount and reject duplicate paths.
+Application metadata and custom platform exports remain project-owned. See
+[brand guidance](design-system/assets/brand/README.md).
+
+## Component guides and rules
+
+Keep detailed API, examples, interactions, token hooks, tests, and source credits
+in a README beside the component. When adapting another library, record its
+version, author, links, concrete influences, and agreed differences. Shared
+architecture belongs here rather than duplicating each component contract.
+
+General Oxlint and Biome CSS checks are included. They do not enforce the entire
+ownership or token contract. Add component-local lint only for concrete,
+statically provable misuse; register tooling centrally and keep it outside the
+runtime barrel. Core checks must work without any particular component library.
+Use configured token and ownership guards as the system grows; bring applicable
+component-specific rules with an external item and register them in project
+tooling. Configure project plugins, rules, and scoped `oxlint.overrides` in
+`ds.config.json`. Overrides configure Oxlint, not independent `ads check` policies.
+Use explicit `boundaries` for documented renderer properties and non-state hooks.
+
+## Verification
+
+Run `npm run build` after adding or changing components. Add meaningful tests
+for stateful behavior, accessibility, gestures, or async lifecycle where needed.
+Run `npm run dev` to inspect the real showcase. A screenshot alone does not
+verify interaction or animation. Generated output and dependencies are not source.

package/dist/bootstrap-ds/README.md

@@ -0,0 +1,98 @@
+# Empty native design system
+
+This private React/TypeScript workspace contains semantic CSS tokens, an empty
+public barrel, Linaria extraction and a project preview compiler adapter. It has
+no components, patterns, icons, fonts or example screens. The minimal showcase
+shell and MCP client come from ADS tooling.
+
+Read the local [contract](ADS.md) and the
+[architecture](https://github.com/reqvire-org/ads/blob/main/docs/ARCHITECTURE.md).
+
+## Start
+
+Copy the contents of `bootstrap-ds/`, including dotfiles, into a new project.
+The installed `ads-designer` skill contains the same files in
+`assets/bootstrap-ds/`. Set the project name in `package.json`. Use Node 22.12 or
+newer and ADS 0.3 or later for the shared-resource preview compiler.
+
+```sh
+npx @reqvire-org/ads init --framework react
+npm install
+npm run build
+npm run dev:showcase
+```
+
+For unreleased tooling, run init using the real local package:
+
+```sh
+ads_tool_package="/absolute/path/to/reqvire-org-ads-0.3.0.tgz"
+npx --yes --package "$ads_tool_package" ads init --framework react --tool-package "$ads_tool_package"
+npm install
+npm run build
+```
+
+For a new Bun workspace, declare Bun in `packageManager`, omit the copied npm
+lockfile and translate nested npm scripts to `bun run`. Init detects existing
+Bun projects and preserves their scripts/lockfiles. Use `bun install` and
+`bun run build`/`bun run dev:showcase`. The supplied preview watcher launches Node
+directly and runs the project's installed checks.
+
+For an existing application, merge only the ADS source and required extraction,
+aliases and preview adapter. Preserve its framework, entry points and build.
+The starter declares `"framework": "react"` in `ds.config.json`. For an existing
+native Preact app without a saved ADS framework, use `ads init --framework preact`.
+Init records that choice and generates native hook imports without migrating the
+app or rewriting its compiler. Subsequent init runs reuse the saved choice.
+Init adds missing foundation files and connects architectural checks; it does
+not configure Linaria or generate component source. Generated `.ds/` files are
+ignored; original artwork and provenance belong in `assets/brand/`.
+
+## Inspect and add UI
+
+When an agent already runs `ads mcp`, open its `ads_status.showcaseUrl`. MCP starts
+the website automatically. Otherwise `npm run dev:showcase` runs `ads showcase`.
+Its shell is minimal: tabs, collapsible left menu, theme switch and App slot.
+Its MCP client discovers entries, invokes preview tools and follows notifications.
+There are no required TokensPage/ComponentsPage/PatternsPage/CompositionPage
+files, and no separate project browser app to implement or rebuild.
+
+The existing `tokens/Foundation.scenario.tsx` and colocated fixture inspect all
+starter token values. Add/remove fixture names alongside token definitions;
+`ads check` rejects missing coverage and invented names. Styled token samples
+belong to your public review patterns and mount through the same scenario pipeline.
+
+Create a component under `design-system/components/`, export it through `@ds`,
+and colocate `Scenario.tsx` plus `fixture.ts` (or `<Owner>.scenario.tsx` and
+`<Owner>.fixture.ts`). Reusable compositions belong under `patterns/`; larger
+scenarios live under `composition/`. Each entry mounts independently with its
+fixture inputs and state/callback adapter. Use public ADS APIs and owned Linaria
+styles, keeping business data/services in the application.
+
+`ds.config.json` configures the supplied Vite watcher. It builds all discovered
+scenarios into one shared resource graph on first demand and watches owner code,
+styles, fixtures and assets. The App loads the selected dependency closure and
+reuses unchanged runtime/CSS/font resources across selections. The MCP client
+refreshes successful revisions inside that App; failures show diagnostics and
+stale retained output. Switching or rebuilding a scenario unmounts its previous
+state. `showcase/mcp/main.tsx` exports `mountScenario(Scenario, container)` and
+returns an unmount callback; it is not the shell. Keep the saved `framework`,
+compiler and mount adapter consistent.
+
+The application and previews use the same foundation CSS and Linaria pipeline.
+The source barrel loads the foundation once. The private `build:lib` script uses
+Vite library mode plus declarations as a source compile check; this is not a
+published UI library. General CSS checks use pinned Biome; architectural and
+registered component checks come from initialized ADS tooling.
+
+Detailed public API, behavior, tokens, tests, credits and notices belong in each
+owner's local README. The starter values and system fonts are defaults; the
+receiving project owns their identity. Import/adapt additional source explicitly
+from a user-selected external repository, preserving revisions and licenses.
+
+## Validation
+
+`npm run build` runs lint, type checking and the public-source compile check.
+`npm run build:showcase` optionally prebuilds the shared preview graph; normal
+inspection builds it automatically, then loads selected entries. Browser review
+still checks layout, accessibility, keyboard/focus, states, themes and motion. A clean
+build or delivered HTML alone does not establish those behaviors.