@canonical/pragma-cli 0.36.0 → 0.38.0

package/bundled-skills/design-auditor/SKILL.md

@@ -146,17 +146,25 @@ Start with a broad inventory, then drill into specific concerns:
 pragma block list      # every component, pattern, layout and subcomponent, with type and tier
 pragma modifier list   # every modifier family with its values
 pragma tier list       # the tiers blocks can live in
+pragma token list      # the design-token symbols, by their dotted names
+pragma variable list   # the CSS custom properties those symbols are emitted as
 pragma graph query "…" # the audit queries below
 pragma graph inspect <IRI-or-ds:name>  # every triple on one entity
+pragma sources status  # which pack is answering, and how many entities it holds
 ```
 
+Run `sources status` before the first query and record what it says in the report's
+scope line. Every count in an audit is a count from one pack at one version; a finding
+that does not say which pack answered cannot be compared against the next audit.
+
 Two graph-query mechanics to know (shared with the sibling skills):
 
-- Common prefixes (`ds:`, `cs:`) are applied automatically — no PREFIX preamble.
-- Inside a SPARQL body, a local name with more than one dot
-  (`ds:global.component.button`) does not parse — use the full IRI there
-  (`<https://ds.canonical.com/global.component.button>`). Single-dot and dot-free
-  prefixed names (`ds:global`, `ds:Component`) work as-is.
+- Common prefixes (`ds:`, `cs:`, `dt:`) are applied automatically — no PREFIX preamble.
+- A prefixed name carrying dots or slashes parses inside a SPARQL body, so write the
+  name the graph prints: `ds:global.component.button` and
+  `dt:s4/web/cond/layer-ds-modifiers/root` both resolve. The full IRI
+  (`<https://ds.canonical.com/global.component.button>`) is accepted too and answers
+  identically — reach for it only when the namespace has no declared prefix.
 
 Note that `block list` deliberately omits the `ds:Group` class — an audit that counts
 only the list under-counts. The queries below go to the graph directly, so they see
@@ -166,10 +174,21 @@ groups too.
 > output (counts, names, ratios) into documentation, PRs, or this skill.
 
 One more live-data rule: before trusting any query, confirm its predicates against the
-current ontology (`pragma ontology lookup ds`). The vocabulary evolves — for example,
-`ds:usage` subsumed the former `whenToUse`/`whenNotToUse` predicates, and queries
-against retired names return empty tables, not errors. An empty result must be
-distinguished from a wrong query before it becomes a finding.
+current ontology. The properties are a section of their own and the flag asks for it —
+`pragma ontology lookup ds` alone prints the classes:
+
+```bash
+pragma ontology lookup ds --properties   # ds: predicates: usage, summary, hasModifierFamily, …
+pragma ontology lookup dt --properties   # dt: predicates: covers, channelOf, …
+```
+
+Both namespaces matter, and they split along a line worth knowing: the block-side
+predicates live in `ds:`, and the token-side ones — `dt:covers`, `dt:channelOf` — live
+in `dt:`, so a token audit that only checks `ds:` never finds the predicate it needs.
+The vocabulary evolves — for example, `ds:usage` subsumed the former
+`whenToUse`/`whenNotToUse` predicates, and queries against retired names return empty
+tables, not errors. An empty result must be distinguished from a wrong query before it
+becomes a finding.
 
 ## Audit Dimensions
 
@@ -198,6 +217,84 @@ where the team's practice is right and the standard is not, the finding becomes
 proposed change to the standard — the standards are open to contribution, and audits
 are where their gaps surface.
 
+### 6. Token Audit
+Which symbols exist, which families rebind them, and which blocks consume them?
+
+The token graph is queryable, and a coverage question about tokens is answered there
+rather than by reading stylesheets. The inventory reads first:
+
+```bash
+pragma token list --search focus          # which symbols exist around a word
+pragma token list --type color            # the population of one type
+pragma token list --channel-of color.text # the channels that provision one symbol
+pragma token consumers --symbol color.text   # which blocks consume a symbol, at which key and state
+```
+
+**`token list`** is the inventory. `--search <word>` matches name and description
+(`--search focus` answers `## Token (7)`, the focus-ring family and its channel);
+`--type <type>` filters by the symbol's own type; and `--limit` defaults to 300, so a
+count is a PAGE until the output says otherwise. It says so plainly — "Showing 300
+token entries, and more exist", with an `--after` cursor — so never read a count of
+300 as a population; raise `--limit` and read the real one (`--type color` is 473,
+not the 300 the default shows). `--channel-of` takes a SYMBOL, not a family name:
+`--channel-of color.text` answers with `modifier.color.text` and
+`surface.color.text`, the two channels that provision it. A family name there is an `INVALID_INPUT` error that lists the symbols
+it would accept.
+
+**A symbol's coverage — which families may rebind it — is `token lookup`'s
+`### Covered by` section**, not `modifier lookup`'s. `pragma modifier lookup
+Criticality` answers with the family's `### Values` (Error, Information, Success,
+Warning) and is the read for what a family offers; `pragma token lookup color.text`
+answers with the families that reach it. Audit from both ends: a family with values
+nothing covers, and a symbol no family covers, are different findings.
+
+The family end has no verb of its own — the predicate is `dt:covers`, and the query
+below is the read (the Family Coverage query under Key Queries lists it per family):
+
+```bash
+pragma graph query "SELECT ?symbol WHERE { ds:global.modifier_family.criticality dt:covers ?symbol }"
+```
+
+`modifier lookup` renders the family's values and nothing else, so the family's OWN
+documentation fields never appear in it — a family with a blank `ds:summary` looks
+identical to a documented one. For a quality finding about the family itself, inspect
+it: `pragma graph inspect ds:global.modifier_family.criticality`. This is the
+present-but-blank trap again, one level up from the blocks.
+
+`pragma variable lookup modifier-color-text` is the third view of the same fact, and
+the most concrete one: one declaration row per modifier, each naming the selector, the
+cascade layer, what it emits and the `file:line` — seventeen rows for that channel,
+which is the family coverage as the stylesheet actually implements it.
+
+**`token consumers` answers empty today, and that is a real finding, not a broken
+command.** No pack records which block consumes which symbol so far: the bindings come
+from the anatomies, the anatomies are being rewritten by hand, and the rows appear
+once the authored anatomies are applied to the document and the pack is bumped. Until
+then, do not report "no block consumes this symbol" as a coverage gap — the honest
+finding is that consumption is not yet measurable, and `anatomy-author` is where the
+work that makes it measurable happens.
+
+Read the empty answer carefully, because under a `--symbol` filter it is ambiguous by
+construction: it means either that nobody consumes THAT symbol, or that the store holds
+no bindings at all. The filtered message does not distinguish them, and its wording is
+in flux — do not learn it by heart. Run the verb unfiltered to tell them apart:
+
+```bash
+pragma token consumers                       # the store-wide answer: are there any bindings at all?
+pragma token consumers --symbol color.text   # then the one symbol
+```
+
+An unfiltered zero settles it — the store has no bindings, so no per-symbol result can
+mean anything yet. Only once the unfiltered read returns rows does a filtered zero
+become a statement about that symbol. A symbol name the store does not know is a
+different outcome again: `INVALID_INPUT`, with the accepted symbols listed, and it
+exits non-zero.
+
+The same reads are available as MCP tools — `token_list`, `token_lookup`,
+`token_consumers`, `variable_lookup`, `variable_chain`, `token_values` among them. Take
+the current list from `pragma capabilities` rather than from this paragraph: the
+catalog grows between releases.
+
 ## Key Queries
 
 Documentation-completeness queries must catch BOTH the absent predicate and the empty
@@ -301,6 +398,23 @@ ORDER BY DESC(?usage)"
 **What it asks**: which families are core and which are unused. A zero-usage family is
 a question — premature abstraction, or adoption that has not landed yet?
 
+### Consistency: Family Coverage — how many symbols each family rebinds
+
+```bash
+pragma graph query "SELECT ?familyName (COUNT(?symbol) as ?symbols) WHERE {
+  ?family a ds:ModifierFamily ;
+          ds:name ?familyName .
+  OPTIONAL { ?family dt:covers ?symbol }
+} GROUP BY ?familyName
+ORDER BY DESC(?symbols)"
+```
+
+**What it asks**: the family end of the token audit — which families actually rebind
+symbols, and which declare values that reach no symbol at all. Keep the `OPTIONAL` as
+written: without it a family covering nothing drops out of the table, and those zero
+rows are the finding. Pair this with the per-component usage count above — a family can
+be widely covered in the token graph and carried by almost no component, or the reverse.
+
 ### Consistency: Components Without Modifier Families
 
 ```bash
@@ -433,6 +547,16 @@ they MEAN is judged against the team's intent:
   "looks" off) and label them differently in the report.
 - Follow up drill-downs with `pragma graph inspect <IRI>` on the specific blocks a
   query surfaced, and `pragma block lookup <Name>` for the human-readable view.
+- `block lookup` takes a DISPLAY name, a `ds:`-prefixed IRI, or a glob — not the bare
+  dotted name. A `block list` row prints `ds:apps_lxd.component.meter`; paste it with
+  the prefix and it resolves, drop the prefix and it is `ENTITY_NOT_FOUND`.
+- A display name shared across tiers answers with EVERY tier's block, concatenated —
+  one `## <Name>` heading and one `- Tier:` line each, and they are DIFFERENT blocks,
+  independently authored, not repeats of one. `pragma block lookup Badge` returns the
+  global, launchpad and portal Badges in a single answer. Read the `- Tier:` lines,
+  count the headings, and pick; an audit that reads only the first heading silently
+  scopes itself to one tier. To go straight to one, use its `ds:` IRI
+  (`pragma block lookup ds:global.component.badge`).
 
 ## Limitations
 

package/bundled-skills/implement-component/SKILL.md

@@ -126,19 +126,29 @@ Then, and only then, the breakdown.
 1. **Read the spec.**
    - Documented block: `pragma block lookup <Name>` — anatomy, modifiers, properties in
      one read (MCP: block_lookup); `pragma graph inspect <uri>` for the full triple view.
-     A bare name can match blocks in several tiers, and `block lookup` silently picks
-     one — it resolves `ds:name` globally and cannot be steered to a tier. Take the
-     picked block's tier from the lookup's own `- Tier:` line, and check for other
-     tiers carrying the name with the name query below, then address the tier you
-     want by its IRI.
+     A bare name resolves `ds:name` globally, so where several tiers carry the name
+     the lookup answers with EVERY one of them — the full writeups concatenated, each
+     under its own `## <Name>` heading with its own `- Tier:` line. They are different
+     blocks, separately authored, not repeats of one: the global Badge and the
+     launchpad Badge have different summaries, properties and anatomies. So the read is
+     not "confirm the tier it picked" but "count the headings and pick": scroll the
+     whole answer, read every `- Tier:` line, and decide which block you are
+     implementing. Stopping at the first heading is how a reader silently implements
+     another tier's component.
+
+     To skip the disambiguation, address one block directly by its `ds:` IRI, which
+     `block lookup` accepts:
 
      ```bash
+     pragma block lookup ds:global.component.badge   # exactly one block
      pragma graph query "SELECT ?b WHERE { ?b ds:name ?n . FILTER(LCASE(?n) = LCASE('<Name>')) }"   # every tier carrying the name
      ```
 
-     If the lookup picked the wrong tier's block, read the one you want with
-     `pragma graph inspect <IRI from that row>` instead — step 2 derives the package
-     from the tier of the block confirmed HERE.
+     The bare dotted name is NOT a key: `block list` prints
+     `ds:apps_lxd.component.meter`, and pasting that row's name without its `ds:`
+     prefix comes back `ENTITY_NOT_FOUND`. Keep the prefix, or use the display name.
+     Step 2 derives the package from the tier of the block confirmed HERE, so make
+     that choice explicit before moving on.
 
      **Check the entry is a spec before building on it — whatever class it is.**
      A row resolving is not the same as a block being documented: many entries
@@ -175,18 +185,37 @@ Then, and only then, the breakdown.
      The inspect renders `ds:hasProperty` only as opaque blank-node labels; for the
      property content use the lookup's Properties section — only when the lookup
      resolved the block you want — or bind the property query to the block confirmed
-     above. (A `block list` row prints the `ds:` form — `graph inspect` takes it
-     as-is, but a SPARQL body needs the full IRI: join `https://ds.canonical.com/`
-     with the row's dotted name, e.g. for the global Button,
-     `<https://ds.canonical.com/global.component.button>`; the name query above
-     prints that full form directly. The bracketed prefixed form `<ds:…>` silently
-     returns an EMPTY table, not an error.)
+     above. (A `block list` row prints the `ds:` form, and both `graph inspect` and a
+     SPARQL body take it as-is — a prefixed name carrying dots parses. The full IRI
+     (`<https://ds.canonical.com/global.component.button>`) is accepted too, and is
+     what `graph query` prints back. What does NOT work is the bracketed prefixed
+     form `<ds:…>`: it silently returns an EMPTY table, not an error.)
 
      ```bash
-     pragma graph query "SELECT ?p ?v WHERE { <https://ds.canonical.com/<dotted name from that row>> ds:hasProperty ?x . ?x ?p ?v }"
+     pragma graph query "SELECT ?p ?v WHERE { ds:global.component.button ds:hasProperty ?x . ?x ?p ?v }"
      ```
    - New block: the `specs/…` file its specify flow produced.
-2. **Confirm the target package and tier.** The spec names its tier; `pragma tier list`
+2. **Check whether it is already implemented, before scaffolding anything.** The graph
+   records implementations, and a block that already has one is not a scaffolding job:
+
+   ```bash
+   pragma implementation list --search <Name>   # which library implements it, on which platform, and the source file
+   ```
+
+   A row names the library, the platform and a link to the head of the source. Read
+   what it points at before deciding: an implementation on the target platform means
+   the work is an EXTENSION of that file, not a new component next to it — and running
+   `pragma create` anyway leaves two components for one block. An implementation on
+   another platform (a react one when the target is svelte) is still the reference to
+   read for API and structure. Only when the search returns nothing for the target
+   platform is a fresh scaffold the right move. Search by display name: a match on the
+   block name also surfaces the groups built from it, so read the block name on each
+   row rather than taking the first.
+
+   If a same-platform implementation exists and the request was to build a new one,
+   that is a decision to raise with the person, not to resolve by scaffolding.
+
+3. **Confirm the target package and tier.** The spec names its tier; `pragma tier list`
    shows what exists. Where a package exists for the tier, its name follows a
    convention — the graph carries no package field: `@canonical/<framework>-ds-global`
    for the `global` tier, `@canonical/<framework>-ds-app` for the shared `apps` tier,
@@ -197,7 +226,7 @@ Then, and only then, the breakdown.
    resolves in the workspace before installing or scaffolding into it. Tiers outside
    `global`/`apps*` have no package convention today: there the target package is a
    decision to raise, not to derive.
-3. **Pull the applicable standards NOW.**
+4. **Pull the applicable standards NOW.**
 
    ```bash
    pragma standard categories                 # what categories exist today
@@ -243,11 +272,22 @@ Then, and only then, the breakdown.
    pragma graph query "SELECT ?s ?kind ?caption ?code WHERE { ?s cs:hasCategory <http://pragma.canonical.com/codestandards#testing.coverage> . { ?s cs:do ?x . BIND('do' AS ?kind) } UNION { ?s cs:dont ?x . BIND('dont' AS ?kind) } ?x cs:description ?caption . OPTIONAL { ?x cs:code ?code } }"
    ```
 
-   (Inside a SPARQL body a local name with more than one dot does not parse; a
-   single dot — `cs:testing.unit` — is fine.) `pragma standard lookup <name>` and
-   `pragma standard sample` resolve only the standards that carry a `cs:name`
-   title — today only a few do — so for the rest the graph query above is the read
-   path. (MCP: standard_categories / standard_list / graph_query / graph_inspect.)
+   Prefixed names with dots parse inside a SPARQL body, so `cs:testing.coverage` and
+   `cs:react.component.barrel_exports` can be written in place of the full `<…>` form
+   and answer identically. The full form is never wrong, and is what `graph query`
+   prints back.
+
+   **`pragma standard lookup <id>` is not the read path for most standards, so do not
+   start there.** It resolves only the standards carrying a `cs:name` title — today a
+   few do — and an id taken straight out of `standard list`'s own output
+   (`css.selectors.namespace`) comes back `ENTITY_NOT_FOUND` with the standard's title
+   offered as a "suggestion", which reads like a typo rather than like the tool
+   answering a different question. The reliable pair is the two reads above:
+   `pragma standard list --category <c>` for what exists, and the Do/Don't graph query
+   for the pairs. `pragma standard sample` has the same title-only limit. Treat a
+   `lookup` miss as saying nothing about whether the standard exists — the category
+   listing is what says that. (MCP: standard_categories / standard_list / graph_query /
+   graph_inspect.)
 
 ## Scaffold
 
@@ -258,7 +298,7 @@ pragma create component react src/components/Button
 - The framework is a tree segment — `pragma create component <framework> <path>` with
   `react`, `svelte`, or `lit` as the segment; the path's final segment is the
   PascalCase component name.
-- Run it from inside the target package confirmed in pre-flight step 2 — the path is
+- Run it from inside the target package confirmed in pre-flight step 3 — the path is
   package-relative (in the ds packages, components live at `src/lib/component/<Name>`,
   so the path there is `src/lib/component/Button`, not the generic example above).
 - Plan-first: preview with `--dry-run`, apply non-interactively with `--yes`, reverse
@@ -294,6 +334,135 @@ standards either way; when no pairs exist, work from those standards' descriptio
 A standard you disagree with is feedback for the standards repo, not a license to
 deviate silently.
 
+### The variable to write, and what it stands for
+
+The stylesheet is where the component meets the tokens, and the seam is queryable — so
+no custom property goes into a stylesheet on a guess. What the reads below cannot do is
+guarantee an answer: a symbol the anatomy names may have no counterpart in the live
+token graph, and that is a finding to raise, not a blank to fill. The rule that follows
+from it is the one to carry through this whole section: a name that does not resolve
+stops the work on that declaration; it never licenses a value.
+
+Six reads, each answering one question:
+
+```bash
+pragma block lookup Button                        # the anatomy the implementation owes: its nodes, keys and symbols
+pragma token list --search radius                 # which symbols exist around a word, when the exact name is unknown
+pragma token lookup color.text                    # one symbol: its type, description and every definition behind it
+pragma token values --symbol modifier.color.text  # what it resolves to at each position
+pragma variable lookup color-text                 # which CSS variable, declared where, emitting what
+pragma variable chain --variable color-text       # what that variable finally reaches
+```
+
+**`block lookup`** carries the `### Anatomy (DSL)` section — the structure and the
+style bindings the implementation owes. Read it as the contract, but read it with one
+caveat: the anatomies are being rewritten by hand and written back to the document, and
+until a block's rewrite has landed and the pack has been rebuilt, that section still
+answers with the retired notation (slash paths like `color/text/muted`, `stack`,
+`flow`, and `sth` placeholders). A slash path there is not a symbol to look up — the
+dotted name is, and `anatomy-author` carries the notation in full. The section that
+will list a block's token bindings directly arrives with those bindings; it is not in
+the lookup's output yet.
+
+Swapping the slashes for dots is a spelling change, and it is only the first thing to
+try. It succeeds where the symbol kept its name and fails where the taxonomy moved
+under it, and those two failures look identical at the prompt — both are
+`ENTITY_NOT_FOUND`. So a miss on the dotted name is not the end of the read; it is the
+start of a search:
+
+```bash
+pragma token list --search radius            # the family, under whatever name it has now
+pragma token list --type dimension --limit 1000
+```
+
+Three outcomes, and they are different findings. The search turns up the same decision
+under a new name — use it, and say in the PR that the anatomy still carries the old
+one. The search turns up a family that was restructured rather than renamed, so the
+decision the anatomy named no longer exists in that shape — that is a design question
+for the token owners, and it belongs in the PR as one. Or the search turns up nothing
+at all — also a finding, and the same answer: raise it. In none of the three do you
+pick a near-miss symbol or write a raw value, because a token-typed property in the
+anatomy is a design decision already made, and `cs:css.properties.values` — pulled in
+pre-flight — bans a raw value in exactly that place. A blocked declaration named in the
+PR is a better outcome than a stylesheet that resolves and is wrong.
+
+**`token list`** is the search read, and it needs its filters to be trusted. It pages
+at 300 rows sorted by name, so the first page of a bare `pragma token list` is colour
+tokens and nothing else — every dimension, number, fontWeight and typography symbol is
+off it. The output says so, in a heading that ends "and more exist" and a closing line
+offering an `--after` cursor, but a bare list piped into `grep` swallows both and reads
+as a system-wide absence. Never conclude "the graph has no such token" from an
+unnarrowed list. Narrow instead: `--search <word>` over name and description,
+`--type <type>` for one type's population, `--channel-of <symbol>` for the channels
+provisioning one symbol (it takes a SYMBOL, not a family name — a family there is an
+`INVALID_INPUT` error that lists what it would accept), and `--limit` raised past 300
+when a full population is what you actually want.
+
+**`token lookup <symbol>`** answers with the symbol's `- Type:` and `- Description:`, a
+`### Definitions` list naming the file each definition comes from, a `### Covered by`
+list of the modifier families that may rebind it, and a `### Values` list. That is what
+tells you whether the symbol you are about to consume is the right one — the
+description is written for exactly this decision. It does not tell you which STYLE KEY
+the symbol is legal on: each key admits symbols from its own namespaces, and neither
+`token lookup` nor `token list` knows about that rule. A symbol that resolves here can
+still be the wrong symbol for the property you are writing — `anatomy-author` carries
+the per-key namespaces, and `anatomies validate --authored` is what enforces them.
+
+**`token values --symbol <symbol>`** is one row per position. For a channel it shows
+the routing: `modifier.color.text | criticality.error | color.text.error` says that
+under `.error`, reading the channel gets you the error text colour. For a flat symbol
+it shows the resolved value per coordinate, `mode.dark` included.
+
+**`variable lookup <name>`** takes the custom property WITHOUT its leading dashes and
+is the read that tells you what to write in CSS. It answers with the `- Symbol:` the
+variable stands for, its `- Tier:` and `- Visibility:`, and a `### Declarations` list:
+one row per declaration, each naming the `selector` it is declared under, the
+`inAtRule` cascade layer, what it `emits`, and the `file:line` it is declared at. A
+`- Visibility: dt:visibility.internal` variable is not a component's to read directly
+— `modifier-color-text` is internal, and a component reads it only as the head of the
+chain the anatomy gives it.
+
+The verb has THREE outcomes, and the third is the one that catches people out:
+
+1. **It resolves and carries a `- Symbol:` line.** The variable stands for that symbol.
+   This is the ordinary case, and the symbol is what you check against the anatomy.
+2. **It resolves and carries NO `- Symbol:` line at all.** The variable is a derived
+   one — a state product or a delta, autogenerated rather than authored — and it stands
+   for no symbol. `hover--color-foreground-secondary` is one: it resolves, its `emits`
+   is an `oklch(from …)` expression, and there is no symbol behind it. Do not read the
+   missing line as a failed lookup, and do not treat the variable as a token. Ask what
+   it reaches instead:
+
+   ```bash
+   pragma variable chain --variable hover--color-foreground-secondary
+   ```
+
+3. **`ENTITY_NOT_FOUND`.** The graph has never heard of the name.
+
+That third outcome does NOT mean "yours to invent". It means one of two things, and
+which one depends on the anatomy. For a property the anatomy never mentions —
+`button-gap`, `icon-size`, a local alias the stylesheet declares for its own
+convenience — it is genuinely component-local: yours to declare, standing for no token,
+and that is the end of it. But for a token-typed property the anatomy DOES name, an
+unresolved name is a gap between the anatomy and the token graph: either the anatomy is
+still in the retired notation, and the rewrite has not landed for that block yet, or
+the token was retired. Neither is a licence to write a value. Stop that declaration and
+raise it, by the rule three paragraphs up.
+
+So the question to ask of every `ENTITY_NOT_FOUND` is not "is it in the graph" but
+"does the anatomy name it". The anatomy names it: raise it. The anatomy is silent:
+declare it locally.
+
+**`variable chain --variable <name>`** is the transitive walk — every
+`variable | variable | symbol` triple the variable reaches through what its
+declarations reference. Use it when `lookup`'s `emits` is another `var()` and you need
+to know where the indirection ends: `color-text` reaches `color.palette.black` and
+`color.palette.white`, which is `light-dark()` spelled out.
+
+The same reads are MCP tools — `block_lookup`, `token_list`, `token_lookup`,
+`token_values`, `variable_lookup`, `variable_chain` — taking the same arguments.
+`pragma capabilities` prints the current catalog, which grows between releases.
+
 ## Post-flight
 
 - Fill in the stories and tests the scaffold stubbed — the spec's properties, modifiers,

package/bundled-skills/specify-component/SKILL.md

@@ -162,12 +162,29 @@ Before anything is invented, find what already exists:
 
 ```bash
 pragma block list                  # every component, pattern, layout and subcomponent, with its type and tier
-pragma block lookup <Name-or-glob> # full spec of candidates: anatomy, modifiers, properties (MCP: block_lookup); a glob repeats a multi-tier name once per IRI and every repeat is the SAME block — the fragment query below lists the tiers
+pragma block lookup <Name-or-glob> # full spec of candidates: anatomy, modifiers, properties (MCP: block_lookup)
 pragma block sample                # real entry shapes — read these BEFORE writing queries
 pragma modifier list               # the modifier families blocks draw from
 pragma tier list                   # the tiers a block can live in
 ```
 
+**`block lookup` fans a shared name out across tiers, and the repeats are not
+repeats.** A display name several tiers carry — or a glob matching them — answers with
+one full writeup per tier, each under its own `## <Name>` heading with its own
+`- Tier:` line, and those are DIFFERENT blocks: `Badge` returns the global, launchpad
+and portal Badges, three independently authored specs with different summaries,
+properties and anatomies. For this step that matters twice over. The answer is the
+prior art, so skipping past the second and third headings as noise is how an
+apps-tier block that already does the job goes unnoticed — read every one. And an
+apps-tier block carrying the name is a different verdict from a global one: the first
+may be a promotion candidate, the second means the gap is not a gap.
+
+Three key forms, and only three: the display name, the `ds:`-prefixed IRI
+(`pragma block lookup ds:global.component.badge`, which answers with exactly one
+block), and a glob. The bare dotted name is not one of them — `block list` prints
+`ds:apps_lxd.component.meter`, and pasting that row without its `ds:` prefix comes
+back `ENTITY_NOT_FOUND`.
+
 Search by name fragment when the naming is uncertain:
 
 ```bash
@@ -177,6 +194,16 @@ pragma graph query "SELECT ?b ?name WHERE { ?b ds:name ?name . FILTER(CONTAINS(L
 > The covered set is whatever the graph answers today. Query it live — never copy its
 > output into documentation, PRs, or this skill.
 
+That query matches `ds:name` on ANY entity, so its rows are not necessarily blocks —
+a modifier value (`ds:global.modifier.in_progress`) and a documentation tag will come
+back alongside them, and neither is prior art. A non-empty table can still mean "no
+block of this name exists". Read each row's IRI, or bind the type when the name is
+noisy:
+
+```bash
+pragma graph query "SELECT ?b ?name ?type WHERE { VALUES ?type { ds:Component ds:Pattern ds:Layout ds:Subcomponent ds:Group } ?b a ?type ; ds:name ?name . FILTER(CONTAINS(LCASE(?name), 'crumb')) }"
+```
+
 Outcome gate: **either "exists — stop or extend it" or a NAMED gap.** No spec is written
 without one of those two sentences, naming the blocks that were checked.
 
@@ -185,11 +212,17 @@ without one of those two sentences, naming the blocks that were checked.
 Read the shape the entry must satisfy:
 
 ```bash
-pragma ontology lookup ds                    # the design-system vocabulary
+pragma ontology lookup ds                    # the design-system vocabulary: its CLASSES
+pragma ontology lookup ds --properties       # the predicates an entry carries — a section of its own, behind the flag
 pragma ontology lookup ds --class UIBlock    # the block-level properties every entry carries
 pragma ontology lookup ds --class Component  # what Component itself declares
 ```
 
+The bare `ontology lookup ds` prints the classes and stops there; the predicates come
+only with `--properties`. So a field name checked against the bare output looks absent
+when it is not — confirm `ds:usage`, `ds:guidelines`, `ds:hasProperty` and the rest
+against the properties section before writing a query or a spec field around them.
+
 `--class` shows only what a class declares itself — usage, guidelines, properties,
 and tier are declared on `ds:UIBlock` and inherited by its subclasses; `summary` and
 `name` sit further up the chain on `ds:Entity`
@@ -281,19 +314,98 @@ Delegate to the `anatomy-author` skill:
 pragma skill lookup anatomy-author
 ```
 
+**Read the repository's copy, not only the printed one, and prefer it where they
+differ.** `skills/anatomy-author/SKILL.md` in canonical/design-system is the authority;
+the copy `pragma skill lookup` prints is bundled into a pragma release and lags the
+repository until the next one. So a section this step names and the printout does not
+show is old text in the printout, not a section that is missing — open the repository
+file before concluding anything is absent.
+
 The skill covers named and anonymous nodes, edges with cardinality, slot names, and
 CTI-inspired style keys; the full ANATOMY_DSL_SPEC ships beside it as
 `ANATOMY_DSL_SPEC.md` in the installed `anatomy-author` skill folder (the lookup
-renders SKILL.md only — open that file directly for the complete spec). The produced
-DSL lands in the step-6 spec file
-under `specs/` — in a `.md` spec as its anatomy section, in a `.ttl` spec as the
-block's `ds:anatomyDsl` string literal — never under `data/`; entry into Coda stays
-the human step.
+renders SKILL.md only — open that file directly for the complete spec).
+
+**A modifier family the spec claims is expressed in the anatomy by CONSUMING its
+channel, never by naming it.** There is no style key, `@state` or `switch`
+discriminator that takes a family name, so an anatomy that supports Criticality on its
+fill colour says so by binding the channel of the symbol the fill reads —
+`appearance.background: [modifier.color.foreground.primary, color.foreground.primary]`
+for a filled surface, `typography.color: [modifier.color.text, color.text]` for text.
+Which channels exist is the token graph's answer, not a guess:
+`pragma token list --channel-of color.background` reports a surface channel and no
+modifier one, so `modifier.color.background` is not a symbol and cannot be bound. The
+family lands in
+the channel: `pragma token values --symbol modifier.color.text` shows
+`anticipation.caution` routing to `color.text.warning`, which is how Button's
+Anticipation support reaches its text without Button's anatomy ever saying
+"Anticipation". So when step 6 recorded a Modifier Families section, this step's job is
+to name, per family, WHICH key carries it and which channel that key reads — and to
+check the family actually covers that symbol (`pragma token lookup <symbol>`, the
+`### Covered by` list). A family covering none of the symbols the anatomy binds is a
+finding for the token owners, not something to express in the tree.
+
+**Where the produced DSL lands.** An anatomy is a file of its own, not a section of
+this spec: it goes to `anatomies/authored/<tier>/<uri>.yaml` in canonical/design-system,
+with the file name spelling the dotted uri. There it is checked offline with
+`bun src/cli.ts anatomies validate --authored`, reviewed as a file in a pull request,
+and written to the block's `anatomy_dsl` cell by `anatomies write`; after that write the
+document is the source of record. Never write into design-system `data/`, which the
+pull sync regenerates. `anatomy-author`'s "Where the anatomy lands" section is the
+authority on that path — this step's job is to hand it a specified component and take
+back the file name it wrote.
+
+### 8. Pair with tokens
+
+Tokens here means token symbols — `color.text`, `dimension.200` — never CSS variables.
+A variable such as `--color-text` is the web platform's name for a symbol, one name per
+platform, and it is the implementer's concern: the anatomy names the symbol, and
+`implement-component` reads `pragma variable lookup` to find what to write in CSS. A spec
+that named variables would be tied to one platform and would miss every symbol the web
+has not emitted yet.
+
+The spec does not bind tokens — that is the anatomy's job, one style key at a time. What
+this step owes is the check that the symbols the component will need actually exist, so
+a specification does not promise a colour or a spacing role the token graph has never
+declared:
 
-### 8. Pair with tokens — placeholder
+```bash
+pragma token list --search focus   # which symbols exist around a word
+pragma token lookup color.text     # one symbol in full: type, description, definitions
+```
+
+`token list` pages at 300 rows sorted by name, so a bare `pragma token list` returns
+colour tokens and nothing else — every dimension, number and typography symbol is off
+the first page, behind an "and more exist" heading and an `--after` cursor that a pipe
+into `grep` swallows. Always narrow (`--search`, `--type`) or raise `--limit` before
+concluding a family is absent; an unnarrowed list is not evidence.
+
+A name that comes back `ENTITY_NOT_FOUND` is a finding for the spec — either the
+component reads an existing symbol instead, or a new token is a decision to raise with
+the token owners, and either answer belongs in the spec rather than in the anatomy that
+follows. (MCP: `token_list`, `token_lookup`.)
+
+**`token lookup` resolving is the FIRST check, not the whole one.** It answers whether a
+symbol exists; it says nothing about which style key the symbol may go on. Each key
+admits symbols from one namespace only, and a symbol that reads as exactly on-topic can
+still be outside it: `typography.text.tertiary` is a real composite typography token and
+"12px tertiary text" is exactly what a small label wants, yet `typography.size` admits
+`dimension.` symbols alone, so the binding is unlawful and
+`dimension.size.fontSize.250` is what belongs there. Neither `token lookup` nor
+`token list` knows that rule.
+
+So the pairing has two checks, in order: `token lookup <symbol>` for existence, then the
+anatomy gate for admissibility.
+
+```bash
+bun src/cli.ts anatomies validate --authored   # in canonical/design-system
+```
 
-**Left blank for now** — token pairing content lands with the token work. Do not invent
-token guidance.
+It names the file, the node, the key, the symbol and the namespaces the key admits. Run
+it before reporting step 8 as done, and treat a namespace rejection the way you treat an
+`ENTITY_NOT_FOUND`: a finding to resolve against the roster
+(`node_modules/@canonical/anatomy-dsl/definitions/style-keys.yaml`, which states the
+`valueKind` and the namespace per key), never a value to force through.
 
 ## Response format
 
@@ -309,8 +421,8 @@ Spec: specs/<tier>.<type>.<snake_name>.md
 - [ ] 4. Benchmarked against: … (adopt/reject decisions stated)
 - [ ] 5. State gate: fired/not fired (States & interaction section: yes/no)
 - [ ] 6. Documentation written to the sync-safe location
-- [ ] 7. Anatomy DSL written via anatomy-author
-- [ ] 8. Token pairing: placeholder (deferred)
+- [ ] 7. Anatomy DSL written via anatomy-author (file: anatomies/authored/…)
+- [ ] 8. Token pairing: symbols checked against the token graph AND the anatomy gate run (findings: …)
 ```
 
 ## Related skills