@reqvire-org/ads 0.3.3 → 0.3.6

package/docs/MCP.md

@@ -17,7 +17,11 @@ 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.
+available one. For a stable address, add `"--port", "4191"` to the server's `args`
+in `.mcp.json` (or the corresponding client configuration). An occupied explicit
+port fails startup; ADS does not silently switch ports or terminate another live
+client. Reuse the connected server's showcase instead of launching another 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.
@@ -155,7 +159,7 @@ The server supplies agent guidance through its instructions, tool descriptions,
 | 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_catalog` | Bounded search for public UI, controllers and hooks, with 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 |
@@ -163,22 +167,53 @@ The server supplies agent guidance through its instructions, tool descriptions,
 | `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_behaviors` | Bounded guarantee/evidence discovery; pass an exact unit for contract details |
+| `ads_verify` | Execute an owner's registered checks and record revision-bound evidence |
 | `ads_show_<id>` | Optional explicitly configured grouped App |
 | `ads_units` | Discover edit owners and the files belonging to one unit |
+| `ads_prepare_patch` | Prepare a local draft of one owner, then generate its Git patch |
+| `ads_prepare_token_samples` | Reconcile real-token fixture samples using explicit project bindings |
+| `ads_apply_transaction` | Validate and apply coupled owner patches as one final candidate |
 | `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
+public exports from `components/`, `patterns/` and `controllers/`; 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
+`ads://project/status`, `/build`, `/tokens`, `/catalog`, `/scenarios`, `/behaviors`, 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.
 
+### Behavioral verification
+
+Read `ads://guides/behaviors` or the [behavior guide](BEHAVIORS.md) for the contract
+and runner schema. `ads_behaviors({ "unit": "components/MessageScroller" })`
+returns subjects, guarantees, demonstration links and check IDs for a discovered
+owner. `ads_verify({ "unit": "components/MessageScroller", "checks": ["prepend-anchor"] })`
+runs those registered cases. The names here are examples, never built-in cases.
+
+`covers` describes rendered UI; optional `exercises` describes public behavioral
+APIs used through reachable scenario code. Neither metadata nor README prose is
+passing evidence. Verification runs trusted project commands from configured
+profiles, without installing dependencies. It is available in read-only source
+mode too and is annotated as executing commands/writing generated evidence.
+Missing/skipped cases, unavailable runners and changed inputs cannot pass.
+Results and subscribed resource notifications are available through
+`ads://project/behaviors`; explicitly re-read evidence when notifications are absent.
+
+Browser profiles start an isolated showcase and verify its sandboxed App using
+the selected candidate's sources. StrictMode profiles need a project React
+development harness. Profiles describe the execution environment, not a proof
+that every possible interaction or lifecycle has been tested.
+
+Guarded mutations also run affected registered behavior checks, including contracts
+that depend on changed shared controllers. Failures reject the candidate before
+writing real source. Projects without contracts retain their existing checks.
+
 ## Guarded editing
 
 Enable editing in the MCP launch arguments and reconnect:
@@ -188,8 +223,9 @@ 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.
+is disabled by default. The default editing tool accepts **one Git unified diff
+for one ADS unit**. Replacement file bodies are not mutation inputs. Genuinely
+coupled changes use the bounded owner transaction described below.
 
 Find the owner with `ads_units({ "query": "Button" })`, then request its file
 manifest with `ads_units({ "unit": "components/core/Button" })`. IDs derive from
@@ -199,6 +235,8 @@ 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`.
+Unit-local token definitions and their previews stay in their component/pattern
+owner; see [owner tokens](ADS.md#owner-local-tokens).
 
 The `tokens` manifest also returns `companionFiles` with the configured foundation
 entry path. When creating or deleting a canonical token foundation file, include
@@ -224,6 +262,8 @@ name) or colocated fixture keeps ownership stable without `Scenario.tsx`.
 A redundant standalone scenario can be removed when other registered scenarios
 still declare and actually render its public exports. Coverage requirements remain
 in force; there is no metadata waiver for uncovered UI.
+An empty `.gitkeep` may be deleted alongside new source in the selected owner
+beneath that marker. Other hidden files and nonempty markers remain blocked.
 
 The same discovery covers the rest of the project ADS:
 
@@ -278,6 +318,47 @@ not an edit to live ADS source. Binary `ads_read_file` results return the digest
 byte count without encoded content. Git verifies the original binary blob and
 reconstructs the result inside the validation copy.
 
+For local editing without a second Git mirror, call
+`ads_prepare_patch({unit, action:"create"})`. It returns a draft ID and a local
+directory containing only the owner and declared companions. Edit that directory
+using the client's local file tools, then call
+`ads_prepare_patch({unit, action:"diff", draft})`. It checks source/baseline
+freshness and owner paths and returns a `patchFile`; it changes no live source.
+Apply the result through `ads_apply_patch`, which runs the normal candidate gates.
+Use `action:"discard"` to remove the draft. Remote clients can continue sending
+inline Git diffs. Drafts are local conveniences, not an alternative mutation API.
+
+`ads_prepare_token_samples({id, bindings?})` reconciles the selected token
+scenario's consumed literal sample array. Existing bindings and other fixture
+fields are preserved; undeclared samples are removed. New bindings explicitly
+name a real `token`, CSS `property` and `probe`. Missing mappings are reported as
+`unresolved`; ADS never guesses a property or renderer from the token name.
+The result is an owner patch file for guarded application. This preparation does
+not establish rendered effects or waive token coverage.
+
+For a coupled rename or upgrade, call `ads_apply_transaction`:
+
+```json
+{
+  "patches": [
+    { "unit": "tokens", "patchFile": ".ds/patches/tokens.patch" },
+    { "unit": "components/Button", "patchFile": ".ds/patches/button.patch" }
+  ],
+  "dryRun": true
+}
+```
+
+It accepts 2–8 distinct owners, at most 32 distinct files and 16 MiB of combined
+Git diff text. Each patch obeys its own ownership/companion rules. Patches apply
+in order inside one candidate; shared-entry hunks in a later patch must match
+the earlier candidate's content. Core checks, registered Oxlint, project commands
+and all affected behavior checks run against the final candidate. No intermediate
+candidate is published. Dry runs, failures, conflicts and cancellation write no
+source; a publication failure rolls back prior writes. This coordinates owned
+source migrations, not dependency installation or arbitrary application files.
+Install changed dependencies before verification; candidates use the project's
+installed `node_modules`.
+
 Resolve ownership diagnostics by preserving the required capability in its proper
 layer. Demo-only sizing, borders and framing belong in a public review/layout
 pattern; a component API addition needs a runtime use case. Measured imperative
@@ -294,8 +375,8 @@ a new directory owner, or change unrelated public-entry statements. Shared
 public-entry changes are limited to re-exports from the selected unit. Alongside
 its real re-export, a patch can remove an obsolete `export {};` placeholder;
 it cannot add one or change unrelated statements. Init generates no empty-export
-placeholder. Report unsupported coupled changes rather than bypassing a rejected
-mutation with direct source writes.
+placeholder. For coupled owners use the bounded transaction; a rejection still
+requires correcting its owner/policy, never a direct-write bypass.
 
 Set `dryRun` to `false` to apply. ADS reconstructs complete candidate files locally
 and validates a temporary project copy with core guards and registered Oxlint
@@ -525,7 +606,13 @@ 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
+merely finding an older HTML file is insufficient. Managed resource graphs and
+HTML descriptors use private session output; standalone build commands retain
+the configured output. One cannot overwrite the other's success record. The
+compiler caches at most six verified graph snapshots under `.ds/preview-graphs/`
+and cleans its session output on ordinary shutdown. These are generated files;
+do not track or use them as source. Legacy self-contained HTML builders retain
+their existing publication contract. 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. Invalid scenario metadata at startup and
@@ -540,8 +627,15 @@ Managed configuration changes replace the compiler through the same supervisor.
 Updating ADS server code itself still requires reconnecting the MCP client to load
 the new package. 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,
+ADS closes both network hosts and stops the managed watcher and its compiler
+subprocesses when the stdio wire closes, including EOF or broken output, or it
+receives SIGINT/SIGTERM. Active browser subscriptions do not retain the runtime.
+A small independent ownership guard watches a pipe from MCP; owner death closes
+that pipe even after SIGKILL. The guard terminates the owned compiler process
+group, escalates for stubborn descendants, then exits. It is disarmed on ordinary
+shutdown; `previewWatch.guardPid` identifies it while running. This requires no
+second user command and applies to custom builders too.
+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
@@ -680,7 +774,7 @@ See the [MCP Apps specification](https://github.com/modelcontextprotocol/ext-app
 | 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.
+`ads-migrate` 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reqvire-org/ads",
-  "version": "0.3.3",
+  "version": "0.3.6",
   "type": "module",
   "description": "A design system your agent can see and shape. Your components. Your look. Your code.",
   "repository": {
@@ -69,6 +69,7 @@
     "@modelcontextprotocol/client": "2.3.1",
     "@modelcontextprotocol/ext-apps": "2.0.3",
     "@modelcontextprotocol/sdk": "1.32.1",
+    "@playwright/test": "1.64.1",
     "@preact/signals": "2.11.3",
     "@types/node": "^25.9.2",
     "@types/react": "^19.2.17",
@@ -98,7 +99,8 @@
     "./mcp/build": "./dist/mcp/build-status.mjs",
     "./scenarios": "./dist/scenarios.mjs",
     "./scenarios/vite": "./dist/scenarios-vite.mjs",
-    "./scenarios/compiler": "./dist/scenarios-compiler.mjs"
+    "./scenarios/compiler": "./dist/scenarios-compiler.mjs",
+    "./verification": "./dist/verification/browser.mjs"
   },
   "files": [
     "dist",

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

@@ -1,4 +0,0 @@
-interface:
-  display_name: "ADS Assimilate"
-  short_description: "Adapt reference components into a native design system"
-  default_prompt: "Use $ads-assimilate with a component-library URL to implement and verify a native design-system component."