@canonical/pragma-cli 0.36.0 → 0.38.0

package/pragma.conf.ts

@@ -55,8 +55,10 @@ over GraphQL or raw SPARQL.
 ## How it fits together
 
 - **Tiers** are a hierarchy (\`global\` > \`apps\` > \`apps/lxd\`): a lower tier
-  inherits and overrides the blocks of its ancestors, so scoping a query to a
-  tier walks that chain.
+  inherits and overrides the blocks of its ancestors, so scoping a read to a
+  tier walks that chain. Reads of a tiered entity ARE scoped — a list answers
+  from the top-level tiers, \`--tier apps_lxd\` from that tier and its
+  ancestors, \`--tier all\` from every tier.
 - **Channels** (\`normal\`, \`experimental\`, \`prerelease\`) gate visibility, so an
   in-progress block never leaks into a stable answer.
 
@@ -72,7 +74,15 @@ exactly the domain that was published.`;
 
 /**
  * The read stories the design-system pack supplies — `block`, `token`,
- * `modifier` and `tier` as declared data rather than code.
+ * `variable`, `modifier` and `tier` as declared data rather than code.
+ *
+ * `token` and `variable` read the TOKEN-ONTOLOGY pack's four strata rather than
+ * this one's graph, and they are declared here anyway, deliberately: `token
+ * consumers` joins a symbol to the design-system records that consume it, so
+ * the pair spans both packs and there is no single pack whose `stories/*.json`
+ * could carry them. The day the strata are addressable without the design
+ * system — or the day either pack ships its own stories — is the day to split
+ * them out, and the note below about deletion applies to whichever half moves.
  *
  * The association with the pack is the point: when `@canonical/design-system`
  * starts shipping its own `stories/*.json`, this block is deleted and the
@@ -82,11 +92,16 @@ exactly the domain that was published.`;
  * layer does not know the pack grammar (`parsePackDefinition` does).
  */
 const designSystemStories: readonly PackDefinition[] = [
-  // `block list` is declared content (L-OPEN-9): one unfiltered SELECT over
-  // the four UIBlock classes, listing ALL blocks — experimental and alpha ones
-  // included, for everyone — until filtering returns in declared form. The
-  // hand-written tier-chain/channel filtering (and its `--all-tiers` escape)
-  // is removed with the code, an owner-signed consequence. Display parity
+  // `block list` is declared content: one SELECT over the four UIBlock
+  // classes, listing every block the TIER SCOPE admits — experimental and
+  // alpha ones included, for everyone, since no read filters by channel.
+  //
+  // Tier filtering did come back in declared form, and in the form the story
+  // declares rather than the form the query text does: `tierScope` below names
+  // the hierarchy, and the kernel compiles the scope into this query as a
+  // constraint on `?uri` (`--tier all` for the unscoped list this used to be).
+  // The retired `--all-tiers` escape is not back — `--tier all` answers the
+  // same question with the argument a caller already holds. Display parity
   // lives IN the query: `VALUES ?class` closes the type set, so the BINDs
   // that derive `name` (declared name, else the IRI's local name), `type`
   // (lowercased class local name), and `tier` (tier IRI's local name) operate
@@ -135,6 +150,30 @@ const designSystemStories: readonly PackDefinition[] = [
     toolDescription:
       "List all design system blocks with their type, tier, and modifier families. Use when browsing which blocks exist. Example: block_list {}.",
     colophon: DESIGN_SYSTEM_COLOPHON,
+    // Blocks are TIERED, so every read of them is SCOPED: `block list` answers
+    // from the top-level tiers, `--tier apps_lxd` from that tier and its
+    // ancestors, `--tier all` from every tier (kernel/packs/tierScope.ts states
+    // the rule once, for every noun that declares this).
+    //
+    // The four terms are the ones the graph already carries, and three of them
+    // this story already declared for its RANKING (`scopeWeight` below): the
+    // hierarchy is the `/` in a tier's own `ds:name`, because the shipped graph
+    // asserts no parent edge to read instead — `ds:apps_lxd` is a `ds:Tier`
+    // with a name and nothing else. Reading the hierarchy from one place is
+    // what keeps the scope and the lookup ranking from disagreeing about which
+    // tier is above which.
+    //
+    // `base` is the editorial half, declared here for the reason `weights` is:
+    // nothing in the graph says `global` is the tier the others build on — the
+    // colophon above says it, and the 119 global blocks every product screen
+    // is assembled from say it. Without `base`, `--tier apps_lxd` would answer
+    // with LXD's nine blocks and hide the Buttons and Inputs they sit in.
+    tierScope: {
+      type: "ds:Tier",
+      via: "ds:tier",
+      by: "ds:name",
+      base: "ds:global",
+    },
     list: {
       query: [
         "SELECT ?uri ?name ?type ?tier",
@@ -268,6 +307,10 @@ const designSystemStories: readonly PackDefinition[] = [
           label: "Anatomy (DSL)",
           kind: "code",
           level: "detailed",
+          // The one piece of the notation that cannot be guessed from reading
+          // it: a bracketed value looks like a set of alternatives with no
+          // stated order of preference, and it is an ORDERED chain.
+          note: "A list value is the fallback chain the implementation reads, first wins.",
         },
         {
           name: "anatomyClassic",
@@ -314,6 +357,69 @@ const designSystemStories: readonly PackDefinition[] = [
             { name: "uri", property: "ds:name", graphqlField: "uri" },
           ],
         },
+        // Which symbols this block consumes, at which style key and rank — the
+        // mirror of `token consumers`, read from the block's end. It was
+        // DELIBERATELY ABSENT while none of the terms existed: the record the
+        // whole tuple hangs off is the design system's to mint, and until it
+        // did, `ds:hasTokenBinding`, `ds:consumesSymbol`, `ds:rank`,
+        // `ds:viaBlock` and `ds:node` were not declared properties at all. All
+        // five are now, with domains and ranges, and `ds:TokenBinding` is a
+        // class — so the declaration lands as the note then predicted, all six
+        // identity columns of it.
+        //
+        // SPARQL lane, and NOT this lookup's own GraphQL one, which is the only
+        // part of that prediction that had to change. Two of the six columns
+        // are unreachable through a generated document: `anatomy:styleKey` and
+        // `anatomy:styleState` carry no `rdfs:domain` — they are the anatomy
+        // vocabulary's, shared by every styled thing — so ke-graphql generates
+        // no field for them on `TokenBinding`, and a derived name the schema
+        // does not carry drops out of the document in silence. Measured on the
+        // shipped pack: Button rendered 24 rows with no key and no state, two
+        // of which (`spacing.internal.inline.start` and `…end`) were then
+        // byte-identical. A table whose rows a reader cannot tell apart is the
+        // defect this story refuses elsewhere, so the expand takes the lane
+        // that can read every term instead. The modifier families above cannot
+        // follow it — their nested `values` is a second hop only a document can
+        // make — which is why the lane is per-expand.
+        {
+          name: "tokens",
+          heading: "Tokens",
+          kind: "table",
+          relation: "ds:hasTokenBinding",
+          source: "sparql",
+          level: "detailed",
+          // Ordered by the READING order of the thing described: a node's
+          // styles, one key at a time, each key's fallback chain in the order
+          // the implementation walks it. The store's own scan order is
+          // undefined and put a node's two spacing keys either side of an
+          // unrelated one.
+          orderBy: ["node", "key", "rank"],
+          // The same sentence `Anatomy (DSL)` carries, because it is the same
+          // notation read from the other side: the anatomy's bracketed list is
+          // the chain, and `rank` is the position in it. A reader who has the
+          // rank column but not that sentence has no way to know that rank 2 is
+          // reached only when rank 1 does not resolve.
+          note: "A list value in the anatomy is the fallback chain the implementation reads, first wins; rank is the position in that chain.",
+          select: [
+            // The dotted name, not the symbol's IRI: it is the address
+            // `token lookup` and `token consumers --symbol` both take, so a row
+            // here is a query a reader can run.
+            { name: "symbol", property: "ds:consumesSymbol/rdfs:label" },
+            { name: "key", property: "anatomy:styleKey" },
+            { name: "state", property: "anatomy:styleState" },
+            { name: "rank", property: "ds:rank" },
+            // Blank on the block's OWN tree. `ds:viaBlock` is present on every
+            // record and its own definition says it equals the block in the
+            // own-tree case, so printing it raw put "Button" in all 24 of
+            // Button's rows — a cell that is only ever news when it differs.
+            {
+              name: "via",
+              property: "ds:viaBlock/ds:name",
+              blankWhenSelf: true,
+            },
+            { name: "node", property: "ds:node" },
+          ],
+        },
       ],
       disclosure: {
         levels: ["summary", "standard", "detailed"],
@@ -327,59 +433,845 @@ const designSystemStories: readonly PackDefinition[] = [
     },
   },
 
-  // Design tokens: SPARQL-sourced on both verbs. There is no `ds:Token` GraphQL
-  // type to project against when the graph ships no tokens, and the lookup reads
-  // a property path (`ds:tokenType/rdfs:label`) only SPARQL can express. The
-  // `emptyRecovery` install hint is the story users see on an empty store. The
-  // noun is now purely declarative: `token add-config` wrote a starter file, and
-  // L-OPEN-9 removed it rather than growing the read grammar a mutation verb.
+  // The design-token SYMBOLS — S1 of the four token strata, keyed on the name
+  // literal the binding programme publishes.
+  //
+  // REPOINTED from `ds:Token`, a class no graph asserts. The shipped pack
+  // carries 0 instances of it and 745 `dt:TokenSymbol`, so every `token list`
+  // on every install answered an empty table while the population sat one
+  // namespace over — the same silent shape as reading a retired `ds:whenToUse`,
+  // and caught the same way (`listBudget.shipped.exec.test.ts` measured this
+  // story at 0 rows / 2 bytes). `ds:valueLight`/`ds:valueDark` go with it: a
+  // symbol's value is not a pair of theme columns but one row per POSITION in
+  // the coordinate space, which is what `token values` answers.
+  //
+  // NO `nameFallback`, deliberately. The kernel's IRI derivation publishes a
+  // dotted local name with SLASHES (`dt:color.text` → `color/text`), which
+  // contradicts the dotted notation ruled for symbol names and would make this
+  // answer disagree with the anatomy's spelling of the same symbol. The
+  // consequence is visible rather than hidden: until the pack ships
+  // `rdfs:label` on the symbols, `token list` publishes no rows and
+  // `token lookup` resolves no name. An empty answer that says so beats a
+  // populated one whose names nothing else recognises — and it is why `token`
+  // is still in `EMPTY_CORPUS_TODAY`.
   {
     noun: "token",
-    description: "List all design tokens.",
+    description: "List the design-token symbols.",
     toolDescription:
-      "List all design tokens with their type. Use when browsing which tokens exist under the active scope. Example: token_list {}.",
+      'List the design-token SYMBOLS — logical dotted names (`color.text`), with the type and description from the symbol\'s OWN definition, and the symbol a channel provisions. The CSS custom-property names a stylesheet declares are variable_list. Example: token_list { type: "color" }.',
     list: {
+      // Type and description are DEFINITION-level facts, and 393 of the 745
+      // symbols have more than one definition (`color.text` has 20). The one
+      // that speaks FOR the symbol is its own, and the graph already carries a
+      // path to it: every symbol the resolver reached has a BASE
+      // `dt:ResolvedValue` — the one with no `dt:coordinate` — and the HEAD of
+      // that value's `dt:resolutionChain` is the definition the value was
+      // authored in at the all-defaults position. Its `dt:tokenType` and its
+      // `w3c-tokens:description` are this row's two cells.
+      //
+      // The base restriction is SPELLED OUT rather than left to `DISTINCT`.
+      // 354 of the 519 values at a coordinate carry a chain too, and their
+      // heads are the definitions authored for those positions — a different
+      // definition, correctly so, and not this column's. Over the shipped
+      // corpus those heads happen to agree with the base head on both fields,
+      // so the unrestricted walk answers the same 745 rows; `FILTER NOT EXISTS`
+      // says WHICH value is meant instead of resting on that coincidence.
+      //
+      // Measured over the 745 symbols: 718 publish both fields, 27 blank both.
+      // The 27 are the 25 minted channels, which have no definition anywhere,
+      // plus `typography.heading.display` and its `.bold` twin, which have
+      // definitions but no resolved value to authorise one of them. Nothing
+      // publishes one field and blanks the other — a chain head carries both,
+      // or the symbol has no chain head.
+      //
+      // This REPLACED an agreement rule (publish what every definition agrees
+      // on, blank it when they disagree), and the two never disagree where the
+      // old one spoke: 0 of the 745 symbols have two definitions naming
+      // different types, and the 40 whose descriptions "disagreed" disagree
+      // only with a `semantic/modifier/**` definition — one position's wording,
+      // which the old rule let outvote the symbol's own. Those 40 now read
+      // their own description instead of a blank. What went with the old rule
+      // is its cost: a `COUNT(DISTINCT ...)` sub-select over 1,311 definitions
+      // made this the slowest body in the distribution. The paged walk that
+      // `listQuery.shipped.exec.test.ts` runs over it took 190 s, past its own
+      // 60-second timeout; over this query it takes 1.8 s, and the whole
+      // population comes back in 71 ms rather than 1.1 s a page.
       query: [
-        "SELECT ?uri ?name ?category WHERE {",
-        "  ?uri a ds:Token ;",
-        "       ds:tokenId ?name .",
+        "SELECT DISTINCT ?uri ?name ?type ?description ?channelOf",
+        "WHERE {",
+        "  ?uri a dt:TokenSymbol ;",
+        "       rdfs:label ?name .",
+        // A channel IS a symbol after the binding programme, so the relation to
+        // the symbol it provisions is a column on this population rather than a
+        // noun of its own. Bound to the base symbol's LABEL, not its IRI: the
+        // filter column and the displayed column are one column, and an
+        // unbound IRI cell renders as a full IRI.
+        "  OPTIONAL { ?uri dt:channelOf/rdfs:label ?channelOf }",
         "  OPTIONAL {",
-        "    ?uri ds:tokenType ?type .",
-        "    ?type rdfs:label ?category .",
+        "    ?resolved dt:forSymbol ?uri ;",
+        "              dt:resolutionChain/rdf:first ?definition .",
+        "    FILTER NOT EXISTS { ?resolved dt:coordinate ?coordinate }",
+        "    OPTIONAL { ?definition dt:tokenType/rdfs:label ?type }",
+        "    OPTIONAL { ?definition w3c-tokens:description ?description }",
         "  }",
         "}",
         "ORDER BY ?name",
       ].join("\n"),
       columns: [
+        { field: "name", label: "Name" },
+        { field: "type", label: "Type" },
+        { field: "channelOf", label: "Channel of" },
+        { field: "description", label: "Description" },
         { field: "uri", label: "IRI" },
+      ],
+      filters: [
+        {
+          param: "type",
+          variable: "type",
+          // The seven typed members of the definition's type class, which is
+          // the same term the `type` column reads off the symbol's own
+          // definition. A type the ontology declares that no symbol is filed
+          // under is a calm empty list, not a bad argument.
+          vocabulary: {
+            query: [
+              "SELECT DISTINCT ?type WHERE {",
+              "  ?kind a w3c-tokens:TokenType ;",
+              "        rdfs:label ?type .",
+              "}",
+            ].join("\n"),
+          },
+          description: "Filter by type.",
+        },
+        {
+          param: "channelOf",
+          variable: "channelOf",
+          // The dimension is "which SYMBOL", so the roster is EVERY symbol —
+          // not the far smaller set that happens to have a channel today.
+          // Asking for a symbol nothing provisions is the documented calm empty
+          // list, which is the whole reason a vocabulary is read from the graph
+          // rather than from the rows a page returned.
+          //
+          // Keyed on `rdfs:label`, the same term the column binds and the same
+          // term the lookup resolves by. All three move together or not at all.
+          vocabulary: {
+            query: [
+              "SELECT DISTINCT ?channelOf WHERE {",
+              "  ?symbol a dt:TokenSymbol ;",
+              "          rdfs:label ?channelOf .",
+              "}",
+            ].join("\n"),
+          },
+          description: "Filter to one symbol's channels.",
+        },
+      ],
+      search: {
+        variables: ["name", "description"],
+        description: "Search name and description.",
+      },
+      // No `emptyRecovery`: this list is empty only on an install whose store
+      // holds no token pack at all, and the kernel's generic hint already names
+      // both fixes for that (broaden the filter, or build the store). Anything a
+      // story added here would be a sentence about an empty store printed to
+      // readers who have 745 symbols and only missed with a filter.
+    },
+    verbs: [
+      {
+        verb: "values",
+        description:
+          "List the value each symbol resolves to at each position, with its chain or its derivation.",
+        toolDescription:
+          'List the resolved token VALUES — one row per (symbol, position) the graph materialises, with the value and either its resolution chain or the symbol it derives from. Only MATERIALISED positions appear, not the permutation space: a position with no row falls through to the base symbol. A derived row carries a derivation and no value cell. Example: token_values { symbol: "color.text" }.',
+        // The resolved-value shape admits exactly one of a chain or a
+        // derivation, so BOTH are selected wherever a value is projected. A
+        // surface that selected only the chain would show a blank row for every
+        // one of the 165 channel routings — and channel values are precisely
+        // what the anatomy validator and the editor's completion ask about.
+        //
+        // Both are rdf:LISTs, not literals: `dt:resolutionChain` is a list of
+        // definition IRIs, so it needs `/rdf:rest*/rdf:first` and an aggregate
+        // to become one cell. The chain items are trimmed to the path inside
+        // the token files, which is the form the resolution chain is quoted in.
+        //
+        // The cell is a SET, and its order is NOT the list's. `GROUP_CONCAT`
+        // has no defined order in SPARQL and takes no `ORDER BY`, so the links
+        // of a multi-link chain may come back either way round — which a test
+        // pinning one spelling of a two-link chain found by flaking. Reading
+        // the cell as "which definitions this value passed through" is
+        // therefore right and reading it as "in what order" is not. The
+        // ORDERED anchor a caller usually wants is the chain's HEAD, the
+        // definition the value was authored in, and that is what the lookup's
+        // `values` expand projects with `rdf:first`.
+        query: [
+          "SELECT ?symbol ?position ?value ?derivedFrom",
+          '       (GROUP_CONCAT(DISTINCT ?chainItem; SEPARATOR=" ") AS ?chain)',
+          "WHERE {",
+          "  ?resolved a dt:ResolvedValue ;",
+          "            dt:forSymbol ?symbolUri .",
+          "  ?symbolUri rdfs:label ?symbol .",
+          "  OPTIONAL { ?resolved dt:coordinate ?coordinate }",
+          "  OPTIONAL { ?resolved dt:resolvesTo ?value }",
+          "  OPTIONAL { ?resolved dt:derivedFrom/rdfs:label ?derivedFrom }",
+          "  OPTIONAL {",
+          "    ?resolved dt:resolutionChain/rdf:rest*/rdf:first ?chainUri .",
+          '    BIND(REPLACE(STR(?chainUri), "^.*/file/", "") AS ?chainItem)',
+          "  }",
+          // The coordinate's own dotted name, with the class prefix its IRI
+          // carries dropped: `dt:coordinate.mode.dark` displays and filters as
+          // `mode.dark`, which is how a position is written everywhere else.
+          // A value at the DEFAULT position carries no coordinate at all, and
+          // its cell is empty rather than a full IRI.
+          '  BIND(REPLACE(REPLACE(STR(?coordinate), "^.*[/#]", ""), "^coordinate[.]", "") AS ?position)',
+          "}",
+          "GROUP BY ?resolved ?symbol ?position ?value ?derivedFrom",
+          "ORDER BY ?symbol ?position",
+        ].join("\n"),
+        columns: [
+          { field: "symbol", label: "Symbol" },
+          { field: "position", label: "Position" },
+          { field: "value", label: "Value" },
+          { field: "chain", label: "Chain" },
+          { field: "derivedFrom", label: "Derived from" },
+        ],
+        filters: [
+          {
+            param: "symbol",
+            variable: "symbol",
+            vocabulary: {
+              query: [
+                "SELECT DISTINCT ?symbol WHERE {",
+                "  ?s a dt:TokenSymbol ;",
+                "     rdfs:label ?symbol .",
+                "}",
+              ].join("\n"),
+            },
+            description: "Filter to one symbol.",
+          },
+          {
+            param: "position",
+            variable: "position",
+            // `set`, because ONE row can sit at several positions at once: a
+            // value asserted `dt:alsoAt` a second coordinate is one row
+            // belonging to both, and a filter comparing only the whole cell
+            // would answer such a row for neither.
+            match: "set",
+            vocabulary: {
+              query: [
+                "SELECT DISTINCT ?position WHERE {",
+                "  ?c a dt:Coordinate .",
+                '  BIND(REPLACE(REPLACE(STR(?c), "^.*[/#]", ""), "^coordinate[.]", "") AS ?position)',
+                "}",
+              ].join("\n"),
+            },
+            description: "Filter to one position.",
+          },
+        ],
+        search: {
+          variables: ["symbol", "value", "derivedFrom"],
+          description: "Search symbol, value, derivation.",
+        },
+        emptyRecovery: {
+          message:
+            "Resolved token values come from the @canonical/token-ontology pack, and a value is only addressable by symbol once that pack publishes its name literals — a store built without that pack carries none.",
+          cli: "sources update",
+        },
+      },
+      {
+        verb: "consumers",
+        description:
+          "List which blocks consume which token symbol, at which style key, state and rank.",
+        toolDescription:
+          'List the token BINDINGS the design system records — which block consumes which symbol, at which style key, state, rank and node. Every column is identity: two bindings differing only in state are different facts. The block is the CONSUMING block; via names the block whose anatomy the binding was authored in, and is blank when that is the consuming block itself. Name the symbol by its dotted name (symbol) or by a CSS variable standing for it (variable). Answers empty until the packs record bindings. Example: token_consumers { variable: "color-text" }.',
+        // Seven identity columns, and not one of them is decoration: a binding
+        // is identified by the whole tuple, so dropping `rank` or `node` would
+        // publish rows a caller cannot tell apart — which is worse than a wide
+        // table, because a deduplicating consumer would silently lose facts.
+        //
+        // `ds:hasTokenBinding` and its four siblings are DEFINED BY the
+        // design-system ontology only from the binding programme's records
+        // onward; today the shipped ontology defines none of them, and the `ds:`
+        // prefix IS bound, so this answers a calm empty list with the recovery
+        // below rather than failing. It starts answering with no code change.
+        //
+        // `?block` is the CONSUMING block and `?via` the block whose anatomy
+        // the binding was authored in, and the two are separate columns because
+        // they are separate facts. They were one: `?block` used to COALESCE the
+        // via name over the consuming block's, so a record Accordion carries
+        // because its anatomy embeds `Accordion.Item` printed as
+        // `Accordion.Item` — byte-identical to Accordion.Item's OWN record.
+        // `--symbol color.text` answered six rows reading `Button`, one per
+        // block that embeds a Button, and no reader could tell which component
+        // would change if the symbol did. Which component consumes the symbol
+        // is the fact this verb exists for, so it is the column the row leads
+        // with; the via is BLANK on a record sitting on the block's own tree —
+        // where the data asserts `ds:viaBlock` equal to the block itself —
+        // because "Button via Button" is not news and 24 of Button's rows
+        // would say it.
+        query: [
+          "SELECT ?block ?via ?symbol ?key ?state ?rank ?node ?uri",
+          '       (GROUP_CONCAT(DISTINCT ?variableName; SEPARATOR=" ") AS ?variable)',
+          "WHERE {",
+          "  ?blockUri ds:hasTokenBinding ?uri .",
+          "  ?uri ds:consumesSymbol ?symbolUri .",
+          "  ?symbolUri rdfs:label ?symbol .",
+          "  OPTIONAL { ?uri anatomy:styleKey ?key }",
+          "  OPTIONAL { ?uri anatomy:styleState ?state }",
+          "  OPTIONAL { ?uri ds:rank ?rank }",
+          "  OPTIONAL { ?uri ds:node ?node }",
+          "  OPTIONAL { ?uri ds:viaBlock ?viaUri . OPTIONAL { ?viaUri ds:name ?viaName } }",
+          "  OPTIONAL { ?blockUri ds:name ?blockName }",
+          // Every platform spelling of the consumed symbol, as a SET rather
+          // than a join that multiplies the row: 204 symbols carry both a
+          // kebab and a camelCase variable, and binding one row per variable
+          // would publish each binding twice under names a caller cannot tell
+          // apart. Aggregated, both spellings land in one cell and `--variable`
+          // set-matches either — which is also why the two spellings of one
+          // symbol return the SAME set rather than partitioning it.
+          "  OPTIONAL {",
+          "    ?variableUri dt:ofSymbol ?symbolUri ;",
+          "                 rdfs:label ?variableName .",
+          "  }",
+          '  BIND(COALESCE(?blockName, REPLACE(STR(?blockUri), "^.*[/#]", "")) AS ?block)',
+          // `IF` and not `COALESCE`: the blank says something a MISSING value
+          // cannot, because the via is present on every record and equals the
+          // block on its own tree. SPARQL evaluates only the taken arm of an
+          // `IF`, so the local-name fallback is never asked to name an unbound
+          // via.
+          "  BIND(IF(BOUND(?viaUri) && ?viaUri != ?blockUri,",
+          '        COALESCE(?viaName, REPLACE(STR(?viaUri), "^.*[/#]", "")),',
+          '        "") AS ?via)',
+          "}",
+          "GROUP BY ?block ?via ?symbol ?key ?state ?rank ?node ?uri",
+          // `?via` second, so a block's OWN bindings (blank via, which sorts
+          // first) come before the ones it inherits, and the inherited ones
+          // stay grouped by the block they come from.
+          "ORDER BY ?block ?via ?symbol ?key ?state ?rank ?node",
+        ].join("\n"),
+        // No `uri` COLUMN, though the record's IRI is still SELECTed: it is the
+        // row's subject and what keeps two bindings differing only in state
+        // apart, so `--format json` carries it exactly as before. What it is
+        // not is a cell worth a reader's eye. A binding record is a BLANK NODE,
+        // so it is not addressable — `graph inspect _:dda768d3…` answers
+        // INVALID_INPUT — and a blank node's label is re-minted on every store
+        // load, so the same row printed a different id on every run. And the
+        // `llm` renderer hoists a `uri` column to the HEAD of the line, ahead
+        // of every other cell, which is the slot the consuming block belongs
+        // in; a story cannot reorder that, so the column goes rather than the
+        // block staying second to an unusable id.
+        columns: [
+          { field: "block", label: "Block" },
+          { field: "via", label: "Via" },
+          { field: "symbol", label: "Symbol" },
+          { field: "variable", label: "Variables" },
+          { field: "key", label: "Style key" },
+          { field: "state", label: "State" },
+          { field: "rank", label: "Rank" },
+          { field: "node", label: "Node" },
+        ],
+        filters: [
+          {
+            param: "symbol",
+            variable: "symbol",
+            vocabulary: {
+              query: [
+                "SELECT DISTINCT ?symbol WHERE {",
+                "  ?s a dt:TokenSymbol ;",
+                "     rdfs:label ?symbol .",
+                "}",
+              ].join("\n"),
+            },
+            description: "Filter to one symbol.",
+          },
+          {
+            param: "variable",
+            variable: "variable",
+            // The SAME constraint as `--symbol`, named by the other spelling.
+            // A web implementer holds a CSS custom-property name, not a dotted
+            // symbol, so answering "what breaks if I change --color-text" used
+            // to take two calls and a spelling the caller did not start with.
+            // The join is in the query instead.
+            //
+            // `set`, because the cell is every platform spelling of the
+            // consumed symbol and one row legitimately belongs to all of them.
+            match: "set",
+            // The variable labels, the same source `variable lookup` resolves
+            // against — so a name that works there works here.
+            vocabulary: {
+              query: [
+                "SELECT DISTINCT ?variable WHERE {",
+                "  ?v a dt:Variable ;",
+                "     rdfs:label ?variable .",
+                "}",
+              ].join("\n"),
+            },
+            // Two things a caller will otherwise assume, both wrong.
+            //
+            // A CHANNEL variable and its semantic sibling are DIFFERENT
+            // constraints: `--variable modifier-color-text` finds the blocks
+            // that bind the channel, `--variable color-text` those that bind
+            // the symbol, and neither includes the other. Whether a block's
+            // resolution eventually reaches the other through a fallback is a
+            // question about the consumed list, not about this single-symbol
+            // join, and blurring them here would answer a question nobody
+            // asked with rows nobody can check.
+            //
+            // And a variable standing for NO symbol has no answer down this
+            // path at all — 236 of them do — which is an empty answer for a
+            // reason the recovery below names, not evidence that nothing
+            // consumes it.
+            description:
+              "A CSS variable name for the consumed symbol — the other spelling of the symbol parameter. A channel variable and its semantic sibling differ.",
+          },
+          {
+            param: "key",
+            variable: "key",
+            // The style-key REGISTRY, which the anatomy pack publishes as 111
+            // `anatomy:StyleKey` individuals. Their identity is the IRI and
+            // they carry no key literal, so the admissible spelling is the
+            // IRI's local name with the class prefix its minting adds dropped:
+            // `anatomy:key.appearance.background` is the key
+            // `appearance.background`, which is how the vocabulary's own
+            // examples write it.
+            //
+            // Read from the REGISTRY rather than from the records, and that is
+            // the point: no block has a binding record yet, so a roster read
+            // from records would be empty and would refuse every key a caller
+            // could legitimately ask about. The registry is the graph's
+            // statement of what a key may be; the records are the population.
+            vocabulary: {
+              query: [
+                "SELECT DISTINCT ?key WHERE {",
+                "  ?styleKey a anatomy:StyleKey .",
+                '  BIND(REPLACE(REPLACE(STR(?styleKey), "^.*[/#]", ""), "^key[.]", "") AS ?key)',
+                "}",
+              ].join("\n"),
+            },
+            description: "Filter to one style key.",
+          },
+          {
+            param: "state",
+            variable: "state",
+            // The closed interaction-state vocabulary, read from the shape that
+            // closes it rather than transcribed here: the anatomy pack's shapes
+            // constrain `anatomy:styleState` with an `sh:in` list, so the five
+            // admissible states are a query over that list. Hard-coding them
+            // would be the "don't hard-code the slugs" defect with an extra
+            // step — the graph already says it.
+            vocabulary: {
+              query: [
+                "SELECT DISTINCT ?state WHERE {",
+                "  ?shape sh:path anatomy:styleState ;",
+                "         sh:in/rdf:rest*/rdf:first ?state .",
+                "}",
+              ].join("\n"),
+            },
+            description: "Filter to one interaction state.",
+          },
+        ],
+        search: {
+          variables: ["block", "via", "symbol", "key", "state", "node"],
+          description: "Search block, via, symbol, key, state and node.",
+        },
+        // Deliberately `sources update`: unlike `standard list`, this story's
+        // data does NOT ride the embedded snapshot — the binding records are
+        // written by the design-system packs, so an empty answer here can be a
+        // store that predates them.
+        //
+        // CAN be, not is — which is why the message opens on the two cases
+        // rather than asserting one. This text prints under a filtered miss too
+        // (`--symbol color.text`), where "nothing is recorded at all" would be a
+        // claim the answer cannot support, so it names both readings and hands
+        // the reader the one command that separates them.
+        emptyRecovery: {
+          message:
+            "Either no component uses this token, or no component is recorded as using any token yet — which components use which tokens comes from the component anatomies in the design-system document, and a copy of the graph built before any anatomy named its tokens is empty for every token. Run the same command without `--symbol` to tell the two apart: an empty unfiltered answer means the graph predates the anatomies and fills in once they are written and the graph is rebuilt. If you asked about a CSS variable rather than a token: some variables are computed from others (the `--hover--…` and `--disabled--…` ones, for example) and stand for no token, so nothing is ever recorded as using them; `pragma variable chain --variable <name>` shows what such a variable ends up as.",
+          cli: "sources update",
+        },
+      },
+    ],
+    lookup: {
+      source: "sparql",
+      // `rdfs:label`, matching the `name` the list publishes — the two-step
+      // grammar is that a row's `name` goes VERBATIM to lookup. Both halves
+      // REQUIRE the literal, so both are empty together rather than one
+      // publishing names the other cannot resolve.
+      by: "rdfs:label",
+      type: "dt:TokenSymbol",
+      description:
+        "Look up one or more token symbols by dotted name, IRI, or glob.",
+      toolDescription:
+        'Get one design-token symbol in full: its own type and description, every definition behind it with that definition\'s own type and description, the modifier families that may rebind it, and the value it resolves to at each position. Address it by the dotted name token_list publishes (`color.text`), by prefixed name, by IRI, or by a glob. Example: token_lookup { name: ["color.text"] }.',
+      fields: [
+        // Single-valued: a channel provisions exactly one symbol.
+        {
+          name: "channelOf",
+          property: "dt:channelOf/rdfs:label",
+          label: "Channel of",
+        },
+        // The same pair `token list` publishes, reached the same way: the head
+        // of a resolved value's chain is the definition that value was authored
+        // in, so these two read the symbol's OWN definition rather than
+        // sampling one of the twenty behind `color.text`.
+        //
+        // A lookup field is a property PATH, so it cannot spell the
+        // `FILTER NOT EXISTS` that restricts the list's walk to the BASE value,
+        // and here it does not have to. 354 symbols have more than one chain
+        // head — one per materialised position — and over the shipped corpus no
+        // symbol's heads name two types or two descriptions, so the path is
+        // multi-valued with one value repeated and `firstRowPerEntity` keeping
+        // the first is a choice between identical answers. Were a position's
+        // head ever to differ, the `definitions` expand is where the difference
+        // is readable, because it shows every definition APART.
+        {
+          name: "type",
+          property:
+            "^dt:forSymbol/dt:resolutionChain/rdf:first/dt:tokenType/rdfs:label",
+          label: "Type",
+        },
+        {
+          name: "description",
+          property:
+            "^dt:forSymbol/dt:resolutionChain/rdf:first/w3c-tokens:description",
+          label: "Description",
+        },
+      ],
+      expand: [
+        {
+          name: "definitions",
+          heading: "Definitions",
+          kind: "table",
+          // The inverse edge: definitions point AT the symbol
+          // (`?definition dt:symbol ?uri`), so the relation from the symbol is
+          // `^dt:symbol`. 1,311 definitions stand behind 745 symbols.
+          relation: "^dt:symbol",
+          select: [
+            { name: "file", property: "w3c-tokens:inFile/w3c-tokens:path" },
+            { name: "type", property: "dt:tokenType/rdfs:label" },
+            { name: "description", property: "w3c-tokens:description" },
+          ],
+        },
+        {
+          name: "coverage",
+          heading: "Covered by",
+          // Coverage hangs on the FAMILY, not on the symbol
+          // (`?family dt:covers ?symbol`), so this is the inverse too. The
+          // family is a `ds:` entity, so its name comes from the
+          // design-system pack rather than the token ontology.
+          relation: "^dt:covers",
+          select: [{ name: "family", property: "ds:name" }],
+        },
+        {
+          name: "values",
+          heading: "Values",
+          kind: "table",
+          relation: "^dt:forSymbol",
+          // BOTH the chain and the derivation, for the reason `token values`
+          // states: the shape admits exactly one of them, and selecting only
+          // the chain would blank every channel routing.
+          //
+          // `rdf:first` and NOT `/rdf:rest*/rdf:first`, which is the walk
+          // `token values` uses. An expand's child field is a plain triple with
+          // no aggregate available, so a multi-hop chain multiplies the CHILD:
+          // 204 of the 1,072 values carry a chain of 2 or 3 links, and
+          // `color.background.container` rendered four "Values" rows for its
+          // two positions, each repeating the same value beside a different
+          // link. A caller counting positions would have read that as four.
+          // The head of the list is the definition the value was AUTHORED in
+          // (the tail is what it aliased through to a primitive), so one link
+          // per row is both correct and the most useful one; the full walk is
+          // `token values`, which can GROUP_CONCAT it into a single cell.
+          select: [
+            { name: "position", property: "dt:coordinate" },
+            { name: "value", property: "dt:resolvesTo" },
+            { name: "chain", property: "dt:resolutionChain/rdf:first" },
+            { name: "derivedFrom", property: "dt:derivedFrom/rdfs:label" },
+          ],
+        },
+      ],
+      sample: {
+        fixedCount: true,
+        toolDescription:
+          "Return random complete design-token symbols — definitions, coverage and resolved values — as exemplars. Use BEFORE writing queries to see real data shapes. Example: token_sample {}.",
+      },
+    },
+  },
+
+  // The platform VARIABLES — S4, the stylesheet's own names for the values.
+  //
+  // A SECOND noun rather than a flag on `token`, and one measurement settles
+  // it: 236 of the 1,156 variables stand for NO symbol at all — legacy twins
+  // the ontology itself names, plus the computed states and resets.
+  // `--disabled--color-text` and `--modifier-color-text` are nobody's symbol, so
+  // a surface keyed on symbols cannot address them. The cut is by STRATUM ROLE,
+  // not by platform: the platform is read out of the IRI base as an ordinary
+  // filter, so a second platform's catalogue arrives as one more value of
+  // `--platform` and not as a noun of its own.
+  //
+  // The published name is the label with its leading `--` STRIPPED, and that is
+  // what makes the noun usable at all: `--color-text` cannot be typed as a
+  // positional argument — the parser answers `unknown option '--color-text'`
+  // and a glob is no escape. Upstream publishes the stripped form as
+  // `rdfs:label`, and the stripping is measurably safe: over the 1,156
+  // variables it produces 1,156 distinct names and collides with no symbol
+  // name. `variable.parity.test.ts` pins both halves.
+  {
+    noun: "variable",
+    description:
+      "List the platform variables the design tokens are emitted as.",
+    toolDescription:
+      'List the platform VARIABLES a stylesheet declares as CSS custom properties, with the symbol each stands for, its tier, visibility and the coordinates it is selected at. 236 stand for no symbol, so token_list cannot reach them. Address one WITHOUT its leading dashes (`color-text`). Example: variable_list { symbol: "color.text" }.',
+    list: {
+      query: [
+        "SELECT ?uri ?name ?platform ?symbol ?tier ?visibility",
+        '       (GROUP_CONCAT(DISTINCT ?coordinateName; SEPARATOR=" ") AS ?coordinate)',
+        "WHERE {",
+        "  ?uri a dt:Variable ;",
+        "       rdfs:label ?name .",
+        "  OPTIONAL { ?uri dt:ofSymbol/rdfs:label ?symbol }",
+        "  OPTIONAL { ?uri dt:tier ?tierUri }",
+        "  OPTIONAL { ?uri dt:visibility ?visibilityUri }",
+        // A variable is selected at a coordinate two ways, and both count: the
+        // CONDITION its declaration sits under selects one
+        // (`.success` → `criticality.success`), and a declaration may assert a
+        // second directly (`dt:alsoAt`, which is `mode.dark` for all 261 of
+        // them). 305 of the 1,156 variables reach at least one coordinate.
+        "  OPTIONAL {",
+        "    { ?uri dt:declaredAt/dt:under/dt:selectsCoordinate ?coordinateUri }",
+        "    UNION",
+        "    { ?uri dt:declaredAt/dt:alsoAt ?coordinateUri }",
+        '    BIND(REPLACE(REPLACE(STR(?coordinateUri), "^.*[/#]", ""), "^coordinate[.]", "") AS ?coordinateName)',
+        "  }",
+        // The platform, read out of the IRI base rather than asserted: every
+        // variable is minted under `…/s4/<platform>/`. STRAFTER/STRBEFORE
+        // rather than a regex so a variable whose IRI carries no such segment
+        // answers an EMPTY cell instead of its own full IRI, which is what a
+        // failed REPLACE returns.
+        '  BIND(STRBEFORE(STRAFTER(STR(?uri), "/s4/"), "/") AS ?platform)',
+        '  BIND(REPLACE(REPLACE(STR(?tierUri), "^.*[/#]", ""), "^tier[.]", "") AS ?tier)',
+        '  BIND(REPLACE(REPLACE(STR(?visibilityUri), "^.*[/#]", ""), "^visibility[.]", "") AS ?visibility)',
+        "}",
+        "GROUP BY ?uri ?name ?platform ?symbol ?tier ?visibility",
+        "ORDER BY ?name",
+      ].join("\n"),
+      columns: [
         { field: "name", label: "Name" },
-        { field: "category", label: "Type" },
+        { field: "symbol", label: "Symbol" },
+        { field: "tier", label: "Tier" },
+        { field: "visibility", label: "Visibility" },
+        { field: "platform", label: "Platform" },
+        { field: "coordinate", label: "Coordinates" },
+        { field: "uri", label: "IRI" },
+      ],
+      filters: [
+        {
+          param: "platform",
+          variable: "platform",
+          // The vocabulary is a query over the IRI base, exactly as the column
+          // is — the platform is not asserted anywhere, so the file identity
+          // in the IRI is the only thing that states it. One value today
+          // (`web`); a second platform's catalogue adds itself here with no
+          // edit.
+          vocabulary: {
+            query: [
+              "SELECT DISTINCT ?platform WHERE {",
+              "  ?v a dt:Variable .",
+              '  BIND(STRBEFORE(STRAFTER(STR(?v), "/s4/"), "/") AS ?platform)',
+              "}",
+            ].join("\n"),
+          },
+          description: "Filter by platform.",
+        },
+        {
+          param: "symbol",
+          variable: "symbol",
+          // The symbol roster, read the same way `token list`'s `channelOf`
+          // filter reads it: every symbol, keyed on `rdfs:label`.
+          vocabulary: {
+            query: [
+              "SELECT DISTINCT ?symbol WHERE {",
+              "  ?s a dt:TokenSymbol ;",
+              "     rdfs:label ?symbol .",
+              "}",
+            ].join("\n"),
+          },
+          description: "Filter to one symbol.",
+        },
+        {
+          param: "tier",
+          variable: "tier",
+          vocabulary: {
+            query: [
+              "SELECT DISTINCT ?tier WHERE {",
+              "  ?t a dt:Tier .",
+              '  BIND(REPLACE(REPLACE(STR(?t), "^.*[/#]", ""), "^tier[.]", "") AS ?tier)',
+              "}",
+            ].join("\n"),
+          },
+          description: "Filter by tier.",
+        },
+        {
+          param: "visibility",
+          variable: "visibility",
+          vocabulary: {
+            query: [
+              "SELECT DISTINCT ?visibility WHERE {",
+              "  ?v a dt:Visibility .",
+              '  BIND(REPLACE(REPLACE(STR(?v), "^.*[/#]", ""), "^visibility[.]", "") AS ?visibility)',
+              "}",
+            ].join("\n"),
+          },
+          description: "Filter by visibility.",
+        },
+        {
+          param: "coordinate",
+          variable: "coordinate",
+          // `set`, and it has to be: `--modifier-color-text` is selected at 17
+          // coordinates at once, so its cell is the whole set its declarations
+          // reach and a filter comparing the whole cell would answer for none
+          // of them. The cell is a `GROUP_CONCAT`, so this predicate can only
+          // run after aggregation — which is why the page wraps the query.
+          match: "set",
+          vocabulary: {
+            query: [
+              "SELECT DISTINCT ?coordinate WHERE {",
+              "  ?c a dt:Coordinate .",
+              '  BIND(REPLACE(REPLACE(STR(?c), "^.*[/#]", ""), "^coordinate[.]", "") AS ?coordinate)',
+              "}",
+            ].join("\n"),
+          },
+          description: "Filter to one coordinate.",
+        },
       ],
+      search: {
+        variables: ["name", "symbol"],
+        description: "Search name and symbol.",
+      },
       emptyRecovery: {
         message:
-          "No tokens in the store. Build it from the configured design-system packs.",
+          "Platform variables come from the @canonical/token-ontology pack, and a variable is only addressable once that pack publishes its name literals — a store built without that pack carries none.",
         cli: "sources update",
       },
     },
+    verbs: [
+      {
+        verb: "chain",
+        description:
+          "List the walk from a variable to every symbol it reaches, through every variable in between.",
+        toolDescription:
+          'List the resolution WALK: every (variable, symbol) pair a variable reaches through what its declarations reference, transitively — what a variable finally means. The closure runs over every declaration of every hop, so one variable can reach dozens of pairs. Example: variable_chain { variable: "modifier-color-text" }.',
+        // ONE property path carries the whole walk, which is why this is a
+        // query and not a traversal in code. `dt:references` is an rdf:List of
+        // the variables a declaration's value reads, so each hop is
+        // `dt:declaredAt/dt:references/rdf:rest*/rdf:first`, and the `+` makes
+        // the whole thing transitive. The terminal is a variable that stands
+        // for a symbol, which is what `dt:ofSymbol` reads.
+        query: [
+          "SELECT ?variable ?reaches ?symbol",
+          "WHERE {",
+          "  ?uri a dt:Variable ;",
+          "       rdfs:label ?variable .",
+          "  ?uri (dt:declaredAt/dt:references/rdf:rest*/rdf:first)+ ?reachedUri .",
+          "  ?reachedUri dt:ofSymbol ?symbolUri ;",
+          "              rdfs:label ?reaches .",
+          "  ?symbolUri rdfs:label ?symbol .",
+          "}",
+          "ORDER BY ?variable ?reaches ?symbol",
+        ].join("\n"),
+        columns: [
+          { field: "variable", label: "Variable" },
+          { field: "reaches", label: "Reaches" },
+          { field: "symbol", label: "Symbol" },
+        ],
+        filters: [
+          {
+            param: "variable",
+            variable: "variable",
+            // The variable roster, keyed on the same `rdfs:label` the column
+            // binds and the lookup resolves by — the CSS name with its leading
+            // `--` already stripped, which is the only form typable as a
+            // positional. `variable.parity.test.ts` pins that the stripping is
+            // injective and collides with no symbol name.
+            vocabulary: {
+              query: [
+                "SELECT DISTINCT ?variable WHERE {",
+                "  ?v a dt:Variable ;",
+                "     rdfs:label ?variable .",
+                "}",
+              ].join("\n"),
+            },
+            description: "Filter to one variable.",
+          },
+          {
+            param: "symbol",
+            variable: "symbol",
+            vocabulary: {
+              query: [
+                "SELECT DISTINCT ?symbol WHERE {",
+                "  ?s a dt:TokenSymbol ;",
+                "     rdfs:label ?symbol .",
+                "}",
+              ].join("\n"),
+            },
+            description: "Filter to one symbol.",
+          },
+        ],
+        emptyRecovery: {
+          message:
+            "A resolution walk follows the declarations the @canonical/token-ontology pack provides, and the walk is only addressable by name once that pack publishes its name literals — a store built without that pack carries none.",
+          cli: "sources update",
+        },
+      },
+    ],
     lookup: {
       source: "sparql",
-      by: "ds:tokenId",
-      type: "ds:Token",
+      // `rdfs:label`, matching the `name` the list publishes, and with NO
+      // `nameFallback` for the same reason `token` has none: the kernel's IRI
+      // derivation would publish `--color-text` with its dashes intact and its
+      // dots as slashes, and a `--`-prefixed positional cannot be typed at all.
+      by: "rdfs:label",
+      type: "dt:Variable",
+      description:
+        "Look up one or more platform variables by name (without the leading dashes), IRI, or glob.",
       toolDescription:
-        'Get type and theme values for one or more design tokens by name. Use when resolving specific tokens\' light/dark values. Example: token_lookup { name: ["color.primary"] }.',
+        'Get one platform variable in full: its symbol, tier, visibility, and EVERY place it is declared — the selector and at-rule stack, the emitted value, the source location, the coordinate it also applies at, and the derivation. Address it by the CSS name WITHOUT its leading dashes (`color-text`). Example: variable_lookup { name: ["color-text"] }.',
       fields: [
+        { name: "symbol", property: "dt:ofSymbol/rdfs:label", label: "Symbol" },
+        { name: "tier", property: "dt:tier", label: "Tier" },
+        { name: "visibility", property: "dt:visibility", label: "Visibility" },
+      ],
+      expand: [
         {
-          name: "category",
-          property: "ds:tokenType/rdfs:label",
-          label: "Type",
+          name: "declarations",
+          heading: "Declarations",
+          kind: "table",
+          relation: "dt:declaredAt",
+          // 927 variables are declared once; the rest up to 17 times, which is
+          // why this is an expand and not a set of fields.
+          select: [
+            { name: "under", property: "dt:under" },
+            { name: "selector", property: "dt:under/dt-web:selector" },
+            // The at-rule STACK, not one at-rule: `dt-web:inAtRule` is an
+            // rdf:List, so the walk is `/rdf:rest*/rdf:first`. One condition of
+            // the 31 nests two levels deep and so contributes two rows for one
+            // declaration — that is the stack, read outermost-in, rather than a
+            // duplicate.
+            {
+              name: "inAtRule",
+              property: "dt:under/dt-web:inAtRule/rdf:rest*/rdf:first",
+            },
+            { name: "emits", property: "dt:emits" },
+            // `dt:at` is the SOURCE LOCATION (`modifiers.theme.css:322`), not a
+            // coordinate; `dt:alsoAt` is the coordinate. The two read alike and
+            // mean different things, which is why both are labelled.
+            { name: "at", property: "dt:at", label: "source" },
+            { name: "alsoAt", property: "dt:alsoAt", label: "alsoAt" },
+            { name: "derives", property: "dt:derives" },
+          ],
         },
-        { name: "valueLight", property: "ds:valueLight", label: "Light value" },
-        { name: "valueDark", property: "ds:valueDark", label: "Dark value" },
       ],
       sample: {
         fixedCount: true,
         toolDescription:
-          "Return randomly selected complete design tokens (with theme values) as exemplars. Use BEFORE writing queries to see actual data shapes. Example: token_sample {}.",
+          "Return random complete platform variables — symbol, tier, visibility and every declaration — as exemplars. Use BEFORE writing queries to see real data shapes. Example: variable_sample {}.",
       },
     },
   },
@@ -394,6 +1286,16 @@ const designSystemStories: readonly PackDefinition[] = [
     description: "List all modifier families.",
     toolDescription:
       "List all modifier families with their values. Use when browsing which modifier families exist and the values each allows. Example: modifier_list {}.",
+    // Tiered like blocks — 11 of the modifier families carry a `ds:tier` — so
+    // the same scope, declared with the same four terms. The scope is per NOUN
+    // because being tiered is a fact about the entities, and the design
+    // system's token symbols and code standards carry nothing of the kind.
+    tierScope: {
+      type: "ds:Tier",
+      via: "ds:tier",
+      by: "ds:name",
+      base: "ds:global",
+    },
     list: {
       query: [
         "SELECT ?uri ?name",
@@ -454,7 +1356,7 @@ const designSystemStories: readonly PackDefinition[] = [
     noun: "tier",
     description: "List all tiers in the design system ontology.",
     toolDescription:
-      "List all tiers in the design-system ontology. Use when understanding the tier hierarchy before setting a tier filter. Example: tier_list {}.",
+      "List all tiers in the design-system ontology. Use when picking the tier to read with: the `tier` parameter scopes a read to one tier plus its ancestors, and this list is never scoped itself. Example: tier_list {}.",
     list: {
       query: [
         "SELECT ?uri ?name WHERE {",
@@ -498,6 +1400,16 @@ const conceptStory: PackDefinition = {
   description: "List design-system concepts.",
   toolDescription:
     'List design-system concepts — long-form foundations, how-to guides, and decision guides not bound to a single UI block. Optionally filter by type or search. Example: concept_list { type: "Explanation" }.',
+  // Concepts carry a `ds:tier` too (4 of them do), so they are scoped on the
+  // same terms as blocks and modifier families. Its `list` publishes no tier
+  // COLUMN and does not need to: the scope constrains the entity through
+  // `ds:tier`, not a projected cell.
+  tierScope: {
+    type: "ds:Tier",
+    via: "ds:tier",
+    by: "ds:name",
+    base: "ds:global",
+  },
   list: {
     query: [
       "SELECT ?uri ?name ?type ?summary",
@@ -542,7 +1454,7 @@ const conceptStory: PackDefinition = {
     },
     emptyRecovery: {
       message:
-        "No concepts in the store. The @canonical/design-system pack provides them; refresh the local store.",
+        "Concepts come from the @canonical/design-system pack, and a local store built without it carries none — refresh it.",
       cli: "sources update",
     },
   },
@@ -671,7 +1583,7 @@ const implementationStory: PackDefinition = {
     },
     emptyRecovery: {
       message:
-        "No implementations in the store. The @canonical/ds-implementations pack provides them; refresh the local store.",
+        "Implementations come from the @canonical/ds-implementations pack, and a local store built without it carries none — refresh it.",
       cli: "sources update",
     },
   },
@@ -871,10 +1783,23 @@ const codeStandardsStories: readonly PackDefinition[] = [
       // because a pack is data — a future release that drops a label should
       // degrade to the IRI-derived name, not become unaddressable.
       //
-      // Deliberately NOT declared on `block`/`token`/`tier`/`concept`: each of
-      // those lists REQUIRES its `by` property, so an entity without one is a
-      // row they never publish, and making it addressable (or sampleable) here
-      // would be the mirror of the defect this repairs.
+      // Deliberately NOT declared on `token`/`modifier`/`tier`/`concept`:
+      // each of those lists REQUIRES its `by` property, so an entity without
+      // one is a row they never publish, and making it addressable (or
+      // sampleable) here would be the mirror of the defect this repairs.
+      //
+      // `block` is NOT in that set, though an earlier version of this comment
+      // claimed it was: its list COALESCEs an OPTIONAL `ds:name` with an
+      // IRI-derived fallback, so a block without a `ds:name` WOULD be
+      // published under a name its lookup cannot resolve. Every shipped block
+      // carries `ds:name` today, so the divergence is latent — and pinned:
+      // `listLookup.shipped.exec.test.ts` runs the whole corpus through both
+      // halves on every test run, and goes red the moment upstream ships an
+      // unnamed block. Fix it THEN, by choosing deliberately between requiring
+      // the name in the list and declaring a fallback pair whose derivations
+      // actually agree (the list keeps the IRI's dots; the shared
+      // `nameFallback` derivation converts them to slashes — declaring the
+      // fallback alone would trade one mismatch for another).
       nameFallback: "iri",
       type: "cs:CodeStandard",
       description:
@@ -982,7 +1907,20 @@ Made by the Canonical Webteam — https://canonical.com.`,
       name: "@canonical/anatomy-dsl",
       source: "git+https://github.com/canonical/anatomy-dsl.git#main",
     },
-    // Pinned to a TAG, and the only source here that is. The standards are the
+    // The design-token semantic model: the authored `dt:` / `w3c-tokens:`
+    // ontology in `definitions/` plus the generated strata in `data/`.
+    //
+    // The only source here carrying a SUBDIRECTORY, and it needs one: this
+    // package lives inside a monorepo, at `packages/token-ontology`, while a
+    // git source names a repository. `readTtlSources` scans
+    // `<root>/definitions` and `<root>/data`, which the design-tokens repo
+    // root does not have — so without the subdirectory this would clone
+    // cleanly and contribute nothing.
+    {
+      name: "@canonical/token-ontology",
+      source:
+        "git+https://github.com/canonical/design-tokens.git#main:packages/token-ontology",
+    },
     // pack an agent is most likely to quote back at a human as policy, so which
     // revision answered a query has to be recoverable — a floating ref makes
     // "the CLI told me this was the rule" unfalsifiable. The other three still
@@ -1023,6 +1961,11 @@ Made by the Canonical Webteam — https://canonical.com.`,
   // `cs:` is listed even though nothing rebinds it upstream.
   prefixes: {
     ds: "https://ds.canonical.com/",
+    dt: "https://dt.canonical.com/",
+    // Nested UNDER `dt:`, and both must be bound: `compactUri` takes the
+    // longest match, so binding only the parent would render every term of
+    // this vocabulary as `dt:w3c-tokens/…`.
+    "w3c-tokens": "https://dt.canonical.com/w3c-tokens/",
     cs: "http://pragma.canonical.com/codestandards#",
   },
   channel: "normal",