diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json
index 000eba6..6a390e8 100644
--- a/.cursor-plugin/plugin.json
+++ b/.cursor-plugin/plugin.json
@@ -14,9 +14,12 @@
     "design-system",
     "design-tokens",
     "mcp",
-    "documentation"
+    "documentation",
+    "dsds",
+    "audit"
   ],
   "logo": "assets/logo.svg",
   "rules": "cursor/rules",
+  "skills": "skills",
   "mcpServers": "cursor/mcp.json"
 }
diff --git a/README.md b/README.md
index d88e8f1..38f8640 100644
--- a/README.md
+++ b/README.md
@@ -15,6 +15,10 @@ What's included:
 - **MCP server** (`cursor/mcp.json`): the connection to zeroheight.
 - **Rule** (`cursor/rules/zeroheight.mdc`): nudges the AI to treat your
   styleguide as the source of truth and look things up before writing UI code.
+- **DSDS audit** (`skills/dsds-audit/`): audits your styleguide's documentation
+  for machine-readability against the
+  [Design System Documentation Spec](https://designsystemdocspec.org) — see
+  [DSDS audit skill](#dsds-audit-skill).
 
 Install it from the Cursor plugin store, or point Cursor at this repository.
 
@@ -57,14 +61,56 @@ What's included:
 - **MCP server** (`claude-code/.mcp.json`): the connection to zeroheight. Claude
   Code surfaces the server's own guidance automatically, so it treats your
   styleguide as the source of truth when working on UI.
+- **DSDS audit** (`skills/dsds-audit/`, `/audit-docs`): audits your
+  styleguide's documentation for machine-readability — see
+  [DSDS audit skill](#dsds-audit-skill).
 
 Add this repository as a plugin marketplace, then install the plugin:
 
 ```
-/plugin marketplace add zeroheight/ai-plugins
-/plugin install zeroheight-mcp@zeroheight
+claude plugin marketplace add zeroheight/ai-plugins
+claude plugin install zeroheight-mcp@zeroheight
 ```
 
+To audit your docs:
+
+```
+/audit-docs
+/audit-docs just Components
+```
+
+Or just ask — e.g. "audit our design system docs for machine-readability".
+
+## Claude desktop app (Cowork)
+
+1. Open the **Plugins** panel (the **+** menu → **Plugins** → **Manage Plugins**).
+2. Choose **Add** → **Marketplace** → **Add from a repository** and enter
+   `zeroheight/ai-plugins`.
+3. Find **zeroheight-mcp** in that marketplace and click **Install** (then
+   enable it if it isn't enabled automatically).
+
+The first time you use the plugin, a browser opens so you can sign in with
+your zeroheight account.
+
+## DSDS audit skill
+
+The `skills/dsds-audit/` skill audits your styleguide's documentation for
+machine-readability against the
+[Design System Documentation Spec](https://designsystemdocspec.org) by
+[PJ Onori](https://pjonori.blog), and returns a prioritised, page-by-page list
+of authoring moves plus ready-to-paste segments.
+
+It ships inside the Cursor and Claude Code plugins above, but you can also
+install it on its own into any agent that supports skills using the
+[skills CLI](https://skills.sh):
+
+```
+npx skills add zeroheight/ai-plugins
+```
+
+The skill needs the zeroheight MCP connection to read your styleguide, so
+install one of the plugins above (or connect the MCP server yourself) first.
+
 ## Usage
 
 Once connected, just ask the AI about your design system:
diff --git a/claude-code/.claude-plugin/plugin.json b/claude-code/.claude-plugin/plugin.json
index 5a19945..1e98631 100644
--- a/claude-code/.claude-plugin/plugin.json
+++ b/claude-code/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "zeroheight-mcp",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Use your design system directly in Claude Code. Search components, retrieve implementation guidance, and generate code that reflects your design system.",
   "author": {
     "name": "zeroheight",
@@ -14,6 +14,8 @@
     "design-system",
     "design-tokens",
     "mcp",
-    "documentation"
+    "documentation",
+    "dsds",
+    "audit"
   ]
 }
diff --git a/claude-code/commands/audit-docs.md b/claude-code/commands/audit-docs.md
new file mode 100644
index 0000000..867a21c
--- /dev/null
+++ b/claude-code/commands/audit-docs.md
@@ -0,0 +1,21 @@
+---
+description: Audit a zeroheight design system's docs for machine-readability against DSDS 0.12.0 and produce a prioritised, page-by-page list of authoring moves plus ready-to-paste segments.
+argument-hint: "[styleguide or page scope, e.g. \"just Components\"]"
+---
+
+Run the **dsds-audit** skill to audit the user's zeroheight design system documentation
+against the Design System Documentation Spec (DSDS, pinned to 0.12.0).
+
+Scope for this run (optional, may be empty): $ARGUMENTS
+
+Follow the skill's procedure exactly:
+
+1. Confirm the **zeroheight MCP is connected** (tools `list-pages`, `search-pages`,
+   `get-page`, `list-releases`, `get-page-asset`). If it is not, stop and tell the user
+   to set their personal zeroheight remote MCP URL — see the plugin README. Do not
+   substitute a generic checklist.
+2. Read all six source files in the skill (`reference/` + `templates/`) before auditing.
+3. If a scope was given above, audit that subset; otherwise call `list-pages` and confirm
+   scope with the user before auditing everything.
+4. Produce the two deliverables the skill specifies: the Markdown audit report and the
+   companion `paste-pack.html`. Omit `[Platform]` findings entirely.
diff --git a/claude-code/skills b/claude-code/skills
new file mode 120000
index 0000000..42c5394
--- /dev/null
+++ b/claude-code/skills
@@ -0,0 +1 @@
+../skills
\ No newline at end of file
diff --git a/skills/dsds-audit/SKILL.md b/skills/dsds-audit/SKILL.md
new file mode 100644
index 0000000..22901df
--- /dev/null
+++ b/skills/dsds-audit/SKILL.md
@@ -0,0 +1,181 @@
+---
+name: dsds-audit
+description: >-
+  Audit a zeroheight design system's documentation for machine-readability
+  against the Design System Documentation Spec (DSDS, designsystemdocspec.org).
+  Use this whenever someone wants to check, score, or improve how parseable,
+  structured, or "agent-ready" / "AI-ready" their zeroheight docs are — phrases
+  like "audit our design system docs", "are our docs machine-readable", "check
+  our styleguide against DSDS", "how AI-ready is our documentation", "what should
+  we change to make our components parseable", or "run a DSDS conformance check".
+  Reads the live styleguide through the zeroheight MCP, classifies each page to a
+  DSDS entity, and produces a granular, prioritised list of the exact changes to
+  make. Use it even if the user doesn't say "DSDS" by name but is asking about
+  documentation structure, machine/agent readability, or design-system docs QA.
+---
+
+# DSDS machine-readability audit
+
+This skill audits a design system documented in **zeroheight** against the
+**Design System Documentation Spec (DSDS)** and returns a concrete, page-by-page
+list of changes that would make the docs machine-readable — parseable by tools and
+consumable by agents, not just readable by people.
+
+It targets a **pinned DSDS version** (currently **0.12.0**) so results are
+reproducible. The spec is a draft and changes; this skill audits against the
+frozen model in `reference/`, not against the live site.
+
+**The core principle:** zeroheight authors cannot emit DSDS JSON — they write
+pages. But DSDS's value isn't the JSON syntax, it's the conventions it enforces
+(stable names, controlled vocabularies, consistent tables, explicit relationships,
+testable statements), and every one of those is authorable in zeroheight. So this
+audit never tells a customer to "add an `identifier` field." It recommends the
+**zeroheight authoring move** that produces the same machine-readable effect, names
+the DSDS intent behind it, and tags who can act ([Author] / [Platform] / [New
+content]). Findings only zeroheight can fix stay out of the customer action list.
+
+## What you need
+
+- The **zeroheight MCP** connected (tools `list-pages`, `search-pages`,
+  `get-page`, `list-releases`, `get-page-asset`). It exposes the user's styleguide.
+- The reference files in this skill:
+  - `reference/dsds-0.12.0-model.md` — the entity/block/criteria model, pinned.
+  - `reference/entity-block-rules.md` — which blocks each entity accepts and the
+    structured shape each needs (the DSDS-intent layer behind the moves).
+  - `reference/zeroheight-mapping.md` — how to classify a zeroheight page to a DSDS
+    entity kind and map its sections onto blocks.
+  - `reference/zeroheight-authoring-pattern.md` — **the heart of the audit**: each
+    DSDS construct translated to the next-best zeroheight authoring move, the
+    controlled vocabularies, and the "For Agents" tab spec. Recommendations come
+    from here.
+  - `reference/rubric.md` — the Pass/Partial/Missing rating, who-can-act tagging,
+    P1/P2/P3 severity, scoring, and how to phrase findings.
+  - `templates/audit-report.md` — the deliverable structure.
+
+Read all six before auditing. They are the source of truth; do not audit from
+memory of the spec, do not invent block kinds or levels, and do not recommend a
+change a customer can't make in the zeroheight editor.
+
+If the zeroheight MCP is not connected, stop and tell the user — the audit reads
+their live docs and cannot run without it. Don't substitute a generic checklist.
+
+## Procedure
+
+### 1. Scope the audit
+Call `list-pages` to get the styleguide name and full navigation tree. Confirm
+with the user: audit the whole styleguide, or a subset (e.g. just Components)?
+For large systems, agree a scope rather than silently auditing everything. If the
+user wants a specific release, use `list-releases` first, then pass that
+`releaseId` consistently to `list-pages` and `get-page` (page IDs differ per
+release).
+
+### 2. Read each page
+For each in-scope page, call `get-page` and read the returned Markdown. Don't
+infer content from the navigation title — open the page. Image annotations are
+coordinate metadata only; you can list anatomy labels but not infer what they
+point at without the image, so note that limit rather than guessing
+(see `reference/zeroheight-mapping.md`).
+
+### 3. Classify to a DSDS entity
+Using `reference/zeroheight-mapping.md`, assign each page a `kind`
+(component / token / token-group / theme / foundation / pattern / guide). Record
+the classification and flag any page that's ambiguous or spans two kinds — let a
+human correct it rather than burying the uncertainty. Intros, changelogs, and
+"welcome" pages are `guide`s, not broken components.
+
+### 4. Rate against the authoring moves
+Map the page's sections to DSDS blocks (`zeroheight-mapping.md`), then run the
+entity's check set from `reference/rubric.md`, scoring against the **zeroheight
+authoring moves** in `reference/zeroheight-authoring-pattern.md`. For each check:
+
+- **Pass** — the authoring move is in place; the MCP extracts it reliably.
+- **Partial** — content present but not via the move; not parseable.
+- **Missing** — absent.
+- **N/A** — doesn't apply to this kind.
+
+Tag every finding **[Author]** / **[Platform]** / **[New content]**. Drop
+**[Platform]** items from the action list (appendix only). Most real findings are
+**Partial, [Author]** — the writing is good, the convention is missing. Phrase that
+as "you're close, here's the move," not failure. Look specifically for the recurring
+high-value gaps: colliding/duplicate titles, empty pages, raw hex instead of token
+names, no Level column on guidance, inconsistent props/variants tables, unnamed
+states/anatomy, no linked alternatives, and no For Agents tab.
+
+### 5. Make every finding a concrete authoring move
+This is the whole value of the audit. Never write "add a guidelines block." Write
+the specific zeroheight move, on the named page, referencing the page's own content,
+and name the DSDS intent:
+
+> **Button › Guidelines ([Author], P2, Partial).** "Use a link for navigation" and
+> "one primary per surface" are prose. Put them in a guidelines **table with a Level
+> column** — `Must not` / `Must` — reusing the Required/Encouraged pattern already
+> on your Color page. *DSDS intent: RFC 2119 levels so parsers separate hard rules
+> from soft.*
+
+Cite their own pages where a good pattern already exists (Color/Theming use a Level
+column; Button has a clean props table; the Component Status matrix has a status
+vocabulary) so findings read as "standardise what you already do." Order each page's
+findings P1 → P2 → P3 so a customer can work top-down and stop when budget runs out.
+
+### 6. Draft ready-to-paste snippets (Markdown report + paste pack)
+For each page, after the findings table, write a **Ready to paste** section: the
+actual segments to drop into the editor, built from the page's own content, one per
+actionable finding (`rubric.md` → "Draft ready-to-paste snippets"). Real content,
+never placeholders, never JSON. **Always draft a For Agents tab** when the page lacks
+one — fill it with the page's real hard rules, disambiguation, and acceptance
+criteria. This is what lets a customer update piece by piece while the MCP is still
+read-only.
+
+Produce the snippets in **two forms**:
+- In the Markdown report, as fenced code blocks (readable record).
+- In a companion **`paste-pack.html`** built from `templates/paste-pack.html` —
+  one `.card` per snippet, each `.snippet` containing rendered, semantic HTML
+  (`<table>`, `<h2>`, `<ul>`, `<a>`). This is the file customers actually copy from:
+  zeroheight ignores raw Markdown on paste (it reads only `text/plain`), but the
+  paste pack's Copy button puts real `text/html` on the clipboard so tables,
+  headings and lists keep their formatting.
+
+Remember the container limit, and state it in each card's note: pasting fills
+*content*, but zeroheight containers — a new **tab** (e.g. For Agents), callouts,
+Do/Don't blocks, token specimens — must be created in the editor UI first, then the
+body pasted in. Tables, headings, lists, bold, and links paste cleanly.
+
+### 7. Score and assemble the report
+Compute the per-page score (`rubric.md`), roll up to a styleguide average, but
+**lead with blocker counts and the author-actionable share, not the average** — one
+P1 outweighs five P3s. Surface the cross-cutting **system-level moves** first:
+conventions that, fixed once, collapse many per-page findings (standardise a Level
+column; pin the status vocabulary; add a For Agents tab everywhere). Include the
+**For Agents tab coverage** appendix since it's usually the biggest gap. **Omit
+[Platform] findings entirely — no "for zeroheight" section anywhere.** The report is
+the customer's to-do list; if they can't do it in the editor, it doesn't appear.
+Fill in `templates/audit-report.md`, save it as Markdown, and offer a .docx/.pdf
+version if they want something shareable.
+
+## Calibration
+
+- **Be honest, not generous.** A page of lovely prose with no structure is ~0–20%,
+  not 70%. The audit's worth is an accurate gap picture; an inflated score that
+  says "mostly there" when no parser can read the docs is worse than nothing.
+- **DSDS references token values, it doesn't store them.** Never flag "missing hex
+  values" — values live in the W3C DTCG file a token `source`-s to.
+- **Respect the entity/block rules.** A block on an entity that can't accept it is
+  a schema error (P1), distinct from a missing block.
+- **Stay located and specific.** Generic advice ("add identifiers everywhere") is
+  the failure mode to avoid; tie every change to a page and its content.
+
+## Output
+
+Two companion files:
+
+1. A **Markdown audit report** following `templates/audit-report.md`: executive
+   summary with the headline numbers, system-level moves, a budget-ordered sequence,
+   per-page findings tables (`check · rating · who · severity · the move`), each
+   page's Ready-to-paste snippets, and the For Agents coverage appendix. Granular
+   and actionable — the customer acts on it page by page.
+2. A **`paste-pack.html`** from `templates/paste-pack.html` — the same snippets
+   rendered with Copy buttons, so customers paste into zeroheight with formatting
+   intact while the MCP is read-only.
+
+Offer a .docx/.pdf of the report if they want something shareable. Never put
+[Platform] items in either file.
diff --git a/skills/dsds-audit/reference/dsds-0.12.0-model.md b/skills/dsds-audit/reference/dsds-0.12.0-model.md
new file mode 100644
index 0000000..1dcedb6
--- /dev/null
+++ b/skills/dsds-audit/reference/dsds-0.12.0-model.md
@@ -0,0 +1,115 @@
+# DSDS 0.12.0 — frozen reference model
+
+This is a pinned, condensed snapshot of the Design System Documentation Spec
+(DSDS) **0.12.0 draft**, captured for reproducible audits. The canonical source
+is https://designsystemdocspec.org/ and the JSON Schema at
+https://github.com/somerandomdude/design-system-documentation-schema
+(`spec/schema/dsds.bundled.schema.json`). DSDS is a draft and will change — when
+you bump the version this skill targets, re-snapshot this file and update the
+rubric, then re-tag the plugin.
+
+> Audit against the version recorded here, not against whatever is live. A moving
+> target makes audits non-reproducible, and customers need stable results they
+> can act on over several sprints.
+
+## What DSDS is (and isn't)
+
+DSDS is a JSON format that documents the *how and why* of a design system in a
+machine-readable shape — components, tokens, themes, foundations, patterns, and
+guides. It does **not** carry token *values*; that is the job of the W3C Design
+Tokens (DTCG) format, which DSDS links to via a token's `source`. An audit that
+flags "missing hex values" is misreading the spec — DSDS references values, it
+does not store them.
+
+The whole point is one source of truth that serves three readers: humans,
+parsers, and agents. Machine-readability means a parser or agent can reliably
+extract structure (types, levels, identifiers, relationships, testable criteria)
+without scraping prose.
+
+## Document shape
+
+A DSDS file requires `dsdsVersion` and one of:
+
+- `entity` — a single entity per file (the `kind` field names its type).
+- `entityGroups` — several entities in one file, or a manifest of `$ref`s to
+  single-entity files.
+
+```json
+{
+  "$schema": "https://designsystemdocspec.org/v0.12.0/dsds.bundled.schema.json",
+  "dsdsVersion": "0.12.0",
+  "entity": { "kind": "component", "identifier": "button", "name": "Button",
+    "description": "...", "metadata": { "status": "stable" },
+    "documentBlocks": [] }
+}
+```
+
+`systemInfo` (e.g. `systemName`) sits at the root of a multi-entity document.
+
+## Entity kinds (seven)
+
+| kind | what it documents |
+| --- | --- |
+| `component` | a reusable UI element (button, input, modal). Accepts anatomy, api, variants, states, design-specifications + general blocks. |
+| `token` | a single design token. Carries `tokenType` and a `source` pointer to the DTCG file. General blocks only. |
+| `token-group` | a nested tree of tokens (`children` may hold tokens or groups). General blocks only. |
+| `theme` | a named set of token `overrides` (dark, high-contrast, brand). Lists which token names change; DTCG holds the values. |
+| `foundation` | a design base (color, type, spacing, elevation). Accepts principles, scale, motion + general blocks. |
+| `pattern` | a multi-component solution to a user need (forms, empty states). Accepts interactions, anatomy, variants, states + general blocks. |
+| `guide` | a long-form reading document (getting-started, contribution, migration). Accepts steps, imports + general blocks. |
+
+## Common entity envelope
+
+Every entity shares: `kind`, `identifier`, `name`, optional `description` and
+`metadata`, plus `documentBlocks` and optional `agentDocumentBlocks`. (Tokens are
+the exception — they key off `tokenType`/`source` rather than rich prose.)
+
+- **`identifier` is the machine key, everywhere.** API properties, anatomy parts,
+  criteria, variants, states — the stable key is always `identifier`. `name` is
+  only ever a human display label. This distinction is the single most common
+  thing a human-authored docs page lacks.
+- **`metadata`** carries `status`, `category`, `tags`, `links`, `aliases`,
+  `since`, `last-updated`, `preview`/`thumbnail`.
+- **`status`** has exactly two shapes: a bare string (`"stable"`) or an object
+  with `overall` and optional per-`platforms` tracking. There is no `value` key.
+
+## documentBlocks vs agentDocumentBlocks
+
+`documentBlocks` is the default home — what a person reads; agents read it too.
+`agentDocumentBlocks` is an optional, agent-only array using the same block kinds,
+for firm ready-to-act notes that would be clutter for people: hard MUST / MUST-NOT
+rules, look-alike disambiguation, and runnable checks. Tools never show it to
+humans. A docs system that wants to be genuinely agent-ready uses this layer —
+its absence is a legitimate, high-value audit finding for systems targeting AI
+consumption.
+
+## The verification model (criteria)
+
+A `guideline` pairs `guidance` + `rationale` + an RFC 2119 `level`
+(`must` / `should` / `should-not` / `must-not`). Agents treat must / must-not as
+hard limits.
+
+A `criterion` turns a guideline into something checkable: a stable `identifier`
+plus a testable `statement`, an RFC 2119 `level`, and a `verification` mode:
+
+- `automated` — a runner decides; names a `check` (its `scheme` + config).
+- `assisted` — a tool surfaces candidates, a human decides.
+- `manual` — pure human judgement; `techniques`/`failures` are the procedure.
+
+When `verification` is omitted, tools must not assume the criterion is
+automatable. `examples` on a criterion are fixtures, each with an `outcome`
+(`pass`/`fail`). The `statement` is the source of truth; the `check` is its
+executable shadow.
+
+This criteria layer is what separates "documented guidance" from "enforceable,
+testable guidance" — the highest rung of machine-readability and usually the
+biggest gap in existing docs.
+
+## Conventions that catch authors (worth checking in an audit)
+
+- `identifier` not `name` for every machine key.
+- `status` has only the two shapes above — no `value` property.
+- `tokens` on a component is a **purpose-keyed map**, not an array:
+  `{ "text-color": "color-button-fg", "background": "color-button-bg" }`.
+- Variants are **flag** (boolean on/off) or **enum** (named options); a
+  single-value enum is valid.
diff --git a/skills/dsds-audit/reference/entity-block-rules.md b/skills/dsds-audit/reference/entity-block-rules.md
new file mode 100644
index 0000000..a288856
--- /dev/null
+++ b/skills/dsds-audit/reference/entity-block-rules.md
@@ -0,0 +1,87 @@
+# Per-entity document blocks + machine-readable shape
+
+The normative block-to-entity mapping from DSDS 0.12.0
+(`document-blocks-document-blocks`). Each entity type accepts its own scoped
+blocks **plus** the general blocks. Use this table to decide, for a given page,
+which blocks are *expected*, which are *missing*, and whether a *present* block
+carries the structured fields that make it machine-readable.
+
+General blocks (accepted by every entity): `guidelines`, `useCases`,
+`accessibility`, `content`, `sections`, `checklist`.
+
+| entity | scoped blocks it accepts (beyond general) |
+| --- | --- |
+| `component` | `anatomy`, `api`, `variants`, `states`, `design-specifications`, `imports` |
+| `foundation` | `principles`, `scale`, `motion` |
+| `pattern` | `interactions`, `anatomy`, `variants`, `states` |
+| `token` / `token-group` | (general blocks only) |
+| `guide` | `steps`, `imports` |
+
+> A block that is not in an entity's accepted set is a schema error, not just a
+> style issue. Flag "this section can't live on this entity type" distinctly from
+> "this block is missing."
+
+## What each block needs to count as machine-readable
+
+A block is more than a heading. For each, the audit checks whether the underlying
+content is expressed in the block's structured fields, or merely as prose/tables a
+human can read but a parser cannot key off. "Partial" = the content exists but is
+unstructured; "Pass" = structured to the shape below.
+
+### General
+
+- **`useCases`** — `items[]`, each `{ description, stance: recommended|discouraged }`;
+  discouraged items SHOULD carry an `alternative` `{ identifier, rationale }`.
+  Optional `purpose`. *Prose "when to use" lists are Partial until they carry the
+  stance enum and alternative identifiers.*
+- **`guidelines`** — `items[]`, each `{ guidance, rationale, level: must|should|should-not|must-not, category? }`.
+  *Bulleted dos/don'ts are Partial until each gets an RFC 2119 level.*
+- **`accessibility`** — structured a11y guidance; strongest when tied to
+  `criteria` with `verification` (e.g. an `axe-core` check), not just narrative.
+- **`content`** — content/UX-writing guidance; do/don't items should be itemised.
+- **`sections`** — `items[]` of `{ title, body }` rich-text; the catch-all for
+  prose that doesn't fit a typed block.
+- **`checklist`** — itemised, ideally referencing `criteria` identifiers.
+
+### Component-scoped
+
+- **`anatomy`** — named parts, each with a stable `identifier` (not just an
+  annotated image). A labelled diagram alone is Partial.
+- **`api`** — `properties[]`, each `{ identifier, type, default?, required?, description? }`.
+  A rendered props table is Partial until it is the structured api block (or its
+  `source`/Storybook link is declared as the machine source).
+- **`variants`** — typed as `flag` (boolean) or `enum` (named options) with
+  `identifier`s. A prose "by hierarchy / by shape" section is Partial.
+- **`states`** — named states each with an `identifier` (default, hover, focus,
+  active, disabled, …). Screenshots with captions are Partial.
+- **`design-specifications`** — structured specs (often the purpose-keyed
+  `tokens` map linking design tokens to roles).
+- **`imports`** — declared composition/imports.
+
+### Foundation-scoped
+
+- **`principles`** — `items[]` of `{ title, description }`.
+- **`scale`** — structured scale steps (spacing/type ramp), not a prose list.
+- **`motion`** — structured motion/easing/duration definitions.
+
+### Pattern-scoped
+
+- **`interactions`** — flow steps for the pattern.
+- plus `anatomy`, `variants`, `states` as above.
+- Pattern composition lives in the entity's `links` array
+  (`{ kind, identifier, role, required }`), not in a block.
+
+### Guide-scoped
+
+- **`steps`** — ordered, structured procedure steps.
+- **`imports`** — referenced material.
+
+## Token / theme specifics
+
+- A **token** needs `identifier`, `tokenType`, and a `source`
+  `{ file, path }` pointing at the DTCG file. No `source` = not machine-traceable
+  to a value.
+- A **token-group** needs `children[]` (tokens or nested groups) and may share
+  `tokenType`/`source` defaults.
+- A **theme** needs `overrides[]` of `{ token, description }` naming which token
+  identifiers change. Values live in DTCG, not here.
diff --git a/skills/dsds-audit/reference/rubric.md b/skills/dsds-audit/reference/rubric.md
new file mode 100644
index 0000000..13dc4ef
--- /dev/null
+++ b/skills/dsds-audit/reference/rubric.md
@@ -0,0 +1,169 @@
+# The audit rubric
+
+How to score a zeroheight page for DSDS 0.12.0 machine-readability and turn the
+result into a prioritised list of changes **a customer can actually make in
+zeroheight**. The goal is not a grade — it's to tell an author the exact authoring
+moves that make their docs parseable by tools and agents, in the order that
+matters.
+
+This rubric scores against the **zeroheight authoring moves** in
+`reference/zeroheight-authoring-pattern.md`, not against raw DSDS JSON fields. A
+finding the customer can't act on in the editor is not a customer finding.
+
+## Rating scale (per check)
+
+- **Pass** — the authoring move is in place; the MCP reliably extracts it.
+- **Partial** — the information exists but not via the move; a human can read it, a
+  parser/agent can't reliably key off it. *Most existing-docs findings land here.*
+- **Missing** — content and structure both absent.
+- **N/A** — doesn't apply to this entity kind.
+
+A **Partial** is good news framed as a small change ("you already have this — here's
+the move that makes it machine-readable"), not a failure. Phrase it that way; it
+changes how the report lands.
+
+## Who-can-act tag (required on every finding)
+
+Tag each finding so the customer never gets advice they can't use:
+
+- **[Author]** — doable in the zeroheight editor now. **These are the report.**
+- **[Platform]** — only zeroheight can do it (JSON export, server-derived ids).
+  **Omit entirely.** Do not list these anywhere in the report — no per-page row, no
+  appendix, no "for zeroheight" section. The tag exists only so you can filter them
+  out; the customer should never see them.
+- **[New content]** — net-new material someone must write (acceptance criteria,
+  agent rules). Author-doable, so it belongs in the report; flag that it's authoring
+  effort, not a tweak, and draft the content for them (see below).
+
+## Severity (drives ordering)
+
+- **P1 / blocker** — without it the entity can't be parsed or placed: ambiguous
+  entity kind, duplicate/colliding titles, empty/stub page, token shown as raw hex
+  with no token-name reference.
+- **P2 / core** — the moves that make docs useful to tools: Level column on
+  guidelines, consistent props/variants tables, canonical names for states/anatomy,
+  status vocabulary, linked alternatives, `introduction` filled.
+- **P3 / enrichment** — the agent-grade layer: the **For Agents tab** (hard rules,
+  disambiguation, acceptance criteria), tags/category, per-platform status detail.
+
+Order every page's findings P1 → P2 → P3 so a customer can work top-down and stop
+when their budget runs out, having done the highest-value work.
+
+## Per-entity check sets
+
+Run only the checks for the page's `kind`. For each, record rating + who-can-act +
+severity + the specific authoring move to make.
+
+### Envelope (all entities)
+- Title unique, clean, consistent (de-facto identifier) — [Author] P1
+- `introduction` filled (→ description) — [Author] P2
+- Status set, from the controlled vocabulary — [Author] P2
+- Tags / category convention (nav grouping helps) — [Author] P3
+- Internal links to related pages (Figma/Storybook/related entities) — [Author] P3
+
+### component
+- Guidelines table with **Level column** (controlled vocab) — [Author] P2
+- "When to use / not to use" or Do/Don't, with **linked alternatives** — [Author] P2
+- **Props table** with fixed column schema — [Author] P2
+- **Variants table** (Type column = flag vs enum) — [Author] P2
+- States named consistently, one per subsection/row — [Author] P2
+- Anatomy parts named/numbered — [Author] P2
+- Accessibility section present — [Author] P2
+- Token references by name (not raw hex) — [Author] P2
+- **For Agents tab** (hard rules + disambiguation) — [Author/New content] P3
+- **Acceptance criteria** (in For Agents tab) — [New content] P3
+- Content/UX-writing do/don't itemised — [Author] P3
+
+### foundation
+- Principles as titled items — [Author] P2
+- Guidelines table with Level column — [Author] P2
+- Scale / motion expressed as tables where relevant — [Author] P2
+- Token references by name — [Author] P2
+- For Agents tab (hard rules, e.g. "reference semantic, never primitive") —
+  [Author/New content] P3
+
+### pattern
+- Page not empty/stub (content not stranded in a sibling subpage) — [Author] P1
+- Member components named and **linked**, with role/required noted — [Author] P2
+- Interaction flow as ordered steps — [Author] P2
+- Guidelines table with Level column; when-to-use — [Author] P2
+- For Agents tab — [Author/New content] P3
+
+### token / token-group
+- Token names follow the system convention (tier-type-context-name) — [Author] P1
+- Values shown as **token-name references / synced specimens**, not raw hex —
+  [Author] P1
+- Grouping/tiers clear (primitive/brand/semantic) — [Author] P2
+- Usage guidance (reference semantic, not primitive) — [Author] P3
+
+### theme
+- Per-theme **override table** (Token / value / Description) — [Author] P1
+- Overrides reference token names, not raw values — [Author] P2
+- "When to use this theme" + best-practices table with Level — [Author] P2/P3
+
+### guide
+- Classified as guide (not mis-audited as a component) — P1
+- Procedural content as **ordered steps** — [Author] P2
+- Clear headings / sections — [Author] P3
+
+### For Agents tab — dedicated checks (components & patterns)
+- Tab present — P3
+- Hard rules as MUST / MUST-NOT (controlled vocab) — P3
+- Disambiguation naming/linking look-alikes — P3
+- Acceptance criteria as testable statements with id + check + mode — P3
+- Placed consistently (same name/position across components) — P3
+
+## Scoring
+
+Per page:
+
+```
+applicable = Pass + Partial + Missing            (exclude N/A)
+score = (Pass + 0.5 * Partial) / applicable       → 0–100%
+```
+
+Report the score **with** the P1/P2/P3 counts and the who-can-act split — the score
+alone hides that one P1 blocker outweighs five P3 gaps. Roll page scores into a
+styleguide average, but always lead with blocker counts.
+
+> Calibrate, don't inflate. A page of beautiful prose with no consistent
+> tables/levels/links is ~0–20%, not 70%. An honest gap picture is the whole value;
+> a generous score that says "mostly there" when no parser can read the docs is
+> worse than useless.
+
+## Turning checks into changes
+
+Every finding must be a concrete authoring move, located on the page, referencing
+the page's own content, with the DSDS intent named so the author understands why.
+Not "add a guidelines block" but:
+
+> **Button › Guidelines ([Author], P2, Partial).** The "button vs link" and "one
+> primary per surface" rules are prose. Put them in a guidelines **table with a
+> Level column** — "Use a link for navigation" → `Must not`; "one primary per
+> surface" → `Must` — reusing the Required/Encouraged pattern already on your Color
+> page. *DSDS intent: RFC 2119 levels so a parser separates hard rules from soft.*
+
+## Draft ready-to-paste snippets (the most valuable output)
+
+The findings table tells the author *what's wrong*; the **ready-to-paste section
+gives them the fix already written**, so they can update zeroheight piece by piece
+(until the MCP supports writes). For every [Author] or [New content] finding that
+can be expressed as content, draft the actual segment — not the whole page, just the
+specific block to paste — built from the page's own material.
+
+Rules for snippets:
+- **Real content, not placeholders.** Pull the page's actual rules, states, props,
+  token names into the snippet. A guidelines snippet for Button must contain
+  Button's real rules with levels assigned.
+- **One segment per snippet**, each labelled with exactly where it goes
+  ("Paste into: Button › a new *For Agents* tab").
+- **In a fenced code block** so it copies cleanly.
+- **Use only authorable constructs** — Markdown tables, headings, callouts, links.
+  Never emit JSON for the customer to paste; they can't author it.
+- **Always draft a For Agents tab** when the page lacks one — this is the single
+  most useful snippet. Fill it with the page's real hard rules, disambiguation, and
+  acceptance criteria.
+
+See `reference/zeroheight-authoring-pattern.md` for the move per construct and the
+For Agents tab structure, and `templates/audit-report.md` for how findings and
+snippets roll up.
diff --git a/skills/dsds-audit/reference/zeroheight-authoring-pattern.md b/skills/dsds-audit/reference/zeroheight-authoring-pattern.md
new file mode 100644
index 0000000..4ef36b3
--- /dev/null
+++ b/skills/dsds-audit/reference/zeroheight-authoring-pattern.md
@@ -0,0 +1,227 @@
+# The zeroheight authoring pattern (DSDS, the authorable way)
+
+This is the heart of the customer-facing audit. zeroheight authors cannot emit
+DSDS JSON — they write pages with titles, headings, tables, callouts, tabs, links,
+and token specimens. But **DSDS's value isn't the JSON syntax; it's the
+conventions the syntax enforces** — stable names, controlled vocabularies,
+consistent table schemas, explicit relationships, testable statements. Every one
+of those is authorable in zeroheight.
+
+So the audit never tells a customer to "add an `identifier` field." It tells them
+the **zeroheight move** that produces the same machine-readable effect, and
+explains the DSDS intent behind it. Doing the move pays off twice: it improves what
+the MCP infers today, and it pre-shapes the content to convert cleanly if/when
+zeroheight ships DSDS export.
+
+## How to read this file
+
+Each construct below gives: the DSDS intent, the **zeroheight move** a customer can
+actually make, what the MCP sees in `get-page`, and the fidelity ceiling (how close
+the approximation gets). Score findings against the *move*, not the JSON — see
+`rubric.md`.
+
+## Confirmed affordances (observed in the Baseline styleguide)
+
+These are real and authorable; the audit can safely recommend them:
+
+- Page **title** + stable URL **slug** (`/p/226512-button`).
+- Page **`introduction`** frontmatter (→ description).
+- **Headings** (page-level tabs serialize as `# H1`; subheads as `##`/`###`).
+- **Tables** with author-defined columns (the Level and Status columns Baseline
+  already uses are the key levers).
+- **Callouts** (`<callout background>`), **Do/Don't** content, **tabs**.
+- **Internal page links** (to alternative components, to the status registry).
+- **Token-name references** / alias syntax (`{primitive.color.pink.300}`), not raw
+  hex.
+- A central **Component Status** matrix + per-page status with a controlled
+  vocabulary (Live / In progress / Backlog / Ready / To do).
+- Per-theme **override tables** (Token / value / Description).
+
+> The audit should treat these as the available toolkit. If a finding can't be
+> expressed with one of these moves, it's not a customer finding — it's platform or
+> net-new content, and belongs in a separate "for zeroheight" appendix, not in the
+> customer's action list.
+
+## Translation table
+
+### identifier (stable machine key)
+- **DSDS intent:** a stable key tools/agents reference; distinct from display name.
+- **zeroheight move:** keep page **titles unique, clean, consistently cased**; the
+  slug becomes the de-facto identifier. For sub-parts (states, anatomy, variants),
+  use the **same canonical label everywhere it appears**. Eliminate duplicate
+  titles (e.g. "Checkbox" vs "Checkbox 1") — they collide.
+- **MCP sees:** `title:` + `url:` slug in frontmatter; labels in headings/table
+  first-columns.
+- **Fidelity:** high for entities (slug is genuinely stable); medium for sub-parts
+  (consistency-dependent, no enforced key).
+
+### description
+- **DSDS intent:** one-line entity summary.
+- **zeroheight move:** fill the page **`introduction`** field.
+- **MCP sees:** `introduction:` in frontmatter.
+- **Fidelity:** high — near-exact match.
+
+### status (overall + per-platform)
+- **DSDS intent:** lifecycle state, optionally per platform.
+- **zeroheight move:** use the **Component Status matrix** + per-page status with a
+  **fixed vocabulary**. Map the columns (Documentation / Design / Storybook) to
+  per-platform status. Pin the vocabulary (see below).
+- **MCP sees:** the status matrix table; per-page status strings.
+- **Fidelity:** high — Baseline already does this; just standardize the words.
+
+### guidelines with RFC 2119 levels
+- **DSDS intent:** each rule tagged must / should / should-not / must-not so a
+  parser separates hard from soft.
+- **zeroheight move:** a **guidelines table with a Level column** drawn from a
+  controlled vocabulary (Baseline's "Required/Encouraged" pattern), *or* start each
+  rule with a fixed verb ("Must…/Should…/Never…/Avoid…"). Add a Why/rationale
+  column.
+- **MCP sees:** a table with a Level column, or consistent leading verbs.
+- **Fidelity:** high — this is the cleanest approximation in the whole pattern, and
+  it already exists on Color and Theming.
+
+### useCases stance + alternative
+- **DSDS intent:** recommended vs discouraged, with a linked alternative.
+- **zeroheight move:** explicit **"When to use" / "When not to use"** sections or
+  **Do/Don't** blocks; for the alternative, **link the alternative component's
+  page** ("use [Link] instead").
+- **MCP sees:** stance from section structure; the internal link as the
+  cross-reference.
+- **Fidelity:** medium-high — stance is clear; the link approximates
+  `alternative.identifier`.
+
+### api (typed properties)
+- **DSDS intent:** properties with identifier / type / default / required.
+- **zeroheight move:** a **props table with a fixed column schema** (Prop / Type /
+  Default / Required / Description), identical across every component, ideally
+  Storybook/Code-Connect-synced.
+- **MCP sees:** a consistent Markdown table.
+- **Fidelity:** high if the schema is consistent — Button already demonstrates it.
+
+### variants (flag vs enum)
+- **DSDS intent:** boolean flag vs named-option enum, each keyed.
+- **zeroheight move:** a **component-properties table** with Property / Type
+  (Variant=enum, Boolean=flag) / Options / Default — Button already has this.
+- **MCP sees:** the table; Type column distinguishes flag from enum.
+- **Fidelity:** high.
+
+### states / anatomy
+- **DSDS intent:** named parts/states each with an identifier.
+- **zeroheight move:** one **subsection or table row per state/part with a
+  consistent canonical name**; number anatomy parts.
+- **MCP sees:** the names in headings/rows.
+- **Fidelity:** medium-high — names carry meaning; no enforced key.
+
+### token source (DTCG)
+- **DSDS intent:** a token points to its value in the DTCG file.
+- **zeroheight move:** always reference the **canonical token name** in
+  specimens/tables (`brand.color.brand.100`), via the **synced token integration**,
+  never hand-typed hex. The token name is the pointer.
+- **MCP sees:** token names / alias syntax in tables.
+- **Fidelity:** high for traceability (name → source); values still live in DTCG by
+  design.
+
+### theme overrides
+- **DSDS intent:** list which token identifiers change per theme.
+- **zeroheight move:** the **per-theme override table** (Token / value / Description)
+  — Baseline's Theming page already does this.
+- **MCP sees:** the override table.
+- **Fidelity:** high.
+
+### criteria with verification
+- **DSDS intent:** testable statements, some automated with a named check.
+- **zeroheight move:** an **"Acceptance criteria" checklist/table** of testable
+  statements; where automatable, **name the tool/rule in text** ("axe-core:
+  button-name"). Best placed in the For Agents tab (below).
+- **MCP sees:** a checklist of statements + tool names.
+- **Fidelity:** medium — readable and self-checkable by an agent; not runnable
+  without a parser.
+
+### agentDocumentBlocks (the agent layer)
+- **DSDS intent:** firm, agent-only rules + look-alike disambiguation.
+- **zeroheight move:** a **"For Agents" tab** (full spec below).
+- **MCP sees:** a `# For Agents` H1 section in `get-page`.
+- **Fidelity:** medium now (visible heading, inferred authority), high if zeroheight
+  gives the tab first-class MCP treatment.
+
+## The "For Agents" tab — spec
+
+A dedicated page tab on components (and patterns) holding the firm, machine-facing
+content that would clutter the human narrative. It's the single highest-leverage
+move in this pattern because it turns the two weakest, most-inferred parts of DSDS
+(the agent layer and verification) into clearly-labeled, reliably-retrieved
+content — and because **zeroheight owns the MCP**, it's the natural hook for
+first-class treatment later (elevate the section in `get-page`; map it to
+`agentDocumentBlocks` + `criteria` in a future export).
+
+### Why it works through the MCP
+`get-page` returns page-level tabs as `# H1` sections, so the tab's full content
+reaches any agent that calls `get-page`. Retrieval is reliable. Caveats to design
+around: it won't appear in `search-pages` snippets (consumers must call
+`get-page`); on very long pages, keep it tight and prominent so attention doesn't
+fade; it's human-visible, so resist softening the rules for human readers.
+
+### Recommended structure
+Keep it terse and imperative — this is for action, not narrative.
+
+```
+# For Agents
+
+## Hard rules
+- MUST NOT use this component to navigate to a URL — use Link.
+- MUST provide an accessible name (visible text or aria-label).
+- MUST limit one primary-emphasis button per surface.
+
+## Disambiguation (when NOT this component)
+- vs Link — Link navigates; Button performs an in-page action.
+- vs Icon Button — use Icon Button for icon-only affordances.
+
+## Acceptance criteria
+- [ ] icon-only-has-name — every icon-only instance exposes a non-empty
+      accessible name. Check: axe-core / button-name. (automated)
+- [ ] focus-visible — focus state is visible and ≥ hover prominence. (manual)
+- [ ] contrast-aa — label/background ≥ 4.5:1. Check: axe-core / color-contrast.
+      (automated)
+```
+
+### Authoring conventions for the tab
+- Lead with **Hard rules** as MUST / MUST NOT bullets (controlled vocabulary).
+- **Disambiguation** entries always name and ideally link the look-alike component.
+- **Acceptance criteria** are testable statements; give each a stable slug-style id
+  and, where automatable, a `Check: tool / rule` and a mode (automated / assisted /
+  manual). This is exactly the shape a future export maps to DSDS `criteria`.
+- Place the tab consistently (same name, same position) on every component so the
+  MCP — and customers — always find it in the same place.
+
+## Controlled vocabularies (pin these per system)
+
+- **Guideline levels:** `Must` / `Should` / `Should not` / `Must not`
+  (or Baseline's Required/Recommended/Discouraged — pick one and use it everywhere).
+- **Status:** `Live` / `In progress` / `Backlog` / `Deprecated` for docs;
+  `Ready` / `In progress` / `To do` for platform readiness. Keep them stable so the
+  MCP reads a closed set, not free text.
+
+## Delivering snippets: paste fidelity
+
+zeroheight's editor ignores raw Markdown on paste — it reads only the `text/plain`
+clipboard flavor, so pasted `|`/`#` arrive as literal characters. The fix is to have
+customers copy **rendered** content (which carries `text/html`), which the editor
+maps to its own blocks. That's what `templates/paste-pack.html` does: each snippet is
+rendered, and the Copy button selects the rendered node so the clipboard gets real
+HTML. Always ship the paste pack alongside the report; never expect customers to
+paste raw Markdown or JSON.
+
+What survives a paste vs what needs a container first:
+- **Pastes cleanly into existing content:** tables, H1–H3 headings, bullet/numbered
+  lists, bold/italic, links, paragraphs.
+- **Needs a zeroheight UI container created first, then paste the body in:** a new
+  **tab** (e.g. For Agents), **callouts**, **Do/Don't** blocks, **token specimens**.
+  Say so in the snippet's note so the author adds the container before pasting.
+
+## What is NOT a customer finding
+
+Some things only zeroheight can do: emitting DSDS JSON, server-deriving identifiers
+from slugs, structured `get-page` export, giving the For Agents tab first-class MCP
+treatment. **Omit these from the report entirely** — no action row, no appendix, no
+"for zeroheight" section. The audit is a customer's to-do list; platform work has no
+place in it. Tag such findings [Platform] only so you can filter them out.
diff --git a/skills/dsds-audit/reference/zeroheight-mapping.md b/skills/dsds-audit/reference/zeroheight-mapping.md
new file mode 100644
index 0000000..11757b0
--- /dev/null
+++ b/skills/dsds-audit/reference/zeroheight-mapping.md
@@ -0,0 +1,79 @@
+# Mapping zeroheight pages to DSDS
+
+How a real zeroheight page (returned by `get-page` as Markdown) maps onto DSDS
+entities and blocks. This is the translation layer the audit reasons over: it
+lets you say "this `## States` section *is* your states block, it just isn't
+structured yet" instead of "you have no states block."
+
+## Step 1 — classify the page to a DSDS entity kind
+
+Use navigation location first, then page content, to pick the `kind`:
+
+| zeroheight signal | DSDS `kind` |
+| --- | --- |
+| under **Components**, documents one UI element with anatomy/variants/states | `component` |
+| under **Foundations**, about color/type/spacing/motion/elevation | `foundation` |
+| a token catalogue / "About Design Tokens" listing token names + values | `token-group` (with `token` children) |
+| a **Theming** page naming token overrides per mode | `theme` |
+| under **Patterns**, composing multiple components for a need | `pattern` |
+| Intro / getting-started / contribution / changelog / "Using the MCP" | `guide` |
+
+Introductions, changelogs, and "welcome" pages are legitimately `guide`s — don't
+audit them as components. Flag the classification you chose so a human can correct
+it; ambiguous pages (e.g. a page that is half foundation, half token catalogue)
+should be called out, not silently bucketed.
+
+## Step 2 — map page sections to blocks
+
+zeroheight section headings vary by team, so match on intent, not exact title.
+Typical Markdown headings seen in the wild and their DSDS target:
+
+| zeroheight section (typical headings) | DSDS block | usual state when first audited |
+| --- | --- | --- |
+| Overview, "Use X when…", When to use / when not to | `useCases` | Partial — prose, no `stance` enum or `alternative` identifiers |
+| Anatomy (annotated diagram + numbered parts) | `anatomy` | Partial — parts named in prose, no `identifier`s |
+| Variants, Component properties table, By hierarchy / By shape | `variants` (+ `api` for the props table) | Partial — table is human-readable, not flag/enum typed |
+| States (+ state screenshots with notes) | `states` | Partial — states named, no `identifier`s |
+| Guidelines, Do / Don't, Best practice | `guidelines` | Partial — no RFC 2119 `level` on each item |
+| Accessibility (contrast, focus, touch target, button-vs-link) | `accessibility` | Partial → Pass if tied to `criteria` with `verification` |
+| Content / Content guidelines (label rules, do/don't) | `content` | Partial — itemise the do/don't pairs |
+| Code / Props table / Storybook link | `api` | Partial — declare the props table or Storybook URL as the machine `source` |
+| Tokens & Variables, "Tokens used" tables | `design-specifications` (component) or token `source` | Partial — tokens shown as a table, not the purpose-keyed map |
+| Theme support / Theming | `theme` overrides or theme links | Partial |
+| Layout & spacing, Touch target | `guidelines` / `design-specifications` | Partial |
+| Principles (foundation) | `principles` | Partial |
+| Spacing/type scale, ramps | `scale` | Partial |
+| Motion / easing / duration | `motion` | Partial |
+| Changelog | `metadata.last-updated` + a `guide`, not a block | n/a |
+| Figma embeds, design callouts | `metadata.links` / `preview` | n/a — these are link metadata |
+
+## Step 3 — recognise the recurring gaps
+
+Across well-written zeroheight pages, the content is usually *present and good*;
+what's missing is the machine structure. The recurring, high-value findings:
+
+1. **No stable `identifier`s.** Pages have display names ("Primary", "Hover") but
+   no machine keys. This blocks almost every downstream parser/agent use.
+2. **Guidance lacks RFC 2119 levels.** Rich do/don't prose, but nothing tells a
+   parser which rules are `must` vs `should`.
+3. **useCases lack stance + alternatives.** "Use a link instead" is written for
+   humans but not encoded as `stance: discouraged` + `alternative.identifier`.
+4. **Props/variants are tables, not typed.** A Markdown props table is readable
+   but isn't the `api`/`variants` block; declare its `source` (Storybook) or
+   structure it.
+5. **No `criteria` / verification.** Accessibility and usage rules are narrative;
+   none are expressed as testable criteria with a `verification` mode.
+6. **No `agentDocumentBlocks`.** Nothing in the agent-only layer — no hard
+   MUST/MUST-NOT, no look-alike disambiguation (button vs link vs icon-button).
+7. **Tokens shown, not sourced.** Token tables list names + values inline rather
+   than a `token` entity with a `source` pointer to the DTCG file.
+
+These seven are the backbone of most reports. Frame each as a concrete, located
+change on the specific page — never a generic "add identifiers."
+
+## Note on fidelity
+
+`get-page` returns rendered Markdown, not the page's underlying structure, and
+image annotations are coordinate metadata only (you can list anatomy labels but
+not infer what each points at without fetching the image). Audit what the text
+asserts; where a determination needs the visual, say so rather than guessing.
diff --git a/skills/dsds-audit/templates/audit-report.md b/skills/dsds-audit/templates/audit-report.md
new file mode 100644
index 0000000..b309611
--- /dev/null
+++ b/skills/dsds-audit/templates/audit-report.md
@@ -0,0 +1,121 @@
+# DSDS Machine-Readability Audit — {{Styleguide name}}
+
+> Audited against **DSDS {{version, e.g. 0.12.0}}** on {{date}}.
+> Pages audited: {{n}}. Source: zeroheight styleguide "{{name}}".
+> Every recommendation below is an **authoring move you can make in zeroheight**,
+> and each page comes with **ready-to-paste segments**. Copy them from the companion
+> **`paste-pack.html`** (open it in a browser, click *Copy formatted*) so they paste
+> into zeroheight with formatting intact — pasting the raw Markdown here won't keep
+> tables/headings.
+
+## Executive summary
+
+{{2–4 sentences: overall state, the single biggest systemic gap, the headline
+number. Lead with blocker counts, not the average. Name the one move that would
+move the needle most across the whole system — usually a convention like "adopt a
+guidelines Level column everywhere" or "add a For Agents tab to every component".}}
+
+| Metric | Value |
+| --- | --- |
+| Machine-readability score (avg) | {{xx%}} |
+| P1 blockers | {{n}} |
+| P2 core gaps | {{n}} |
+| P3 enrichment gaps | {{n}} |
+| Author-actionable findings | {{n}} ({{xx%}} of all) |
+| Pages fully parseable today | {{n}} / {{total}} |
+
+## System-level moves
+
+Cross-cutting conventions — adopt once and most per-page findings collapse. Order
+by impact. Each names the DSDS intent so the team understands the why.
+
+1. **{{Move}} ({{P1/P2/P3}}, [Author]).** {{What to do system-wide, the DSDS intent
+   it satisfies, and where they already do it (cite their own page) so it's a
+   standardisation, not a new habit.}}
+2. …
+
+## Recommended sequence
+
+A budget-ordered path; stop anywhere having done the highest-value work to date.
+
+1. {{P1 wave — unblock parsing: fix duplicate titles, fill empty pages, reference
+   tokens by name}}
+2. {{P2 wave — standardise tables: Level columns, props/variants schemas, status
+   vocabulary, linked alternatives, introductions}}
+3. {{P3 wave — add the agent layer: For Agents tabs, acceptance criteria, tags}}
+
+---
+
+## Per-page findings
+
+Repeat per page. Order findings P1 → P2 → P3. Only findings the customer can act on
+appear anywhere in this report; platform-only items are omitted entirely.
+
+### {{Page name}} — classified as `{{kind}}`
+
+**Score: {{xx%}}** · P1: {{n}} · P2: {{n}} · P3: {{n}}
+{{If classification is uncertain, say so and give the alternative.}}
+
+| Check | Rating | Who | Severity | Authoring move (and DSDS intent) |
+| --- | --- | --- | --- | --- |
+| {{Title hygiene}} | {{Pass/Partial/Missing}} | Author | P1 | {{e.g. Rename "Checkbox 1" — it collides with "Checkbox". Unique titles act as stable identifiers.}} |
+| {{Guidelines}} | Partial | Author | P2 | {{Move the dos/don'ts into a table with a Level column (Must/Should/Never), reusing your Color-page pattern. DSDS intent: RFC 2119 levels.}} |
+| {{For Agents tab}} | Missing | New content | P3 | {{Add a "For Agents" tab: hard MUST/MUST-NOT rules + button-vs-link disambiguation + acceptance criteria. Reliably read via get-page; the seam for future agentDocumentBlocks export.}} |
+| … | | | | |
+
+**What's already good:** {{call out the Pass items and strong prose — the page is
+closer than the score implies because the content exists; it needs the move, not a
+rewrite.}}
+
+#### Ready to paste
+
+Drafted segments built from this page's own content. Copy one at a time into the
+editor — not whole pages, just the specific block named. Update piece by piece.
+
+**Paste into: {{Page}} › {{section, e.g. Guidelines}}** — {{what this fixes}}
+
+```markdown
+{{The actual filled-in segment — e.g. a guidelines table with the page's real rules
+and Level values assigned. Real content, never placeholders.}}
+```
+
+**Paste into: {{Page}} › a new *For Agents* tab** — {{only when the page lacks one}}
+
+```markdown
+# For Agents
+
+## Hard rules
+- MUST {{real rule from this page}}
+- MUST NOT {{real rule from this page}}
+
+## Disambiguation (when NOT this component)
+- vs {{look-alike}} — {{distinction; link the alternative's page}}
+
+## Acceptance criteria
+- [ ] {{slug-id}} — {{testable statement from this page}}. Check: {{tool/rule}}. ({{mode}})
+```
+
+{{Add one snippet per actionable finding that can be expressed as content. Skip
+findings that are purely structural with nothing to draft (e.g. "fill the empty
+page").}}
+
+---
+
+## Appendix A — For Agents tab coverage
+
+A system-wide view of the highest-leverage move, since it's usually the biggest
+gap. {{Which components have a For Agents tab, which don't; recommended rollout
+order, e.g. highest-traffic components first.}}
+
+| Component | For Agents tab | Hard rules | Disambiguation | Acceptance criteria |
+| --- | --- | --- | --- | --- |
+| {{Button}} | {{Missing}} | — | — | — |
+| … | | | | |
+
+## Appendix B — method
+
+Audited each page via the zeroheight MCP (`list-pages` → `get-page`), classified to
+a DSDS entity kind, mapped sections to the zeroheight authoring moves in the skill's
+`reference/` files, and rated each applicable check Pass / Partial / Missing against
+DSDS {{version}}. Scores exclude N/A. "Partial" means the information is present but
+not via the authoring move, so a parser/agent can't reliably consume it.
diff --git a/skills/dsds-audit/templates/paste-pack.html b/skills/dsds-audit/templates/paste-pack.html
new file mode 100644
index 0000000..b0908d8
--- /dev/null
+++ b/skills/dsds-audit/templates/paste-pack.html
@@ -0,0 +1,124 @@
+<!DOCTYPE html>
+<!--
+  PASTE PACK TEMPLATE — fill and ship alongside the Markdown audit report.
+
+  Purpose: zeroheight's editor ignores raw Markdown on paste (it only reads the
+  text/plain clipboard flavor). This page renders each audit snippet so the Copy
+  button puts real text/html on the clipboard — tables, headings and lists then
+  paste into zeroheight with formatting intact.
+
+  HOW TO FILL:
+  1. Set the <title> and the .page / .sub text to the styleguide + date.
+  2. Replace the cards between <!-- CARDS:START --> and <!-- CARDS:END --> with one
+     .card per ready-to-paste snippet from the report. Keep the example card's shape.
+  3. Each .snippet must contain RENDERED, SEMANTIC HTML built from the page's own
+     content — real <table>/<thead>/<tbody>, <h2>, <ul>, <p>, <a>. No inline styles
+     (the page CSS styles the preview; the copied innerHTML stays clean). No raw
+     Markdown, no JSON.
+  4. Group cards by page with an <h2 class="group"> heading so authors find them.
+  5. Leave the <style> and <script> blocks unchanged.
+
+  WHAT PASTES CLEANLY vs WHAT NEEDS A CONTAINER FIRST (tell the author in .where):
+  - Clean on paste: tables, H1–H3 headings, bullet/numbered lists, bold/italic,
+    links, paragraphs.
+  - Needs a zeroheight UI container created first, THEN paste the body in:
+    a new tab (e.g. "For Agents"), callouts, Do/Don't blocks, token specimens.
+-->
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>DSDS Audit — Paste Pack · {{STYLEGUIDE NAME}}</title>
+<style>
+  :root { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; }
+  body { max-width: 820px; margin: 0 auto; padding: 32px 20px 80px; color: #1c1c1f; line-height: 1.5; }
+  h1.page { font-size: 22px; margin: 0 0 4px; }
+  p.sub { color: #5a5a63; margin: 0 0 28px; font-size: 14px; }
+  h2.group { font-size: 16px; margin: 34px 0 14px; padding-bottom: 6px; border-bottom: 2px solid #ececf0; }
+  .card { border: 1px solid #e3e3e8; border-radius: 10px; margin: 0 0 22px; overflow: hidden; }
+  .card .bar { display: flex; align-items: center; justify-content: space-between; gap: 12px;
+    background: #f6f6f8; border-bottom: 1px solid #e3e3e8; padding: 10px 14px; }
+  .card .where { font-size: 13px; font-weight: 600; }
+  .card .where small { display: block; font-weight: 400; color: #6a6a73; margin-top: 2px; }
+  button.copy { font-size: 13px; font-weight: 600; cursor: pointer; border: 1px solid #c5c5cd;
+    background: #fff; border-radius: 7px; padding: 6px 12px; white-space: nowrap; }
+  button.copy:hover { background: #f0f0f3; }
+  button.copy.done { background: #e7f6ec; border-color: #9bd3ad; color: #1c6b38; }
+  .snippet { padding: 16px 18px; }
+  .snippet h1 { font-size: 18px; margin: 4px 0 12px; }
+  .snippet h2 { font-size: 15px; margin: 18px 0 8px; }
+  .snippet h2:first-child { margin-top: 4px; }
+  .snippet table { border-collapse: collapse; width: 100%; margin: 6px 0; font-size: 14px; }
+  .snippet th, .snippet td { border: 1px solid #d9d9e0; padding: 7px 10px; text-align: left; vertical-align: top; }
+  .snippet th { background: #f3f3f6; }
+  .snippet ul, .snippet ol { margin: 6px 0; padding-left: 22px; }
+  .snippet li { margin: 4px 0; }
+  .note { font-size: 13px; color: #6a6a73; background: #fafafb; border: 1px solid #ececf0;
+    border-radius: 8px; padding: 12px 14px; margin: 0 0 28px; }
+</style>
+</head>
+<body>
+  <h1 class="page">Paste Pack — {{STYLEGUIDE NAME}}</h1>
+  <p class="sub">Rendered audit snippets. Click <strong>Copy formatted</strong>, then paste into zeroheight — formatting is preserved.</p>
+
+  <div class="note">
+    <strong>How to use:</strong> these copy as rich content, so they land as real blocks, not raw text.
+    Pasting fills <em>content</em>; zeroheight containers — a new <em>tab</em>, callouts, Do/Don't blocks —
+    are created via the editor UI. For a “For Agents” tab: add the tab first, then paste the body.
+  </div>
+
+  <!-- CARDS:START -->
+
+  <h2 class="group">{{Page name}}</h2>
+
+  <!-- Example card — duplicate this shape per snippet, then delete the example. -->
+  <div class="card">
+    <div class="bar">
+      <span class="where">{{Page › section}}<small>{{what this fixes / container note}}</small></span>
+      <button class="copy" onclick="copySnippet(this)">Copy formatted</button>
+    </div>
+    <div class="snippet">
+      <!-- Rendered, semantic HTML built from the page's own content goes here. -->
+      <table>
+        <thead><tr><th>Guidance</th><th>Why</th><th>Level</th></tr></thead>
+        <tbody>
+          <tr><td>{{real rule}}</td><td>{{real rationale}}</td><td>{{Must / Should / …}}</td></tr>
+        </tbody>
+      </table>
+    </div>
+  </div>
+
+  <!-- CARDS:END -->
+
+<script>
+function copySnippet(btn) {
+  var snippet = btn.closest('.card').querySelector('.snippet');
+  var done = function () {
+    btn.textContent = 'Copied ✓';
+    btn.classList.add('done');
+    setTimeout(function () { btn.textContent = 'Copy formatted'; btn.classList.remove('done'); }, 1600);
+  };
+  // Primary: copy the rendered selection (carries text/html + text/plain).
+  try {
+    var range = document.createRange();
+    range.selectNodeContents(snippet);
+    var sel = window.getSelection();
+    sel.removeAllRanges();
+    sel.addRange(range);
+    var ok = document.execCommand('copy');
+    sel.removeAllRanges();
+    if (ok) { done(); return; }
+  } catch (e) { /* fall through */ }
+  // Fallback: async Clipboard API with explicit html + plain flavors.
+  try {
+    navigator.clipboard.write([new ClipboardItem({
+      'text/html': new Blob([snippet.innerHTML], { type: 'text/html' }),
+      'text/plain': new Blob([snippet.innerText], { type: 'text/plain' })
+    })]).then(done);
+  } catch (e2) {
+    alert('Copy not supported here — select the snippet manually and copy.');
+  }
+}
+</script>
+</body>
+</html>