@canonical/pragma-cli 0.35.0 → 0.36.0

package/pragma.conf.ts

@@ -97,8 +97,30 @@ const designSystemStories: readonly PackDefinition[] = [
   // Base level mirrors the old summary view (name/tier/summary); the default is
   // `detailed`, matching the old CLI which rendered anatomy and modifiers
   // without a flag. A derived name that maps onto no schema field is omitted
-  // (OPTIONAL parity), so a graph lacking whenToUse/whenNotToUse degrades
-  // gracefully.
+  // (OPTIONAL parity), so a graph missing one of these properties degrades
+  // gracefully rather than erroring.
+  //
+  // That graceful degradation is also how this story went silent: it used to
+  // read `ds:whenToUse`/`ds:whenNotToUse`, which the ontology RETIRED in favour
+  // of a single `ds:usage` — "Subsumes the former whenToUse/whenNotToUse" is
+  // that property's own skos:definition. The shipped pack asserts `ds:usage` on
+  // all 264 blocks and neither retired term on any of them, so every
+  // `block lookup` on every install rendered no usage narrative at all —
+  // silently, because a name that maps onto no schema field is exactly the case
+  // OPTIONAL parity swallows. The retired terms are NOT kept as a fallback:
+  // `ds:usage` subsumes them, so a pack carrying both would print the same
+  // guidance twice, and a declaration no shipped graph can satisfy is
+  // untestable by construction — which is what let the silence ship.
+  // `block.shipped.exec.test.ts` now holds every graph term declared here — the
+  // identity property, fields, sections, expand relations, and every term
+  // selected beneath them, walked recursively — to being DEFINED as a property
+  // by the SHIPPED ontology. Defined, not asserted, and the difference is the
+  // whole point: a term the ontology never defines is a story bug that can
+  // never render, on any block, on any install — this defect. A term it defines
+  // that no instance asserts yet (`ds:figmaLink` today) is a content gap
+  // upstream, which the OPTIONAL parity above degrades over gracefully and
+  // which this pack has no business failing on. `ds:usage` alone is ALSO held
+  // to being asserted, on every block, because its absence is what shipped.
   //
   // Disclosure declares the FULL canonical ladder `[summary, standard,
   // detailed]` — the same set `standard` declares — so a config
@@ -121,14 +143,33 @@ const designSystemStories: readonly PackDefinition[] = [
         "  VALUES ?class { ds:Component ds:Pattern ds:Layout ds:Subcomponent }",
         "  ?uri a ?class .",
         "  OPTIONAL { ?uri ds:name ?dsName }",
-        "  OPTIONAL { ?uri ds:tier ?tierUri }",
+        "  OPTIONAL { ?uri ds:tier ?tierUri . OPTIONAL { ?tierUri ds:name ?tierName } }",
         "  OPTIONAL { ?uri ds:hasModifierFamily ?family . ?family ds:name ?modName }",
         '  BIND(COALESCE(?dsName, REPLACE(STR(?uri), "^.*[/#]", "")) AS ?name)',
         '  BIND(LCASE(REPLACE(STR(?class), "^.*[/#]", "")) AS ?type)',
         '  BIND(REPLACE(STR(?tierUri), "^.*[/#]", "") AS ?tier)',
+        // `ORDER BY ?name` alone is not a total order, and 25 names here are
+        // shared by two or three blocks. SPARQL says nothing about tied rows,
+        // so the store's scan decided: ONE run gave `Button` launchpad-first
+        // and `CheckboxInput` global-first. Tier depth, then `STR(?uri)`,
+        // makes it total — the shallower tier leads its name group, and equal
+        // depths fall back to a key that cannot tie.
+        //
+        // The depth is the same one `lookup` ranks by, spelled out because a
+        // list query is declared TEXT the kernel does not compose. Only the
+        // depth: a browse ordered by NAME is not the place to re-litigate which
+        // block the name MEANS (that is `lookup`'s ranking, which also weighs
+        // the block's type), and every row here already prints its own type.
+        //
+        // The depth-0 IF is the store's, not style: oxigraph raises on
+        // `0.2 * 0`, and a raising BIND leaves `?tierRank` unbound — which is
+        // exactly how a top-tier block silently sorted last (see
+        // `sparqlProduct` in kernel/packs/sparql/buildLookupQuery.ts).
+        '  BIND(STRLEN(?tierName) - STRLEN(REPLACE(?tierName, "/", "")) AS ?tierDepth)',
+        "  BIND(COALESCE(IF(?tierDepth = 0, 1, 1 - (0.2 * ?tierDepth)), 0) AS ?tierRank)",
         "}",
-        "GROUP BY ?uri ?name ?type ?tier",
-        "ORDER BY ?name",
+        "GROUP BY ?uri ?name ?type ?tier ?tierRank",
+        "ORDER BY ?name DESC(?tierRank) STR(?uri)",
       ].join("\n"),
       columns: [
         { field: "name", label: "Name" },
@@ -153,9 +194,41 @@ const designSystemStories: readonly PackDefinition[] = [
       // for the query "button" the 86 `…-close_button` subcomponents used to
       // outrank `ds:global.component.button` on the alphabet alone. Weighting
       // them below 1 sinks every one of them under every component at equal
-      // match score, and lowers their `annotations.priority` in the resource
-      // listing by the same declaration.
+      // match score, lowers their `annotations.priority` in the resource
+      // listing, and — since a name resolve now RANKS rather than picks — sorts
+      // them under every component a shared name also reaches.
       weights: { "ds:Subcomponent": 0.6 },
+      // The other half of that judgement, and the reason it is a PRODUCT and
+      // not a tiebreak. 25 live block names are shared by two or three blocks
+      // across tiers, and `weights` alone cannot separate two components; the
+      // alphabet decided, so `Button` answered with Launchpad's and never
+      // mentioned the global one. A tier's DEPTH is what ranks it: `Global` is
+      // depth 1 and worth 1, `Apps/Launchpad` is depth 2 and worth 0.8, so
+      //
+      //   Button    global component 1 × 1   >  launchpad component 1 × 0.8
+      //   TextInput global SUBcomponent 0.6 × 1  <  launchpad component 1 × 0.8
+      //
+      // — the global block wins where both are whole blocks, and the editorial
+      // rule that a whole component beats a part survives the addition. A pure
+      // tier tiebreak would have inverted the second case.
+      //
+      // DERIVED, never enumerated: the depth is the `/` count in the tier's
+      // OWN `ds:name` (`"Apps/Launchpad"`), not in its IRI (`ds:apps_launchpad`
+      // — the slash exists only in the name), so a tier added upstream tomorrow
+      // is ranked correctly without editing anything here.
+      //
+      // Declared as DATA beside `weights` for the same reason `weights` is:
+      // editorial judgement the ontology has not yet made belongs in the config
+      // layer, which "wins every harvest" when upstream is silent. `asserted`
+      // is the exit: the day `ds:tierRank` is asserted upstream it takes
+      // precedence over the derived depth (`COALESCE`), and this whole entry is
+      // deleted with no code change.
+      scopeWeight: {
+        via: "ds:tier",
+        by: "ds:name",
+        falloff: 0.2,
+        asserted: "ds:tierRank",
+      },
       graphqlType: "UIBlock",
       fields: [
         { name: "tier", property: "ds:tier", label: "Tier" },
@@ -168,16 +241,19 @@ const designSystemStories: readonly PackDefinition[] = [
       ],
       sections: [
         { name: "summary", property: "ds:summary", label: "Summary" },
+        // ONE section, because `ds:usage` is ONE property: its literal is
+        // free-text Markdown carrying its own `### When to use` / `### When not
+        // to use` sub-sections (78 and 71 of the 126 non-empty ones do), so
+        // splitting it back into two headings here would mean parsing prose the
+        // graph deliberately keeps whole. The renderer demotes a body's own ATX
+        // headings below the section heading, so those sub-sections nest UNDER
+        // `### Usage` instead of colliding with it. Half the blocks assert an
+        // EMPTY `ds:usage` (138 of 264); the renderer skips empty sections, so
+        // those print no heading rather than an empty one.
         {
-          name: "whenToUse",
-          property: "ds:whenToUse",
-          label: "When to use",
-          level: "detailed",
-        },
-        {
-          name: "whenNotToUse",
-          property: "ds:whenNotToUse",
-          label: "When not to use",
+          name: "usage",
+          property: "ds:usage",
+          label: "Usage",
           level: "detailed",
         },
         {
@@ -246,7 +322,7 @@ const designSystemStories: readonly PackDefinition[] = [
       sample: {
         fixedCount: true,
         toolDescription:
-          "Return randomly selected complete design-system blocks as exemplars. Use BEFORE writing queries to see actual data shapes, anatomy, and property names.",
+          "Return randomly selected complete design-system blocks as exemplars. Use BEFORE writing queries to see actual data shapes, anatomy, and property names. Example: block_sample {}.",
       },
     },
   },
@@ -303,7 +379,7 @@ const designSystemStories: readonly PackDefinition[] = [
       sample: {
         fixedCount: true,
         toolDescription:
-          "Return randomly selected complete design tokens (with theme values) as exemplars. Use BEFORE writing queries to see actual data shapes.",
+          "Return randomly selected complete design tokens (with theme values) as exemplars. Use BEFORE writing queries to see actual data shapes. Example: token_sample {}.",
       },
     },
   },
@@ -361,7 +437,7 @@ const designSystemStories: readonly PackDefinition[] = [
       sample: {
         fixedCount: true,
         toolDescription:
-          "Return randomly selected complete modifier families (with value lists) as exemplars. Use BEFORE writing queries to see actual data shapes.",
+          "Return randomly selected complete modifier families (with value lists) as exemplars. Use BEFORE writing queries to see actual data shapes. Example: modifier_sample {}.",
       },
     },
   },
@@ -421,7 +497,7 @@ const conceptStory: PackDefinition = {
   noun: "concept",
   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.",
+    '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" }.',
   list: {
     query: [
       "SELECT ?uri ?name ?type ?summary",
@@ -443,6 +519,20 @@ const conceptStory: PackDefinition = {
       {
         param: "type",
         variable: "type",
+        // `ds:ConceptType` is the vocabulary; the concepts are the population.
+        // The shipped graph declares six types and uses two, so validating
+        // against the rows rejected "Decision guide" — a type the ontology
+        // declares — as an invalid argument instead of answering with the
+        // empty list it actually has.
+        vocabulary: {
+          query: [
+            "SELECT DISTINCT ?name WHERE {",
+            "  ?conceptType a ds:ConceptType ;",
+            "               ds:name ?name .",
+            "}",
+          ].join("\n"),
+          variable: "name",
+        },
         description: "Filter by concept type (e.g. Explanation, How-to guide).",
       },
     ],
@@ -463,7 +553,7 @@ const conceptStory: PackDefinition = {
     description:
       "Look up a concept's full documentation by name, IRI, or glob.",
     toolDescription:
-      "Get a design-system concept's full Markdown documentation. Address concepts by name, prefixed name (ds:concept.…), absolute IRI, or glob pattern.",
+      'Get a design-system concept\'s full Markdown documentation. Address concepts by the name concept_list publishes, by prefixed name (ds:concept.…), by absolute IRI, or by a glob. Example: concept_lookup { name: ["Foundations: Grid"] }.',
     fields: [
       { name: "type", property: "ds:conceptType/ds:name", label: "Type" },
       { name: "tier", property: "ds:tier", label: "Tier" },
@@ -544,14 +634,34 @@ const implementationStory: PackDefinition = {
       { field: "uri", label: "IRI" },
     ],
     filters: [
+      // Both vocabularies are read off `ds:ImplementationLibrary`, the subject
+      // that carries them — the same terms `implementation libraries`
+      // enumerates. A library that implements nothing yet still exists, and
+      // asking for it is an empty answer rather than a bad argument.
       {
         param: "platform",
         variable: "platform",
+        vocabulary: {
+          query: [
+            "SELECT DISTINCT ?platform WHERE {",
+            "  ?lib a ds:ImplementationLibrary ;",
+            "       ds:platform ?platform .",
+            "}",
+          ].join("\n"),
+        },
         description: "Filter by platform (e.g. react, svelte, typescript).",
       },
       {
         param: "library",
         variable: "library",
+        vocabulary: {
+          query: [
+            "SELECT DISTINCT ?library WHERE {",
+            "  ?lib a ds:ImplementationLibrary ;",
+            "       ds:libraryName ?library .",
+            "}",
+          ].join("\n"),
+        },
         description: "Filter by implementation library name.",
       },
     ],
@@ -618,20 +728,44 @@ const codeStandardsStories: readonly PackDefinition[] = [
     noun: "standard",
     description: "List all code standards.",
     toolDescription:
-      "List code standards. Optionally filter by category or search term.",
+      'List code standards: one ROW per standard — its IRI, name, category and description — not the standards themselves. Take a row\'s `name` VERBATIM to standard_lookup for the dos and donts. Optionally filter by category slug (a parent slug answers for its whole branch; standard_categories lists them) or by search term. Example: standard_list { category: "react" }.',
     list: {
       query: [
+        // `?category` is the LEAF a standard is filed under — what a row
+        // displays. `?categories` is that leaf plus every ancestor, which is
+        // what `--category` matches against, so asking for a parent answers for
+        // the whole branch. The traversal is written ONCE, here, rather than
+        // repeated by each consumer.
         "SELECT ?uri ?name ?category ?description",
+        '       (GROUP_CONCAT(DISTINCT ?ancestorSlug; SEPARATOR=" ") AS ?categories)',
         "WHERE {",
         "  ?uri a cs:CodeStandard ;",
         "       cs:description ?description .",
-        "  OPTIONAL { ?uri cs:name ?n . }",
+        // `rdfs:label`, matching `lookup.by` below. Both COALESCE over the
+        // SAME property with the SAME IRI fallback, and that agreement IS the
+        // two-step grammar: a row's `name` goes VERBATIM to lookup. Keyed on
+        // different properties they diverge for exactly the entities carrying
+        // one and not the other — 16 standards in the shipped snapshot
+        // published `Turtle local-name casing` from `cs:name` while lookup,
+        // reading `rdfs:label`, bound the derived slug and answered
+        // ENTITY_NOT_FOUND. Change one, change both.
+        "  OPTIONAL { ?uri rdfs:label ?n . }",
         '  BIND(COALESCE(?n, REPLACE(STRAFTER(STR(?uri), "#"), "\\\\.", "/")) AS ?name)',
         "  OPTIONAL {",
         "    ?uri cs:hasCategory ?cat .",
         "    ?cat cs:slug ?category .",
+        // `skos:broader` is deliberately NOT transitive, and this store
+        // (oxigraph) has no reasoner — so `skos:broaderTransitive` returns zero
+        // rows and hand-asserting it would be materialisation wearing a
+        // standards badge. `broader*` is the only thing that works.
+        // The `*` is REFLEXIVE and that is load-bearing: `+` would silently
+        // drop every standard filed DIRECTLY on the category being asked for
+        // (one of the 8 under `testing` today). Do not "correct" it.
+        "    ?cat skos:broader* ?ancestor .",
+        "    ?ancestor cs:slug ?ancestorSlug .",
         "  }",
         "}",
+        "GROUP BY ?uri ?name ?category ?description",
         "ORDER BY ?name",
       ].join("\n"),
       columns: [
@@ -643,28 +777,64 @@ const codeStandardsStories: readonly PackDefinition[] = [
       filters: [
         {
           param: "category",
-          variable: "category",
-          description: "Filter by category name.",
+          variable: "categories",
+          match: "set",
+          // The SAME terms `standard categories` enumerates (`cs:Category` /
+          // `cs:slug`), so the slugs that surface hands out are exactly the
+          // slugs this filter accepts. Read from the graph rather than the
+          // returned ROWS: a category the graph declares with no standards
+          // filed under it is reported by `standard categories` with count 0,
+          // and asking for it must be the documented calm empty list, not
+          // INVALID_INPUT.
+          vocabulary: {
+            query: [
+              "SELECT DISTINCT ?slug WHERE {",
+              "  ?cat a cs:Category ;",
+              "       cs:slug ?slug .",
+              "}",
+            ].join("\n"),
+            variable: "slug",
+          },
+          description:
+            "Filter by category slug. A parent category answers for its whole branch.",
         },
       ],
       search: {
         variables: ["name", "description"],
         description: "Search in name and description.",
       },
+      // Deliberately NOT `sources update`: the code standards ship in the
+      // embedded snapshot and answer with no update at all, so the generic
+      // build hint is actively wrong here. An empty result on this noun means
+      // the filter, and the vocabulary it must be drawn from lives in the graph
+      // — which is what `standard categories` reads out.
+      emptyRecovery: {
+        message:
+          "Category slugs come from the graph, and a parent slug answers for its whole branch — read them out rather than guessing.",
+        cli: "standard categories",
+      },
     },
     verbs: [
       {
         verb: "categories",
-        description: "List all standard categories with counts.",
-        toolDescription: "List all code standard categories.",
+        description:
+          "List all standard categories with counts (a parent counts its whole branch).",
+        toolDescription:
+          "List all code standard categories with the number of standards each covers. Categories are a hierarchy: a parent's count includes every descendant, and `standard_list { category }` answers for the same set. Use this to pick a valid slug before filtering. Example: standard_categories {}.",
         query: [
-          "SELECT ?name (COUNT(?standard) AS ?count)",
+          // The same reflexive roll-up `list` filters with — written the other
+          // way round (every category whose broader-chain reaches ?cat), so the
+          // count a category reports and the rows `--category` returns are the
+          // same set. `COUNT(DISTINCT ?standard)`: a standard reachable by two
+          // paths is still one standard.
+          "SELECT ?name (COUNT(DISTINCT ?standard) AS ?count)",
           "WHERE {",
           "  ?cat a cs:Category ;",
           "       cs:slug ?name .",
           "  OPTIONAL {",
+          "    ?descendant skos:broader* ?cat .",
           "    ?standard a cs:CodeStandard ;",
-          "              cs:hasCategory ?cat .",
+          "              cs:hasCategory ?descendant .",
           "  }",
           "}",
           "GROUP BY ?name",
@@ -674,16 +844,43 @@ const codeStandardsStories: readonly PackDefinition[] = [
           { field: "name", label: "Category" },
           { field: "count", label: "Standards" },
         ],
+        // Also not `sources update`. The categories ride the same embedded
+        // snapshot, so zero rows means the store did not load — a health
+        // question, not a staleness one.
+        emptyRecovery: {
+          message:
+            "The code standards ship with the CLI itself, so no categories at all means the store did not load — not that it is out of date.",
+          cli: "doctor",
+        },
       },
     ],
     lookup: {
       source: "sparql",
-      by: "cs:name",
+      // `rdfs:label`, not `cs:name`. The pack pin above moved to v0.1.5, which
+      // retired the bespoke `cs:name` for the standard property every RDF
+      // consumer already reads — measured against that tag: 0 standards carry
+      // `cs:name`, 148 of 148 carry exactly one `rdfs:label`. Left keyed on the
+      // retired property, this story would still ANSWER — every title would
+      // simply stop reaching a reader and each row would fall back to its
+      // IRI-derived name, with nothing raised. That is the same silent shape as
+      // reading a retired `ds:whenToUse`, one noun over.
+      by: "rdfs:label",
+      // The fallback stays, and is now near-inert rather than load-bearing: it
+      // covered the ~87% of standards that carried no display title at all, and
+      // v0.1.5 gives every one of them a curated label. It remains declared
+      // 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.
+      nameFallback: "iri",
       type: "cs:CodeStandard",
       description:
-        "Look up detailed information for a standard by name, IRI, or glob.",
+        "Look up one or more standards by name, IRI, or glob. --detail standard adds the dos, --detail detailed adds the don'ts.",
       toolDescription:
-        "Get detailed information about one or more code standards including dos and donts with code examples. Address standards by name, prefixed name (cs:…), absolute IRI, or glob pattern (react/component/*).",
+        'Get one or more code standards in full, with dos and don\'ts as code examples. `detail` DEFAULTS to "summary", which returns neither: pass detail: "standard" for the dos and detail: "detailed" for dos AND don\'ts. Address a standard by the name standard_list publishes (`react/component/tsdoc`), by prefixed name (`cs:react.component.tsdoc`), by absolute IRI, or by a glob over any of those. Example: standard_lookup { name: ["react/component/tsdoc"], detail: "detailed" }.',
       fields: [
         {
           name: "category",
@@ -729,7 +926,7 @@ const codeStandardsStories: readonly PackDefinition[] = [
         description:
           "Return randomly selected complete standard instances as exemplars for shape discovery.",
         toolDescription:
-          "Return 1–5 randomly selected complete code standard instances as exemplars. Use BEFORE writing queries to see actual data shapes, property names, and value formats. Each call returns different instances.",
+          "Return 1–5 randomly selected complete code standard instances as exemplars. Use BEFORE writing queries to see actual data shapes, property names, and value formats. Each call returns different instances. Example: standard_sample { count: 2 }.",
       },
     },
   },
@@ -785,9 +982,19 @@ 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
+    // 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
+    // float: they are read for shape and identity, where the newest answer is
+    // the right one.
+    //
+    // Bump this deliberately. `sources update` resolves the tag, so a new
+    // upstream release reaches users only when this line moves — which is the
+    // point, and the cost.
     {
       name: "@canonical/code-standards",
-      source: "git+https://github.com/canonical/web-code-standards.git#main",
+      source: "git+https://github.com/canonical/web-code-standards.git#v0.1.5",
       stories: codeStandardsStories,
     },
     // The implementation graph: ds:ImplementationLibrary / ds:ImplementationObject

package/src/bin.ts

@@ -204,7 +204,14 @@ async function main(): Promise<void> {
       .flatMap((module) => [...module.verbs])
       .filter((verb) => !verb.hidden);
     process.stdout.write(
-      `${formatRootHelp(BIN_NAME, PROGRAM_DESCRIPTION, live, VERSION, ISSUES_URL)}\n`,
+      `${formatRootHelp(
+        BIN_NAME,
+        PROGRAM_DESCRIPTION,
+        live,
+        VERSION,
+        ISSUES_URL,
+        globalFlags,
+      )}\n`,
     );
     // The front door is a read, so it is where the un-set-up hint belongs: the
     // machine's state is the presence of the global config, and nothing is

package/src/capabilities/block.parity.test.ts

@@ -17,8 +17,11 @@
  *   deleted `capabilities/block/parity.test.ts`. Button and Modal resolve with
  *   the same content a direct SPARQL oracle returns (summary, guidance,
  *   anatomy, tier, modifier families with values, properties, subcomponents).
- *   The fixture DECLARES whenToUse/whenNotToUse (which the live graph superseded
- *   with ds:usage), so those sections are exercised here.
+ *   The fixture declares the usage narrative the way the live graph does — one
+ *   `ds:usage` literal — so what is exercised here is the path a real install
+ *   takes. It formerly declared the retired whenToUse/whenNotToUse pair, and
+ *   that divergence is exactly why this suite could assert a "### When to use"
+ *   heading no install had rendered in months.
  */
 
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
@@ -139,9 +142,9 @@ ds:Component a owl:Class .
       const rows = (await verb("list").run({}, emptyRt)) as PackRow[];
       expect(rows).toEqual([]);
       // The same semantics, on the empty-state seam: the calm message + its
-      // runnable hint now reach the user via stderr (`emptyNotice`), keeping
+      // runnable hint now reach the user via stderr (`notice`), keeping
       // plain stdout pure data.
-      const notice = verb("list").output.formatters.emptyNotice?.(rows);
+      const notice = verb("list").output.formatters.notice?.(rows);
       expect(notice).toContain("No blocks in the store.");
       expect(notice).toContain("pragma sources update");
     } finally {
@@ -159,10 +162,7 @@ describe("block lookup — Button content parity (GraphQL, detailed)", () => {
 
     // Guidance + anatomy sections — each cross-checked against the graph.
     expect(button.summary).toBe(await oracle(`${DS}button`, "ds:summary"));
-    expect(button.whenToUse).toBe(await oracle(`${DS}button`, "ds:whenToUse"));
-    expect(button.whenNotToUse).toBe(
-      await oracle(`${DS}button`, "ds:whenNotToUse"),
-    );
+    expect(button.usage).toBe(await oracle(`${DS}button`, "ds:usage"));
     expect(button.guidelines).toBe(
       await oracle(`${DS}button`, "ds:guidelines"),
     );
@@ -200,7 +200,13 @@ describe("block lookup — Button content parity (GraphQL, detailed)", () => {
     const out = (await verb("lookup").run({ name: ["Button"] }, rt)) as never;
     const llm = verb("lookup").output.formatters.llm(out);
     expect(llm).toContain("## Button");
-    expect(llm).toContain("### When to use");
+    expect(llm).toContain("### Usage");
+    // The usage literal's OWN headings are demoted below the section heading
+    // they now live under, so `### When to use` renders as a CHILD of Usage
+    // rather than a sibling that reads as an empty section.
+    expect(llm).toContain("#### When to use");
+    expect(llm).toContain("#### When not to use");
+    expect(llm).not.toContain("\n### When to use\n");
     expect(llm).toContain("### Anatomy (DSL)");
     expect(llm).toContain("### Modifier Families");
     expect(llm).toContain("primary");
@@ -213,7 +219,15 @@ describe("block lookup — Modal content parity (GraphQL, detailed)", () => {
     expect(modal.uri).toBe(`${DS}modal`);
     expect(modal.name).toBe("Modal");
     expect(modal.summary).toBe(await oracle(`${DS}modal`, "ds:summary"));
-    expect(modal.whenToUse).toBe(await oracle(`${DS}modal`, "ds:whenToUse"));
+    // Modal asserts an EMPTY `ds:usage` — the shape 138 of the 264 live blocks
+    // have. It resolves (parity with the oracle) and renders NOTHING: an empty
+    // literal must not print a bare "### Usage" heading with no body under it.
+    expect(modal.usage).toBe(await oracle(`${DS}modal`, "ds:usage"));
+    expect(modal.usage).toBe("");
+    const modalLlm = verb("lookup").output.formatters.llm(
+      (await verb("lookup").run({ name: ["Modal"] }, rt)) as never,
+    );
+    expect(modalLlm).not.toContain("### Usage");
     const families = modal.modifierFamilies as {
       name: string;
       values?: string[];
@@ -237,7 +251,7 @@ describe("block lookup — disclosure trims to the base view at summary", () =>
     const button = out.results.at(0) as Record<string, unknown>;
     expect(button.name).toBe("Button");
     expect(button.summary).toBeDefined();
-    expect(button.whenToUse).toBeUndefined();
+    expect(button.usage).toBeUndefined();
     expect(button.anatomyDsl).toBeUndefined();
     expect(button.modifierFamilies).toBeUndefined();
     expect(button.figmaLink).toBeUndefined();