@reqvire-org/ads 0.3.12 → 0.3.13

package/docs/GUIDE.md

@@ -5,7 +5,54 @@ contains a Node CLI, shared token contract, static checks, an Oxlint plugin, and
 empty foundation scaffolding. It includes no component or pattern catalogue,
 fonts, mock screens, or UI runtime dependency.
 
-
+## Use ADS through MCP
+
+Connect your coding agent using the [MCP client setup](MCP.md#connect-codex-or-claude).
+The client launches `ads mcp` in your project; add `--mutations` to enable guarded
+source editing. Initialization also supplies `ads-mcp` and `ads-read-mcp` launch
+scripts. The server starts its showcase and configured preview compiler, so use
+the returned showcase URL rather than starting a separate preview application.
+
+An agent uses the MCP tools to inspect, edit and review the project:
+
+1. Call `ads_status` to identify the connected project, available commands,
+   mutation mode, showcase URL and build freshness.
+2. Find public UI/behavior APIs with `ads_catalog`, inspect relevant definitions
+   with `ads_tokens`, and discover preview IDs with `ads_scenarios`. Read one
+   relevant workflow through `ads_skills` and `ads_read_skill` before editing.
+3. Open a discovered preview with `ads_show_scenario` or `ads_show_tokens`. These
+   render the project's actual scenario, fixtures and adapter through MCP Apps.
+   Use the returned showcase link when the client cannot render Apps.
+4. When editing is enabled, discover ownership with `ads_units`, read relevant
+   source through `ads_read_file`, and submit an owner Git patch through
+   `ads_apply_patch`. Use `ads_apply_transaction` for genuinely coupled owners.
+   Prepare/diff a local draft with `ads_prepare_patch` when useful. Dry-run first;
+   ADS checks an isolated candidate before any live source is written.
+5. Review diagnostics, registered behavior evidence and the rendered result.
+   `ads_behaviors` discovers guarantees; `ads_verify` executes selected registered
+   checks. Recheck `ads_status.build` after changes; notifications alone do not
+   establish current output.
+
+For an on-demand screenshot, call `ads_capture` with a discovered scenario ID and
+optionally a named `captureTargets` element, theme and viewport. To compare a
+proposed change before applying it, add `screenshot:true` and an explicit
+`captures:[{scenario:"<discovered ID>"}]` selection to the patch/transaction dry run.
+Normal patches and dry runs create no screenshots. Capture uses project-installed
+Playwright and its browser; ADS installs neither.
+
+Read `ads://project/captures` and the returned PNG image URIs through MCP
+`resources/read`. Each target keeps only current and candidate: a successful
+standalone screenshot replaces current and clears candidate; a screenshot-enabled
+dry run replaces the pair; applying matching source promotes candidate. Source
+changes mark images stale. There is no previous slot, history or TTL.
+`ads_capture_clear` discards candidate or clears both images. Subscribe to resource
+updates when supported, and explicitly reread otherwise. Screenshots provide visual
+evidence for one state; they do not replace behavior checks.
+
+The [MCP guide](MCP.md) details tool/resource schemas, prompts, skills and
+notifications. The portable [capture guide](../skills/ads-designer/references/captures.md)
+explains screenshot setup, named targets, limits and comparison usage; MCP serves
+the same guide at `ads://guides/captures`.
 
 ## Implementation support
 

package/docs/MCP.md

@@ -177,6 +177,8 @@ The server supplies agent guidance through its instructions, tool descriptions,
 | `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_capture` | On-demand PNG of a discovered scenario or named element; replace current and clear candidate |
+| `ads_capture_clear` | Remove generated captures or discard only the candidate |
 | `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 |
@@ -212,6 +214,36 @@ informational limit nor a traced target proves a rendered failure or success.
 Bounded check results put warnings before informational limits; the checks
 resource retains complete results.
 
+### Screenshots and candidate comparison
+
+`ads_capture({scenario:"<discovered ID>",target?,theme?,viewport?})` renders current
+source in the real sandboxed App using project-local Playwright/browser. It returns
+PNG resource URIs and revision/settings metadata. The default is the full widget
+viewport; optional `captureTargets` metadata names an element within the scenario.
+Token/component/pattern/composition scenarios share this path. The tool adds no
+project-specific renderer or fixture assumptions.
+
+Patch and transaction dry runs accept `screenshot:true` plus an explicit 1–8-entry
+`captures:[{scenario,target?,theme?,viewport?}]` selection. Existing gates run first;
+current and candidate use matching capture settings. Source/conflict checks remain
+mandatory. No screenshots are created by ordinary patches/dry runs. A newly added
+scenario has a candidate with an explicit absent current baseline.
+
+`ads://project/captures` lists current/candidate slots, metadata and freshness.
+Read returned `ads://captures/{key}/{slot}` resources as `image/png` binary content;
+the resource template is advertised without per-revision catalogue growth.
+Subscriptions receive `resources/updated` for replacement/removal. Successful
+standalone capture replaces current and clears any prior candidate. Applying
+matching proposed source promotes candidate; explicit `ads_capture_clear` can
+discard the candidate or both slots. There is no previous/history/TTL. Source
+changes mark stale images; deleted targets are collected. Capture data is bounded
+generated output under `.ds/captures/`, not a source mutation or behavior pass.
+
+Optional `mcp.capture` selects browser, Chromium channel and runner timeout.
+ADS installs no browser dependencies. See `ads://guides/captures` or the portable
+[capture reference](../skills/ads-designer/references/captures.md) for setup, precise
+limits, target declarations and the guarded review workflow.
+
 ### Behavioral verification
 
 Read `ads://guides/behaviors` or the [behavior guide](BEHAVIORS.md) for the contract
@@ -229,6 +261,15 @@ 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.
 
+During a run, `ads_status.behaviors.progress` exposes completed/active/pending
+checks, timings and the profile's whole-run timeout. Candidate mutation checks use
+`ads_status.mutations.progress`. Requested MCP progress notifications also report
+runner activity. Playwright uses the project's workers and filters selected case
+tags; ADS does not silently change timeout or parallelism policy. Timeout results
+retain partial outcomes and reports under `.ds/verification/`, but incomplete
+runs still block application and cannot establish passing guarantees. See the
+[runner and evidence details](BEHAVIORS.md#register-execution-profiles).
+
 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
@@ -361,7 +402,14 @@ 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.
+Pass that `patchFile` to `ads_apply_patch` with `dryRun:true` to validate before
+applying. This runs the normal candidate gates, including affected registered
+behavior checks against an isolated candidate and its configured browser preview.
+It writes no live source and does not persist passing evidence for live inputs.
+Read returned `behavior` failures or behavior-check results in `checks`; update the
+draft, diff again and repeat as needed. Apply with `dryRun:false` after validation;
+the gates run again. `ads_verify({unit,checks?})` checks current source and accepts
+no draft argument; a selected-check draft runner is not currently exposed.
 Use `action:"discard"` to remove the draft. Remote clients can continue sending
 inline Git diffs. Drafts are local conveniences, not an alternative mutation API.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reqvire-org/ads",
-  "version": "0.3.12",
+  "version": "0.3.13",
   "type": "module",
   "description": "A design system your agent can see and shape. Your components. Your look. Your code.",
   "repository": {