@reqvire-org/ads 0.0.0-stage → 0.2.9

package/dist/skills/ads-import/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: ads-import
+description: "Import selected components, patterns, styles, or brand artwork into a project's design system using ADS's fixed token names and ownership. Use tokens mode to adopt compatible source theme values. Preserves behavior, credits, and license notices."
+---
+
+# ADS Import
+
+When ADS MCP is connected, use `ads_status`/`ads_catalog` to inspect the destination
+and discover its addressable scenarios; `ads_tokens` inspects its current
+values. Render imported public implementations in real project fixtures, using
+the normal showcase when Apps are unavailable. MCP does not perform the import
+or replace source inspection. Resolve served skill references relative to this
+`SKILL.md` URI and load them lazily; a read does not itself activate the skill.
+Use the returned `projectRoot` and `project.commands`; the connected ADS may be
+inside a different or nested repository. Inspect the selected public API, owning
+source/available guides and relevant tokens, then mount its discovered scenario.
+Metadata and source reads do not prove rendered behavior.
+
+When `ads_status.mutations.enabled`, discover the owner with `ads_units`, read
+relevant ranges with `ads_read_file` and send only a Git unified diff through
+`ads_apply_patch({ unit, patch, dryRun })`. A unit includes its own implementation,
+scenarios and fixtures; imported peers remain separate. `tokens` is the token
+foundation unit. Unit discovery and file ownership are distinct from preview IDs.
+Include only that owner's required re-exports in the public entry. Use
+`dryRun: true` to inspect validation; applying re-runs the gates. Fix rejected
+patches in their owner. Shared styles/helpers use `foundation`, root guides use
+`documentation`, and branding/fonts use their discovered `assets/*` unit.
+Intentional configuration, rule exceptions, registered guard code and compiler
+changes use `configuration`; validate the proposed settings and keep mandatory
+ADS gates. For binary/large assets, generate `git diff --binary --full-index` into
+`.ds/patches/<name>.patch` and send `patchFile` instead of inline `patch`, so bytes
+stay out of model context. Binary changes require Git. When editing is disabled,
+use the client's normal source-editing tools.
+
+Before trusting a preview after edits, check `ads_status.build` or
+`ads://project/build`. Fix build diagnostics in owned source; an older view or
+unreported freshness is not evidence of current code. Notifications may not
+reach the agent.
+
+Transfer existing ADS implementation into the target design system. Use the
+source's real files and documented contracts, integrating them with the target's
+structure, exports, and build. Preserve the selected item's interaction and
+motion mechanics. Its visual values follow the destination theme unless the
+user also requests source token values.
+
+React and native Preact are supported. Preserve the target runtime in both
+production and scenario builds; never alias React to Preact just to shrink a
+preview. Native Preact uses its own JSX transform, hooks and DOM events (live
+text updates use `onInput`). Native SVG uses DOM names such as `stroke-width`,
+not React presentation aliases. Keep Linaria extraction and the same public APIs.
+The shipped empty starter uses React; the tool repository's working example
+uses Preact. Neither is a component dependency of the receiving project.
+
+ADS is tooling only. Components, patterns, themes and scenarios live in
+external sources, not a built-in or optional tool catalogue. Import the selected
+external source into the destination's
+local ADS folder; the project owns the resulting code and theme values, and the
+app uses its local public barrel. Do not install the source ADS as a UI runtime
+dependency. Later source updates require explicit imports or merges that preserve
+local customizations.
+
+## Input and selection
+
+```text
+$ads-import <repository-url-or-local-path> [component|pattern|style|brand <names...>|tokens]
+$ads-import /path/to/source-repo component Toast
+$ads-import /path/to/source-repo pattern AppShell
+$ads-import /path/to/source-repo style dense-controls
+$ads-import /path/to/source-repo tokens
+$ads-import /path/to/source-repo brand
+```
+
+Accept plural forms such as `components`, `patterns`, `styles`, and `brands`, and multiple
+names. A repository URL can identify a branch, commit, or ADS subdirectory; honor
+that reference. The user can also specify the ADS path or revision in prose.
+Use the current repository's design system as the destination unless named otherwise.
+
+Read [references/cli.md](references/cli.md) and invoke supported ADS CLI commands
+through `npx` using the actual published version or a local tarball. The current
+CLI performs setup/checks; this skill performs the source import and integration.
+
+If the source is missing, ask for its URL or local path. Inspect its catalogue
+before asking which item to import:
+
+- With only a source, ask which component, pattern, style, or brand artwork to import, offering
+  actual discovered names and a **token-values-only** option.
+- With a category but no names, ask which items in that category to import.
+- With explicit names, resolve them from the source catalogue without asking
+  again. Infer the category for a unique bare name; clarify ambiguous names.
+- With `tokens`, import all source token values without asking for component,
+  pattern, or individual token selection. This explicitly requests a theme-value
+  import. The user can request item imports and token values together.
+- With `brand`, inspect original artwork and usage guides, then resolve named
+  assets or ask which variants to import. Read [branding.md](references/branding.md).
+  Brand selection imports artwork and guidance; theme-value changes require
+  `tokens` or an explicit values request.
+
+Do not select an arbitrary item or import the entire component catalogue when
+the selection is missing. Continue source/destination research while awaiting
+the answer; wait for the selection before changing the destination. Necessary
+dependencies of a selected item are included in its import scope.
+
+## Discover both systems
+
+Read repository instructions, `README.md`, `docs/ARCHITECTURE.md` and `docs/ADS.md`
+when present or equivalent guides, public exports, relevant local READMEs, style entries, and build/lint
+configuration in both repositories. Locate the actual ADS folder: it may be
+`design-system/`, an existing nested ADS folder, or a workspace package. Inspect its token,
+component, and pattern structure rather than assuming a folder name proves it
+is a reusable ADS. Clarify genuinely ambiguous source or destination folders.
+
+For a remote source, use available repository tools or an isolated checkout.
+Record the resolved commit/revision and ADS path; keep the source read-only and
+copy source files rather than generated bundles. Do not overwrite the target's
+repository metadata or project configuration with the source checkout.
+
+The destination's component and pattern styling uses required Linaria extraction.
+Adapt source styles to colocated `@linaria/atomic` blocks while preserving the
+selected interaction contract. Verify extraction in app and preview builds;
+`ads init` does not install or configure Linaria. Preserve the destination framework.
+
+Build a working import inventory: selected items, their transitive runtime/style
+dependencies, assets, external packages, source guides, and relevant tests/rules.
+Use source exports and dependency edges to distinguish public items from helpers.
+
+## Shared token contract and theme values
+
+Read [tokens.md](references/tokens.md). Shared token names, meanings, and value
+types form the contract; concrete values and theme overrides can differ between
+projects. Different values for the same compatible token are expected.
+
+ADS fixes token names and namespaces. The destination uses the architecture's
+shared names, `--ds-*` for components, and `--ux-*` for patterns, including the
+owned review layouts. Fixtures define no custom styling. Do not add configurable prefixes, source-prefixed
+aliases, or a parallel vocabulary. Normalize selected nonconforming source to
+the ADS architecture as part of the import; report unresolved semantic mappings
+before writing them. This does not add foreign-prefix support to ADS tooling.
+
+| Import mode | Token handling |
+|-------------|----------------|
+| Component, pattern, or style | Reuse destination token names and values; add missing shared definitions with initial values |
+| `tokens`, or items plus an explicit values request | Import all source-provided token values and theme variants; add missing definitions |
+
+Inspect the complete source/target contract for additions and compatibility.
+Preserve existing destination values during item imports, including starter
+values. Synchronize missing shared definitions and needed aliases/types without
+replacing existing registries, helpers, stylesheets, or themes wholesale. A truly
+empty destination needs initial definitions and values before an item can render.
+
+In `tokens` mode, apply the source values for compatible token names. Preserve
+target-only tokens and theme variants the source does not define. Bring assets
+needed by imported values, such as fonts. This mode already authorizes the value
+changes; do not ask again merely because source and target values differ.
+
+If names, meanings, or types are incompatible, resolve a semantic mapping or
+contract migration before writing it. Keep one shared contract; do not create
+source-prefixed duplicates. Document any necessary migration between canonical
+ADS names and any user-requested adaptation.
+
+## Import the selected implementation
+
+Read [implementation.md](references/implementation.md) for dependency closure,
+style ownership, documentation, and verification. Copy selected items and needed
+helpers/styles/assets into the matching target layers. Reuse target dependencies
+only after checking compatible APIs and behavior. Merge only necessary external
+dependencies and build support; keep the target's framework and unrelated scripts.
+
+Preserve interaction, accessibility, lifecycle, gestures, and animation mechanics.
+Rewrite paths, token references, and exports as required by the integration. A different
+styling engine may require equivalent source-to-source conversion; document any
+material API or UX change. Keep product routes, data, and example scaffolding
+outside reusable ADS runtime code.
+
+Register imported component-specific lint through the target's central tooling
+when applicable. Keep tooling out of runtime exports. Do not automatically copy
+the source's whole lint/configuration stack or create rules for every component.
+
+## Document, verify, and deliver
+
+Discover the target's showcase and run/build commands. It is the shared design
+review surface for agents and humans. Add/update examples for imported components
+and patterns; token-value/style/brand imports update and inspect existing examples
+across relevant themes and sizes. Examples and composition scenarios import the same
+public ADS source and foundation styles as the application. Keep isolated sample
+data, state and callback adapters beside their scenario; larger entries belong
+under `composition/`, rather than inside browsing pages. Production-screen structure
+and reusable controls/patterns must live in the ADS.
+Do not copy a source mock's private implementation or keep a demo-only replica.
+Reusable scenario review layouts are public ADS entities with defined APIs.
+The outer minimal shell belongs to the MCP client. Showcase/scenario files define no CSS, custom classes, or widget markup.
+Use the target's owned review layouts; change their ADS pattern if a new layout
+is needed inside a scenario. The outer showcase shell belongs to the tool.
+
+If no showcase is running, start the built-in client with `ads showcase`.
+Run shared ADS/project guards before both showcase and app builds; inspect the
+rendered examples and relevant interactions. Fix shared UI in its owner and
+give a full running URL or exact run command for human review.
+
+The showcase is a minimal shell plus an MCP client and Apps host, supplied by ADS
+tooling. It discovers Tokens/Components/Patterns/Composition entries through MCP
+tools and renders their scenarios in the preview App. Navigation, theme and
+pane/header visibility belong to the tool client. Do not create page files,
+copy its shell into the project or assemble a second catalogue/rendering pipeline.
+
+When MCP is connected, open the running URL from `ads_status`. Otherwise run the
+installed `ads showcase` or the project's `dev:showcase` script. Do not launch a
+second runtime/compiler for the same connected project. A configured project
+preview watcher publishes a shared graph on first demand and after source
+changes. The built-in client refreshes discovery and the active scenario in the
+same App after a successful build. Shared runtime, foundation CSS, fonts and
+selected scenario modules load through MCP
+resources inside the sandboxed App. Never inject project styles/runtime into
+the outer host. Keep the configured framework, compiler and mount/unmount adapter
+consistent; scenario teardown must release owned timers, portals and workers.
+The host shows errors and marks retained output as stale. Other hosts may need an
+explicit preview-tool invocation. Compilation remains project-owned and required
+for TSX/Linaria; it is automatic, not eliminated.
+
+Reusable review layouts belong in public project ADS patterns, while scenario
+files define no CSS, custom classes or widget replicas. Keep real presentation in
+its component/pattern owner. The tooling shell's CSS is outside that project
+contract. Legacy custom showcase pages may be retained during migration; new
+projects require no TokensPage/ComponentsPage/PatternsPage/CompositionPage files.
+
+Colocate `Scenario.tsx` and `fixture.ts` with tokens and each component/pattern; flat owners
+may use `<Owner>.scenario.tsx` and `<Owner>.fixture.ts`. Put larger entries under
+`composition/<Name>/Scenario.tsx` with their own `fixture.ts`. Export a default
+zero-input mountable view and literal metadata, for example
+`export const scenario = { title: "Button states", covers: ["Button"] };`.
+Import the real UI from the public ADS alias. Keep fixture inputs, simulated
+services and initial state/callback adapters beside the scenario. Empty fixtures
+are valid for an entry with no inputs. Extra development helpers use a
+`scenario/` or `fixtures/` subfolder, or `<Owner>.scenario-adapter.ts`, so guards
+recognize their role even beside runtime code. Never require a page, router or store to
+initialize the entry. Several contextual public parts may share one scenario.
+
+IDs derive from ADS-relative filenames: both `components/core/Button/Scenario.tsx`
+and `components/core/Button.scenario.tsx` identify `components/core/Button`.
+Use one form, no duplicate IDs or hand-maintained registry. Renames change IDs.
+The showcase and external hosts mount the same discovered entry. The Vite
+adapter uses `previewEntriesPlugin` and `createPreviewResources` with
+`runScenarioCompiler` to publish the shared graph. Its framework mount adapter
+returns cleanup; the project owns rendering and Linaria extraction. The older
+`scenarioRegistryPlugin` is only for retained legacy browsers. MCP discovers
+metadata without importing executable TSX. Existing apps need an explicitly
+integrated compiler; init alone adds no compiler or extraction setup.
+Use `ads_scenarios` (query/kind/limit) and `ads_show_scenario({id})` to open an exact
+entry. Check its build freshness; HTML delivery is not browser verification.
+If Apps or resource forwarding are unavailable, open that scenario in the real
+showcase, using the tool result's URL. Do not build a preview-only replica.
+
+For a production screen, find and render the application's public screen pattern.
+Its owner supplies structure, controls, layout and presentation. Scenario fixtures
+supply data/state/callbacks. Move shared presentation into a pattern if needed,
+preserving existing behavior and lazy imports, workers, caching and cancellation.
+Do not reassemble an alternative screen or substitute placeholder content.
+Screen reuse remains skill guidance, not a dedicated screen-parity lint.
+
+Resolve `scenario-contract`, `scenario-render` and `scenario-coverage` findings
+with meaningful entries. Every public renderable component and pattern needs an
+addressable scenario, including unused exports; types/constants/utilities do not.
+Only public render references reachable from the default entry count. Tests and
+unused imports/functions do not. Static reachability does not prove successful
+mounting, correct content, every branch/state or visual parity: open each affected
+entry independently and verify real behavior at narrow/wide sizes in both themes.
+The older `showcase-coverage` policy separately checks application references.
+
+Token previews use that same scenario pipeline. Colocate a token scenario and
+fixture under the configured token directory. Use static metadata
+`{ title: "Typography", covers: ["TokenSamples"], tokens: fixture.tokens }` with
+literal const fixture fields; names/sample text are fixture data, values come
+from the real foundation CSS. Reuse a public project review pattern for styled
+samples. The minimal starter's foundation value scenario can have `covers: []`.
+Every declared token needs reachable scenario coverage; adding/removing a token
+requires fixture updates. Fix `token-scenario-reference`, `token-scenario-render`
+and `token-scenario-coverage` findings. Metadata and unused fixture fields do not
+count. Discover exact token IDs with `ads_scenarios({kind:"tokens"})`; mount them
+with `ads_show_scenario({id})` or `ads_show_tokens({category:id})`. With the shared
+resource compiler, omitting category opens the first project token scenario.
+Legacy compilers retain the generic definition inspector. Use `ads_tokens` for
+source definitions and values; inspecting definitions does not prove UI parity.
+The tool keeps the shared naming contract; sample templates and their token
+lists belong to the project.
+
+Scenarios, colocated fixtures and helpers are development-only. Never export them
+from the runtime barrel or import them in production, including through aliases,
+re-exports or dynamic imports. They may not import application stores, routers,
+providers or HTTP clients. Live business data is application-owned; UI uses typed
+inputs or injected services/callbacks. Direct global fetch/XHR/WebSocket/EventSource
+is rejected; custom clients and computed access require review/project guards.
+Use local simulated services in fixtures. Tests may import fixtures; load real
+foundation CSS rather than assigning shared token values in JavaScript. Keep
+full-app integration harnesses and workflow coverage in application test support.
+
+
+
+Register component/project Oxlint plugins and rules in `ds.config.json`. Use
+scoped `oxlint.overrides` for justified file-specific settings; never edit
+`.ds/oxlintrc.json`. These overrides configure Oxlint, not the independent
+architecture checks in `ads check`. Measured renderer properties and documented
+non-state hooks use explicit `boundaries`; shared token writes and primitive
+state overrides cannot be allowlisted. Add generic architectural protections to
+ADS core and keep domain/component-specific rules registered in project setup.
+
+Write or update the imported item's local README with public usage, required
+setup, token hooks, behavior, tests, and any integration differences. Include
+source repository/file links, revision, authors, and concrete provenance. Carry
+forward existing upstream credits and preserve applicable license/copyright
+notices for code, tokens, fonts, icons, and other assets actually imported.
+Record token-contract additions, value-import provenance, and theme policy in
+the receiving project's ADS guide. Keep its item catalogue and implementation
+docs outside the core tool's documentation.
+
+Verify contract compatibility, missing-token additions, entry/asset resolution,
+public exports, and the actual showcase/consumer path. Run the target's relevant lint, type checking,
+build, and meaningful imported component/rule tests. Compare source/imported
+behavior and motion where the item needs it; a successful build or screenshot
+alone does not establish parity. Account for intentional destination-theme
+differences. Token-value imports also need consumer checks for existing theme,
+typography, spacing, and motion behavior.
+
+Follow [references/cli.md](references/cli.md) to integrate the tool as a
+development dependency in the target's actual lint/build pipeline. Register
+imported component rules through its project-owned plugin adapter and
+`ds.config.json` Oxlint plugins/rules, then run the normal project build; its lint
+step refreshes configuration and runs ADS/core/project rules automatically.
+Use npx for bootstrap or ad hoc checks. Preserve unrelated existing lint setup;
+do not add catalogue imports to core tooling. CLI checks complement the project
+build and behavior tests.
+
+Report selected imports and included dependencies, contract additions, whether
+destination values were retained or source values imported, source revision/path,
+retained notices, checks run, and any unresolved integration limits. Give actual
+demo URLs only when running; clean up
+temporary comparison servers when finished unless the user requested they remain.

package/dist/skills/ads-import/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ADS Import"
+  short_description: "Import ADS items, brand artwork, or theme values"
+  default_prompt: "Use $ads-import with a source repository to import selected ADS items, brand artwork, or token values using the fixed ADS architecture."

package/dist/skills/ads-import/references/branding.md

@@ -0,0 +1,44 @@
+# Import project branding
+
+Use this reference for explicit `brand` selection. Components, patterns, and
+styles retain the destination's identity; `tokens` separately adopts compatible
+theme values. Brand import brings selected original artwork and its guidance,
+not generated platform exports or an entire source build configuration.
+
+Inspect the source's real originals, variants, README, license/credits, and any
+icon-source setting. Resolve named assets, or ask which discovered variants to
+import when selection is missing. Preserve the receiving project's artwork and
+icon source unless replacing them is part of the request.
+
+Copy selected masters into `design-system/assets/brand/`. Update its local README
+with usage, suitable backgrounds, source repository/file links and revision,
+authors, credits, and applicable license notices. Keep fixed colors and geometry
+in original SVG artwork. Licensed fonts needed by an explicit theme import live
+in `assets/fonts/`; declarations use `tokens/fonts.css`.
+
+UI branding uses existing ADS token names such as `--accent` and `--font-sans`.
+Component variables use `--ds-*`, patterns `--ux-*`, and owned scenario review layouts
+`--ux-*` (`--showcase-*` is reserved, not permission for fixture CSS). These prefixes are fixed; do not introduce a brand namespace or
+assign component state variables in token files. Source artwork is not a reason
+to change destination token values during an asset-only import.
+
+When the selected artwork should supply the app icon, set only
+`assets.iconSource` in the target's `ds.config.json` to its ADS-relative path,
+for example `assets/brand/app-icon.svg`. The source must be an SVG inside
+`assets/brand/`. Use the real installed tool's `ads assets` command to generate
+favicon SVG/ICO, an Apple touch icon, and 192/512px icons in ignored `.ds/assets/`.
+No cache, manifest, theme adapter, or extra export-target configuration is needed.
+
+Integrate that generated directory into the target's existing asset mount/copy
+step without replacing unrelated public assets. Duplicate final output paths
+must fail. Keep application manifest metadata and custom platform exports in
+the project. A configured SVG background is retained; otherwise rendering keeps
+transparent padding and the artwork's aspect ratio.
+
+Follow [cli.md](cli.md) to integrate local tooling into the normal npm/Bun build:
+ADS checks and registered Oxlint rules run before asset generation and the
+existing build steps. Run the normal build, inspect actual icon dimensions and
+transparency, and verify the real consumer URLs and selected artwork variants.
+Confirm token values, unselected artwork, configuration, and unrelated build
+steps were preserved. Report source provenance, selected originals, icon-source
+changes, generated outputs, mount integration, and checks.

package/dist/skills/ads-import/references/cli.md

@@ -0,0 +1,111 @@
+# Run ADS tooling through npx
+
+Use npx for setup or ad hoc checks alongside this skill's research,
+implementation, documentation, and verification workflow. ADS must be a project
+development dependency, and its checks must run before the project's build.
+Routine builds use the local CLI.
+
+Select an actual published package/version or a real local tarball supplied by
+the user or built from the tool checkout. Respect the project's installed
+version. Confirm the selected published version supports the required features; use a
+local tarball for unreleased changes. Never resolve an unrelated package with
+bare `npx ds`. Read the actual version/help and use only supported commands.
+
+## Published setup
+
+Run **inside the receiving project**, where
+`package.json` lives:
+
+```sh
+npx @reqvire-org/ads init --framework react
+npm install
+npm run build
+```
+
+Use `--framework preact` for native Preact. A saved `framework` in
+`ds.config.json` lets later init runs omit the flag; otherwise the choice is
+required, including for an older config. Init preserves existing framework
+tooling and rejects conflicting saved/JSX settings instead of converting it.
+
+Use the confirmed package name/version if different. For an existing Bun
+project, the same init command detects `packageManager` or `bun.lock`/`bun.lockb`;
+then use `bun install` and `bun run build`. Node 22.12 or newer remains required.
+Only use `--package-manager bun` when the project has no Bun marker yet or needs
+an explicit override. Preserve its existing package-manager policy and lockfile.
+
+`init` accepts no directory argument and requires an existing `package.json`.
+For starting from zero, copy the bundled `ads-designer` application scaffold
+first, then run init inside it. For an existing app, init preserves app files,
+framework configuration, lockfiles, and build scripts. It adds only missing ADS
+foundation files, config, development dependencies, and build checks. Existing
+ADS values are reused; incomplete contracts need an explicit migration.
+
+Init adds `lint:ds` and `assets:ds`, and runs checks then brand generation before
+the existing `prebuild` hook without replacing the actual build command or
+unrelated checks. It rejects conflicting custom scripts before writing.
+It does not configure framework aliases, style
+extraction, or application entry points; integrate these using the target's
+framework and ADS contracts. Install dependencies, review the changes, and
+commit the updated lockfile.
+
+## Local checkout testing
+
+If no published distribution exists, build and pack the tooling checkout with
+`npm run build` and `npm run pack:tool`. Resolve its tarball to an absolute path.
+From inside an existing test project:
+
+```sh
+ads_tool_package="/absolute/path/to/reqvire-org-ads-0.3.0.tgz"
+npx --yes --package "$ads_tool_package" ads --help
+npx --yes --package "$ads_tool_package" ads init --framework react --tool-package "$ads_tool_package"
+npm install
+npm run build
+```
+
+Use Bun's install/build commands for Bun projects. Keep npx options before
+`ds`. `--tool-package` is optional local-testing/version-override support;
+registry users do not need an archive. A `file:` dependency must remain
+available wherever dependencies are installed. A published pinned version is
+portable between machines.
+
+## Checks and rules
+
+For an initialized project, from its root:
+
+```sh
+npx @reqvire-org/ads check
+npx @reqvire-org/ads tokens --json
+npx @reqvire-org/ads assets
+```
+
+Use the selected real distribution; for a local tarball, invoke
+`npx --yes --package "$ads_tool_package" ads check` instead. Other inspection
+commands accept a directory; init deliberately does not.
+
+Every normal build refreshes `.ds/oxlintrc.json`, runs `ads check`, executes
+core/project Oxlint rules, then generates configured standard brand icons in
+`.ds/assets/`. Set `assets.iconSource` to an SVG inside the ADS's `assets/brand/`,
+relative to the ADS folder; no source means generation is a no-op. Integrate that
+directory through the app's existing asset mount. Fixed token names and prefixes
+are required; project values and artwork remain project-owned. Its paths reference the project and local tool;
+builds do not depend on the initializing npx cache. Ignore `.ds/`. Register
+component rules through the project's plugin adapter and `ds.config.json`, then
+run its actual build. Use `lint-config` directly for custom pipeline integration
+or debugging, not as a separate routine setup step.
+
+Use ADS 0.3 or later for the shared-resource preview compiler. `mcp` starts stdio
+plus its local website; `showcase` starts the browser-only MCP runtime. Open the existing runtime URL from `ads_status` when
+connected; otherwise use `npm run dev:showcase` or the installed `ads showcase`.
+The tool client discovers entries and renders MCP Apps. Init adds the launch
+script but does not install the project preview compiler. Integrate its graph
+compiler/mount adapter and configure `mcp.previewManifest` plus `mcp.previewWatch`;
+then use the same foundation and Linaria extraction as the application. Source discovery,
+selected component/pattern/style/brand imports, explicit theme-value imports, and
+assimilation are agent workflows. There is no CLI `import` command. Core checks
+do not copy source, import values, or establish behavior/motion parity; continue
+project type checking, meaningful tests, and browser comparisons.
+
+If no CLI distribution is available, continue with the target's existing
+checks. `ads-designer` includes an empty scaffold for offline bootstrapping.
+Install skills separately with `npx skills`; the tool does not install skills
+or fetch an external UI catalogue.

package/dist/skills/ads-import/references/implementation.md

@@ -0,0 +1,111 @@
+# Selected implementation import
+
+## Follow the real dependency closure
+
+Start at each selected public export and inspect its imports, re-exports, side
+effects, styles, hooks, providers, state stores, helpers, types, and assets.
+Include transitive prerequisites even when the user selected only one component.
+Copy into the destination's local ADS source, which the project owns. Configure
+its local public alias (such as `@ds`) rather than installing the source ADS as
+an application dependency.
+A pattern may depend on several primitives; explain those additions as required
+dependencies rather than importing the whole catalogue.
+
+Check source contracts before replacing a dependency with a target equivalent.
+A similarly named Button, Icon, or hook can have different props, dimensions,
+focus behavior, or semantics. Prefer an existing equivalent when it preserves
+the selected item's contract. Otherwise import the required dependency or make
+a documented compatible adapter in the appropriate target layer.
+
+Inspect external package imports and source dependency versions. Add only what
+the closure needs, compatible with the target's peer/framework versions. Merge
+package changes through the target's dependency manager and lockfile. Integrate
+essential CSS extraction, assets, or code generation without replacing the
+whole build configuration. External runtime dependencies of the copied code
+remain real dependencies;
+do not disguise a wrapper as a fully native independent implementation.
+
+Do not copy real product data, routes, network services, or application imports
+into reusable primitives/patterns. Use documented slots, props, and callbacks
+to separate those concerns. If a required service or provider cannot be integrated
+within the request, identify that concrete limit instead of adding a silent stub.
+
+## Keep styles in their owning layers
+
+Copy colocated component/pattern styles with their implementation. Import style
+helpers or presets into the owning ADS layer and document their public setup.
+If a requested style is only used through specific markup, include or adapt the
+needed contract rather than presenting an inert stylesheet as a working import.
+
+Follow ADS styling and namespace ownership. The default layout is:
+
+- Primitives live under `design-system/components/` and own `ads-*` classes.
+- Reusable layouts live under `patterns/` and own `ux-*` classes.
+- Linaria blocks use `@linaria/atomic`; public foundation CSS is import-only.
+- Public scenario review layouts are patterns with `ux-*` classes; fixtures define
+  no CSS or custom classes and consume public ADS entities.
+- Runtime measured geometry stays narrow; visual constants stay in tokens.
+
+Source implementations may use another styling engine or framework. Adapt
+styles to the destination's required Linaria pipeline and ownership boundaries,
+retaining state mechanics, layout relationships, and motion choreography. Token-backed dimensions, easing, and durations follow
+the chosen value policy; record resulting theme differences. Do not implement
+imported visual policy as consumer overrides targeting
+internal classes or as new app-level CSS.
+
+Export the selected API and required public types through the target barrel.
+Resolve export-name collisions explicitly; do not silently replace an unrelated
+target component. Update assets and internal imports for their new locations.
+Demonstrate the actual imported item through public exports in the target showcase.
+
+## Documentation, provenance, and lint
+
+Keep detailed usage/API/setup, lifecycle, interactions, token hooks, and validation
+in the component or pattern's local README. For styles, document supported
+selectors/markup, theme scope, and application through the public entry.
+Describe material target integration differences alongside the source contract.
+
+Include source repository/file links, resolved revision and ADS path, authors,
+and what was copied or adapted. Preserve the source item's own inspiration and
+upstream credits. Keep applicable license/copyright notices for copied code and
+assets in accessible local files and reference them from the guide. Do not call
+copied/adapted source an independently authored reproduction. Shared ADS docs own
+the shared token contract, value-import policy, and links to item guides.
+
+Inspect source component-local lint rules and their tests when present. Import
+applicable rules into tooling-only ownership and register them through the
+target's maintained configuration/generator. Adjust real public import names,
+aliases, root-file configuration, and plugin registration. Keep rule modules and
+test harness dependencies outside runtime exports.
+
+Do not assume the source's global lint configuration applies to the destination.
+Add a new rule only for concrete, statically provable misuse not already covered
+by existing checks. Test accepted and rejected consumer cases and false-positive
+boundaries when rules are changed or adopted.
+
+## Verification and evidence
+
+Run the destination's lint/typecheck/build and meaningful selected-item tests.
+Adapt source tests to the target public API and test environment without dropping
+behavioral assertions just to pass. Verify asset resolution, declarations, public
+imports, setup/providers, and scope/mounting across routes where relevant.
+
+Compare the imported component or pattern with the actual source implementation
+at the recorded revision. Align content, configuration, themes, viewport, and
+input modality. For implementation comparisons, use matching token values when
+possible; also verify the item under its actual destination theme. For
+stateful/motion-heavy items, check lifecycle, focus, keyboard,
+pointer and touch, natural dimensions, transitions, interruption, reduced motion,
+and cleanup as relevant. Separate token/font differences from implementation
+drift. Build success does not establish gesture or animation parity.
+
+Use isolated browser pages/contexts and temporary comparison projects. Do not
+resize or navigate the user's existing tabs for tests. Rebuild `dist`-based
+fixtures after source changes. Stop comparison servers after verification unless
+the user asked to keep them; preserve requested demos until asked to stop them.
+
+Report the selected items, added prerequisites, token-contract additions and
+value policy, source revision, documented adaptations, notices, and checks
+actually run. Distinguish observed parity from source inference and untested
+states. Token-values-only mode has
+no selected runtime items, but still needs token and existing-consumer validation.