feat(cli): answer the component contract per component, not per catalog

The agent-facing guidance named dist/components.json as the source of truth,
which is an instruction to read 13,634 tokens — 36% of it JSON punctuation —
to learn about a handful of components. The bin already answered the same
questions for 50 tokens each; the docs pointed past it.

`components` now takes several names in one call, and `--used <file>` prints
the contract for exactly the components a file contains. It scans for tags
rather than compiling, so it still answers for an artifact mid-edit. Across the
shipped examples that costs 100-1,576 tokens against 13,634.

The manifest keeps its envelope and its exact-version guarantee as bulk data
for tools; agent-facing docs now name the CLI only.

Author: vltansky

README.md

@@ -94,7 +94,7 @@ passes, and a diagram that cannot load keeps its fence text. Disable it with
 
 ## Components
 
-The runtime ships 87 components. Its `htmdx@2` exact-version `dist/components.json` manifest documents every component's purpose, canonical example, body mode, props, and source.
+The runtime ships 89 components. `npx @wix/htmdx components <name...>` prints a component's purpose, canonical example, body mode, props, and source, and `--used <file>` prints that contract for exactly the components a file already contains. The same data ships in bulk as the `htmdx@2` exact-version `dist/components.json` manifest, for tools that consume the whole catalog.
 
 **Report Built-ins** cover summaries, callouts, metrics, charts, tables, timelines, findings, evidence, and risks. Their `markdown` bodies reject nested tags, and each definition's purpose and example state any stricter list or table grammar. Components with `htmdx` bodies accept Markdown, HTML, and nested registered tags; components with `none` bodies accept only empty or self-closing tags.
 
@@ -288,7 +288,7 @@ Exit codes are `0` clean, `1` problems found, `2` could not run. `--format json`
 
 `lint` accepts an HTML artifact — the source comes from its `<script type="text/htmdx">` block and positions are reported against the artifact — or a bare source file. On top of everything `validate()` reports, it adds two findings that only exist at the artifact level: `unpinned-runtime` (the runtime `<script>` has no pinned version, so a future release can change the artifact) and `runtime-version-mismatch` (the artifact pins a version other than the one linting it). This repo lints its own examples this way in CI.
 
-`components` reads the manifest built next to the bin, so the catalog it prints is the one that version renders — the thing to ask before writing a document rather than guessing at prop names. See the [package README](./packages/htmdx/README.md#command-line) for the full behavior, including how `invalid-html-nesting` dedupes across files in one run.
+`components` reads the manifest built next to the bin, so the catalog it prints is the one that version renders — the thing to ask before writing a document rather than guessing at prop names. Name several components in one call, or pass `--used <file>` to get the contract for exactly what an artifact already contains. See the [package README](./packages/htmdx/README.md#command-line) for the full behavior, including how `invalid-html-nesting` dedupes across files in one run.
 
 ## Agent skill
 
@@ -301,7 +301,7 @@ The authoring guidance ships with the runtime and is printed by `htmdx skill`, s
 - npm: `@wix/htmdx` · CDN entry: `dist/browser.js` (under 160KB gzip, [budgeted in CI](./packages/htmdx/build/bundle-budget.json)) · module entries: `.`, `./react`, `./testing`, `./components`, `./components/builtins`, `./components/shadcn`
 - custom element: `<htmdx-code>` · browser API: `window.Htmdx`
 - linting: [`validate()`](#validation-and-linting) · CLI: [`lint`, `compile`, `components`](#command-line) — `npx @wix/htmdx lint <files...>`
-- component contract: `dist/components.json`
+- component contract: `npx @wix/htmdx components <name...>` · bulk data: `dist/components.json`
 - agent guidance: `npx @wix/htmdx skill` (topics in [`packages/htmdx/skill/`](./packages/htmdx/skill/)), installable skill in [`skills/htmdx/`](./skills/htmdx/SKILL.md)
 - architecture decisions: [`adr/`](./adr/)
 

adr/answer-the-component-contract-from-the-cli.md

@@ -0,0 +1,88 @@
+# Answer the component contract from the CLI, not the manifest
+
+- Status: accepted
+- Date: 2026-07-28
+- Extends [component-definitions-as-agent-contracts](component-definitions-as-agent-contracts.md),
+  which made `dist/components.json` the contract, and
+  [ship-agent-guidance-from-the-runtime](ship-agent-guidance-from-the-runtime.md),
+  which put the guidance behind the bin
+
+## Context
+
+`dist/components.json` is the component contract, and the agent-facing docs said
+so literally. `skill/authoring.md` and `skill/components.md` both named the
+jsDelivr URL as "the source of truth when the network is reachable", which is an
+instruction to read the whole document.
+
+Measured with `gpt-tokenizer` (`o200k_base`), that document is 13,634 tokens.
+The breakdown is what makes it a problem rather than a cost:
+
+| Part | Tokens | Share |
+| --- | ---: | --- |
+| JSON punctuation and indentation | 4,873 | 36% |
+| `example` | 4,174 | 31% |
+| `props` | 2,326 | 17% |
+| `purpose` | 1,645 | 12% |
+| `name`, `body`, `source` | 616 | 4% |
+
+Better than a third of it is structural syntax — quotes, braces, indentation,
+key names repeated 89 times. A machine parses that for free. A model pays for
+every token of it.
+
+The same facts already came out of the bin far cheaper. `htmdx components`
+lists the catalog in 1,600 tokens; `htmdx components Callout` answers in 50.
+Nothing needed building for the common case to cost 3% of what the docs
+recommended — the commands existed and the docs pointed past them.
+
+Two gaps kept the CLI from being a complete substitute. It took one name per
+invocation, so asking about five components meant five calls. And it had no way
+to answer "what does *this artifact* use", which is the question an edit starts
+from: an agent editing a file needs the grammar for the components in it, not
+for all 89.
+
+## Decision
+
+The CLI is the documented way to read the component contract. `components.json`
+keeps its `htmdx@2` envelope, its exact-version guarantee, and its place in the
+published package — it is bulk machine-readable data for tools that consume the
+whole catalog, and it is no longer what agent-facing documentation points at.
+
+`htmdx components` grows the two modes that make it sufficient:
+
+- `components <name...>` takes several names in one call. One unknown name
+  fails the call rather than printing a partial answer that reads like a
+  complete one.
+- `components --used <file>` prints the contract for exactly the components a
+  file contains, taking the source from an artifact's
+  `<script type="text/htmdx">` block or reading a bare source file directly.
+
+`--used` scans for capitalized tags instead of compiling. Compiling would be
+more precise, but the artifact whose contract someone needs is disproportionately
+the one that does not compile yet, and an answer that requires a working document
+is unavailable exactly when it is wanted. The same tolerance means a tag inside a
+code fence counts: over-reporting costs a few lines, and missing a component
+costs the answer.
+
+Measured across the shipped examples, `--used` costs 100 tokens (2 components)
+to 1,576 (16). `component-tour.html` is the outlier at 7,134, because it is a
+catalog demo that names 73 components — the case where reading everything is the
+correct answer, and where it still beats the manifest by half.
+
+`--format json` keeps emitting the bare entry for a single name. Several names
+and `--used` emit an array. Preserving the single-name shape keeps existing
+callers working, at the cost of a response shape that varies with the request.
+
+## Consequences
+
+- The realistic contract read for an edit drops from 13,634 tokens to 100-1,576.
+- Two documented sources of truth for one catalog is how they drift, so
+  agent-facing docs name the CLI only. `components.json` stays documented where
+  it is consumed as data: the package README and the integration topic.
+- `--used` reports what a file mentions, not what it renders. A component named
+  only inside a code fence appears in the output.
+- The manifest's own size is unaddressed. Family examples are the next lever:
+  60 of 89 components sit in compound families whose canonical examples largely
+  repeat each other (Avatar's three members ship one identical example,
+  Breadcrumb's seven ship three), and 3,178 of the 4,174 example tokens belong
+  to them. Deduplicating in a projection rather than in the manifest would keep
+  the per-definition example validation this repo's build depends on.

packages/htmdx/README.md

@@ -48,6 +48,11 @@ CDN caveats:
 
 ## Exact-version component manifest
 
+`htmdx components` is the way to read this contract — it answers for the
+version that runs it, and it answers for the components asked about rather than
+all 89. The manifest below is the same contract as bulk machine-readable data,
+for tools that consume the whole catalog.
+
 Every release includes its machine-readable component contract at:
 
 <!-- x-release-please-start-version -->
@@ -535,8 +540,19 @@ browser bundle injects.
 
 Prints the [component manifest](#exact-version-component-manifest) built next to
 the bin, so the catalog is the one that version renders. With no argument it
-lists every component grouped by source; with a name it prints that component's
-purpose, body mode, props, and canonical example.
+lists every component grouped by source; with one or more names it prints each
+component's purpose, body mode, props, and canonical example.
+
+`--used <file>` prints that contract for exactly the components a file already
+contains, which is the shape an edit needs: the catalog for this artifact, not
+the catalog for everything. It scans for capitalized tags instead of compiling,
+so it still answers for source that is mid-edit and does not compile — and a tag
+inside a code fence counts, because over-reporting costs a few lines while
+missing a component costs the answer.
+
+```bash
+$ npx @wix/htmdx components --used report.html
+```
 
 ```bash
 $ npx @wix/htmdx components Foldout
@@ -560,9 +576,10 @@ example:
 
 A name that does not match exits `1` and suggests the closest entries, by
 substring and by edit distance, so a typo or a half-remembered name still lands:
-`unknown component "Calout"; did you mean Callout?`. `--format json` prints the
-manifest entry, or the whole manifest when no name is given — the shape to read
-before writing a document rather than guessing at prop names.
+`unknown component "Calout"; did you mean Callout?`. One unknown name among
+several fails the whole call, so a partial answer never reads as a complete one.
+`--format json` prints the manifest entry for a single name, an array for
+several or for `--used`, and the whole manifest when no name is given.
 
 ## Agent guidance
 

packages/htmdx/skill/authoring.md

@@ -139,17 +139,25 @@ in order is not an alternate view, and tabbing it hides content for no gain.
 starts with `Must-have`, `Differentiator`, `Not now`, or `Won't do`.
 
 Body grammar is per component and is enforced at compile time. The `components`
-topic has the grammar for every built-in family with a working example. The
-exact-version manifest is the source of truth when the network is reachable:
+topic has the grammar for every built-in family with a working example. Ask the
+CLI for the contract of the components in play rather than reading the whole
+catalog:
 
 <!-- x-release-please-start-version -->
 
-```text
-https://cdn.jsdelivr.net/npm/@wix/htmdx@4.11.0/dist/components.json
+```bash
+npx @wix/htmdx@4.11.0 components Callout DataTable   # the ones you plan to use
+npx @wix/htmdx@4.11.0 components --used report.html  # the ones a file already uses
+npx @wix/htmdx@4.11.0 components                     # every name with its purpose
 ```
 
 <!-- x-release-please-end-version -->
 
+Each command answers for the version that runs it. `dist/components.json` holds
+the same contract as machine-readable data, but it is the whole catalog in one
+document — reach for it when a tool consumes it, not to answer a question about
+a handful of components.
+
 ## Author the source
 
 - **Attributes are data.** Every component accepts `class`, `id`, `aria-*`, and

packages/htmdx/skill/components.md

@@ -1,21 +1,25 @@
 # Component grammar
 
 The runtime ships two catalogs: 24 report built-ins and a 65-component
-shadcn/ui pack. Its exact-version manifest documents every component's purpose,
-canonical example, body mode, and props:
+shadcn/ui pack. Ask the CLI for a component's purpose, canonical example, body
+mode, and props:
 
 <!-- x-release-please-start-version -->
 
-```text
-https://cdn.jsdelivr.net/npm/@wix/htmdx@4.11.0/dist/components.json
+```bash
+npx @wix/htmdx@4.11.0 components Callout DataTable   # the ones you plan to use
+npx @wix/htmdx@4.11.0 components --used report.html  # the ones a file already uses
+npx @wix/htmdx@4.11.0 components                     # every name with its purpose
 ```
 
 <!-- x-release-please-end-version -->
 
-Read the manifest when the network is reachable. This file covers the grammar
-the manifest's `body` field alone does not spell out: the built-ins with a
-`markdown` body still parse that Markdown against a fixed row or table shape,
-and an invalid body fails the artifact.
+`--used` scans for tags rather than compiling, so it still answers for an
+artifact that is mid-edit and does not compile yet.
+
+This file covers the grammar a component's `body` field alone does not spell
+out: the built-ins with a `markdown` body still parse that Markdown against a
+fixed row or table shape, and an invalid body fails the artifact.
 
 ## Body modes
 

packages/htmdx/src/cli/components.ts

@@ -37,6 +37,19 @@ export function findComponent(manifest: Manifest, name: string): ManifestCompone
   return manifest.components.find((entry) => entry.name.toLowerCase() === wanted);
 }
 
+const COMPONENT_TAG = /<([A-Z][A-Za-z0-9]*)[\s/>]/g;
+
+// Scans for capitalized tags instead of compiling the source: the artifact
+// whose contract someone needs is often the one that does not compile yet.
+// A tag inside a code fence counts too — over-reporting costs a few lines,
+// missing a component costs the answer.
+export function componentsUsedIn(manifest: Manifest, source: string): ManifestComponent[] {
+  const used = new Set(
+    Array.from(source.matchAll(COMPONENT_TAG), (match) => match[1].toLowerCase()),
+  );
+  return manifest.components.filter((entry) => used.has(entry.name.toLowerCase()));
+}
+
 // A miss is usually a typo or a half-remembered name, so point at the closest
 // things rather than making the user re-read the whole list. Substring catches
 // the half-remembered case ("chart"), edit distance catches the typo ("Calout").
@@ -91,6 +104,10 @@ export function formatList(components: ManifestComponent[], runtime: string): st
   return `${lines.join('\n')}\n`;
 }
 
+export function formatComponents(entries: ManifestComponent[]): string {
+  return entries.map(formatComponent).join('\n');
+}
+
 export function formatComponent(entry: ManifestComponent): string {
   const lines = [entry.name, '', entry.purpose, '', `body: ${entry.body}  source: ${entry.source}`];
 

packages/htmdx/src/cli/index.ts

@@ -8,13 +8,16 @@ import { readFile, writeFile } from 'node:fs/promises';
 import { relative } from 'node:path';
 import { compileFile } from './compile';
 import {
+  componentsUsedIn,
   findComponent,
-  formatComponent,
+  formatComponents,
   formatList,
   loadManifest,
   suggestNames,
+  type ManifestComponent,
 } from './components';
 import { lintFile, summarize, type LintDiagnostic, type LintReport } from './lint';
+import { extractEmbeddedSource, isArtifact } from './runtime';
 import {
   DEFAULT_SKILL_TOPIC,
   formatTopicList,
@@ -31,14 +34,15 @@ Commands:
   lint <files...>      Report problems in artifacts and source files
   validate <files...>  Alias for lint
   compile <file>       Print the static HTML snapshot
-  components [name]    List the component catalog, or describe one component
+  components [name...] List the component catalog, or describe named components
   skill [topic]        Print the authoring guidance for this runtime
 
 Options:
   --format <pretty|json>  Output format for lint and components (default: pretty)
   --strict                Treat lint warnings as failures
   -o, --out <file>        Write compile output to a file instead of stdout
   --layout <name>         Document layout for compile
+  --used <file>           Describe only the components that <file> already uses
   --list, --full, --json  Topic selection and format for skill
   -h, --help              Show this message
 
@@ -50,6 +54,7 @@ type Args = {
   strict: boolean;
   out?: string;
   layout?: string;
+  used?: string;
 };
 
 async function main(argv: string[]): Promise<number> {
@@ -148,8 +153,20 @@ async function runComponents(args: Args): Promise<number> {
     return 2;
   }
 
-  const [name] = args.files;
-  if (!name) {
+  if (args.used !== undefined) {
+    const content = await read(args.used);
+    if (content === undefined) {
+      return 2;
+    }
+    const source = isArtifact(args.used, content) ? extractEmbeddedSource(content) : content;
+    if (source === undefined) {
+      process.stderr.write(`${args.used}: no <script type="text/htmdx"> block found\n`);
+      return 2;
+    }
+    return writeComponents(componentsUsedIn(manifest, source), args.format);
+  }
+
+  if (args.files.length === 0) {
     process.stdout.write(
       args.format === 'json'
         ? `${JSON.stringify(manifest, null, 2)}\n`
@@ -158,18 +175,37 @@ async function runComponents(args: Args): Promise<number> {
     return 0;
   }
 
-  const entry = findComponent(manifest, name);
-  if (!entry) {
-    const near = suggestNames(manifest, name);
-    process.stderr.write(
-      `unknown component "${name}"${near.length ? `; did you mean ${near.join(', ')}?` : ''}\n`,
-    );
-    return 1;
+  const entries: ManifestComponent[] = [];
+  for (const name of args.files) {
+    const entry = findComponent(manifest, name);
+    if (!entry) {
+      const near = suggestNames(manifest, name);
+      process.stderr.write(
+        `unknown component "${name}"${near.length ? `; did you mean ${near.join(', ')}?` : ''}\n`,
+      );
+      return 1;
+    }
+    entries.push(entry);
   }
 
-  process.stdout.write(
-    args.format === 'json' ? `${JSON.stringify(entry, null, 2)}\n` : formatComponent(entry),
-  );
+  // One name has always emitted the bare entry; keep scripts that read it working.
+  const payload = entries.length === 1 ? entries[0] : entries;
+  return writeComponents(entries, args.format, payload);
+}
+
+function writeComponents(
+  entries: ManifestComponent[],
+  format: Args['format'],
+  payload: unknown = entries,
+): number {
+  if (format === 'json') {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return 0;
+  }
+
+  // Silence would read as "this file uses nothing", which is also what a bad
+  // --used path looks like from the caller's side.
+  process.stdout.write(entries.length ? formatComponents(entries) : 'no components\n');
   return 0;
 }
 
@@ -242,6 +278,11 @@ function parseArgs(argv: string[]): Args {
       args.layout = argv[index];
       continue;
     }
+    if (argument === '--used') {
+      index += 1;
+      args.used = argv[index];
+      continue;
+    }
     args.files.push(argument);
   }