@reqvire-org/ads 0.3.5 → 0.3.7

package/docs/MCP.md

@@ -171,6 +171,9 @@ The server supplies agent guidance through its instructions, tool descriptions,
 | `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 |
 
@@ -185,6 +188,16 @@ 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.
 
+`ads_check` and `ads://project/checks` return nonblocking atomic composition
+warnings under `advisories` with `severity: "warning"`, related source declarations
+and `guidanceUri: "ads://guides/atomic-styles"`. Read that guide for causes and
+component-level fixes. The full guide lives in every ADS skill as
+`references/atomic-styles.md` for standalone clients; MCP serves the packaged
+[skill-local reference](../skills/ads-designer/references/atomic-styles.md).
+Guarded mutation results preserve these warnings without rejecting valid source.
+An overlap warning is a review signal; failed registered rendered checks remain
+blocking.
+
 ### Behavioral verification
 
 Read `ads://guides/behaviors` or the [behavior guide](BEHAVIORS.md) for the contract
@@ -220,8 +233,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
@@ -231,6 +245,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
@@ -256,6 +272,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:
 
@@ -310,6 +328,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
@@ -326,8 +385,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
@@ -557,7 +616,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reqvire-org/ads",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "type": "module",
   "description": "A design system your agent can see and shape. Your components. Your look. Your code.",
   "repository": {
@@ -34,8 +34,10 @@
     "generate:icons": "node scripts/generate-icons.mjs",
     "sync:skill-starter": "node scripts/sync-skill-starter.mjs",
     "check:skill-starter": "node scripts/sync-skill-starter.mjs --check",
+    "sync:skill-references": "node scripts/sync-skill-references.mjs",
+    "check:skill-references": "node scripts/sync-skill-references.mjs --check",
     "lint": "npm run lint:tool",
-    "lint:tool": "npm run check:skill-starter && oxlint --deny-warnings src preview-client showcase-client mcp-explorer tests/*.test.mjs scripts/build-ads-tool.mjs scripts/pack-ads-tool.mjs",
+    "lint:tool": "npm run check:skill-starter && npm run check:skill-references && oxlint --deny-warnings src preview-client showcase-client mcp-explorer tests/*.test.mjs scripts/build-ads-tool.mjs scripts/pack-ads-tool.mjs scripts/sync-skill-references.mjs",
     "lint:project": "npm run lint:ds && npm run lint:style && npm run check:skill-starter",
     "lint:ds": "node dist/cli.mjs lint-config && node dist/cli.mjs check && oxlint --deny-warnings --config .ds/oxlintrc.json src design-system",
     "lint:style": "biome lint --config-path=biome.css.json .",