@instruments/materialgraph 0.5.0 → 0.6.1

package/client.js

@@ -28,18 +28,69 @@ function operation(operationId) {
     }
     return match;
 }
+/**
+ * The MaterialGraph client — every lens on the graph, on one object.
+ *
+ * PICK YOUR LENS BY THE QUESTION, not by the noun. Most wrong answers from this
+ * API come from routing a question to a lens that cannot see it:
+ *
+ * | The question | The lens |
+ * | --- | --- |
+ * | "find me something like this / matching these words" | {@link MaterialGraphClient.search} |
+ * | "what's IN this photo?" | {@link MaterialGraphClient.match} / {@link MaterialGraphClient.matchStream} |
+ * | "which materials, from anyone, meet this hard spec?" | {@link MaterialGraphClient.bySpec} |
+ * | "what's near this colour / this palette / this gradient?" | {@link MaterialGraphClient.byColour}, `colours.palette()`, `colours.gradient()` |
+ * | "what goes with THIS material?" | {@link MaterialGraphClient.pairings}, {@link MaterialGraphClient.siblings}, {@link MaterialGraphClient.coordinate} |
+ * | "how much is this specified?" | {@link MaterialGraphClient.demand}, {@link MaterialGraphClient.demandBatch} |
+ * | "is this allowed in an A-2 corridor?" | `codes.*` |
+ * | "what can I even ask for?" | {@link MaterialGraphClient.specificationFacets}, {@link MaterialGraphClient.attributeValues}, {@link MaterialGraphClient.taxonomy}, {@link MaterialGraphClient.colourFacets}, {@link MaterialGraphClient.glossary} |
+ * | "do the whole job for me, async" | {@link MaterialGraphClient.createRun} + `mg:compose` |
+ *
+ * Two structural rules that fall out of that table:
+ * - **Colour is a separate lens.** {@link MaterialGraphClient.search} matches
+ *   WORDS. A colour word in `text` finds materials whose text mentions it, not
+ *   materials that look it. Route visual intent to the colour lenses.
+ * - **Relationships hang off a material, not off a query.** You cannot ask "what
+ *   pairs with beige oak"; you resolve a material first, then ask what pairs
+ *   with THAT `variantId`.
+ *
+ * And three reading rules that apply to every lens: ids are opaque (see
+ * `./identifiers.ts`), absent is not false, and a page is not a corpus.
+ */
 export class MaterialGraphClient {
     baseUrl;
+    /**
+     * THE QUESTION: "show me everything, ordered lightest / most vivid / most
+     * muted." Pure colour scalars — no query, no relevance. `browse({ sort })` is
+     * one page; `browse.pages({ sort })` walks them all, and only the walk can
+     * support a corpus claim.
+     *
+     * Instead use {@link MaterialGraphClient.byColour} for materials NEAR a colour,
+     * {@link MaterialGraphClient.search} when there is anything to rank against,
+     * and `colours.profiles()` for a category's palette rather than its members.
+     */
     browse;
     /**
-     * The advisory building-code surface: `codes.context()` to discover the
-     * vocabulary, `codes.requirements()` to state a space, `codes.advisory()` to
-     * badge candidates against it.
+     * THE QUESTION: "is this material allowed HERE?" — a jurisdiction + occupancy +
+     * finish location, not a property of the material alone. `codes.context()`
+     * discovers the vocabulary, `codes.requirements()` states a space,
+     * `codes.advisory()` badges candidates.
+     *
+     * Instead use {@link MaterialGraphClient.bySpec} to find materials by a
+     * classification you already know you need; codes is what tells you WHICH one
+     * the space demands. ADVISORY ONLY: model code as adopted, never a
+     * determination for an authority having jurisdiction.
      */
     codes;
     /**
-     * The colour AGGREGATE surface: `colours.profiles()` for a category palette,
-     * `colours.stats()` for corpus colour coverage.
+     * THE QUESTION: "what colours exist here?" (`profiles`, `stats`) and "what
+     * matches this whole SET of colours?" (`palette`, `gradient`).
+     *
+     * Instead use {@link MaterialGraphClient.byColour} for ONE colour,
+     * {@link MaterialGraphClient.browse} to walk by a colour scalar, and
+     * {@link MaterialGraphClient.colourFacets} for the colour VOCABULARY rather
+     * than values. Colour throughout is derived from product imagery — visual
+     * likeness, never a declared colour specification.
      */
     colours;
     #transport;
@@ -73,6 +124,16 @@ export class MaterialGraphClient {
         return this.#transport.requestJson(operation(operationId), { body, signal });
     }
     /**
+     * THE QUESTION: "find me materials like this" — a RANKED answer over words, a
+     * seed image, colours and a mood, optionally gated by hard specs.
+     *
+     * Instead use {@link MaterialGraphClient.bySpec} when the spec IS the question
+     * (ranking would be noise), {@link MaterialGraphClient.byColour} /
+     * `colours.palette()` for visual colour intent (`text` matches WORDS — "sage
+     * green" finds materials that SAY sage, not ones that look it),
+     * {@link MaterialGraphClient.match} for a photo, {@link MaterialGraphClient.pairings}
+     * for what goes WITH something, {@link MaterialGraphClient.suggest} for typeahead.
+     *
      * The full search primitive (POST `/api/v1/search`). Layer a hard
      * specification gate onto a ranked (colour / visual / lexical / seed) search
      * via `input.filters` — each entry is a typed {@link SearchFilter} criterion:
@@ -86,9 +147,28 @@ export class MaterialGraphClient {
     search(input, signal) {
         return this.#post("search_materials_post", input, signal);
     }
+    /**
+     * The same question as {@link MaterialGraphClient.search}; the difference is
+     * transport — a cacheable, link-shareable GET for queries that must survive in
+     * a URL. `filters`, `preferences`, `verdicts`, image bytes and `weights` have
+     * no query-string form, so anything using those must go through `search`.
+     */
     searchGet(params, signal) {
         return this.#get("search_materials_get", { ...params }, signal);
     }
+    /**
+     * THE QUESTION: "what materials are in this PHOTO?" — Material Match classifies
+     * the image, decomposes it into surfaces, and answers each one.
+     *
+     * Instead use {@link MaterialGraphClient.matchStream} whenever a human is
+     * watching, {@link MaterialGraphClient.search} with `image` for ONE ranked list
+     * rather than a per-surface decomposition, and
+     * {@link MaterialGraphClient.extractPalette} for the image's colours only.
+     *
+     * Exactly one of `imageBase64`, `imageUrl` or `vector`. Read `qualityFloor` and
+     * `droppedBelowFloor` before reporting an empty result: "nothing was good
+     * enough" and "nothing was found" are different answers.
+     */
     match(input, signal) {
         return this.#post("match_material", input, signal);
     }
@@ -118,6 +198,17 @@ export class MaterialGraphClient {
     matchStream(input, signal) {
         return matchStreamCall(this.#transport, input, signal);
     }
+    /**
+     * THE QUESTION: "what materials are near THIS colour?" — one colour (or a small
+     * palette), ranked by OKLab closeness to colour extracted from product imagery.
+     *
+     * Instead use `colours.palette()` for N colours at stated proportions (a
+     * different ranking, not a wrapper), `colours.gradient()` for a transition,
+     * {@link MaterialGraphClient.resolveColour} first if you hold a NAME,
+     * {@link MaterialGraphClient.browse} to walk by lightness/vividness, and
+     * {@link MaterialGraphClient.search} when colour is one signal among many.
+     * Report matches as visual likeness, never a stated colour specification.
+     */
     byColour(params, signal) {
         return this.#get("search_by_colour", {
             hex: params.hex,
@@ -130,31 +221,78 @@ export class MaterialGraphClient {
         }, signal);
     }
     // ── Materials ──────────────────────────────────────────────────────────────
-    /** Get a single material's detail record (GET `/api/v1/materials/{variantId}`). */
+    /**
+     * THE QUESTION: "tell me everything about THIS material" (GET
+     * `/api/v1/materials/{variantId}`).
+     *
+     * The hinge of the API: every relationship lens
+     * ({@link MaterialGraphClient.siblings}, {@link MaterialGraphClient.pairings},
+     * {@link MaterialGraphClient.demand}, `codes.advisory()`) hangs off a
+     * `variantId`. Instead use {@link MaterialGraphClient.materials} for many ids,
+     * {@link MaterialGraphClient.materialBlocks} to tell "no value" from "not
+     * checked", {@link MaterialGraphClient.search} when you have no id yet.
+     *
+     * @param variantId Opaque — pass back exactly what you were given.
+     */
     material(variantId, options, signal) {
         return this.#get("get_material", options?.includeSiblings ? { include: "siblings" } : undefined, signal, { variantId });
     }
-    /** The other variants of the same product (GET `/api/v1/materials/{variantId}/siblings`). */
+    /**
+     * THE QUESTION: "what other colourways and finishes does this product come in?"
+     * — the SAME product, different variants.
+     *
+     * Instead use {@link MaterialGraphClient.pairings} for a DIFFERENT product that
+     * goes with this one, and `search({ similarTo })` for one that LOOKS like it.
+     */
     siblings(variantId, signal) {
         return this.#get("get_material_siblings", undefined, signal, { variantId });
     }
-    /** Canonical block completeness for a material (GET `/api/v1/materials/{variantId}/blocks`). */
+    /**
+     * THE QUESTION: "what do we actually KNOW about this material, and what have we
+     * simply not checked?" The only read that distinguishes a determined absence
+     * from an unasked question — every field carries a `status`, so this is the one
+     * surface entitled to back a negative ("no fire rating").
+     * {@link MaterialGraphClient.material} cannot: there an absence is merely unknown.
+     */
     materialBlocks(variantId, signal) {
         return this.#get("list_material_blocks", undefined, signal, {
             variantId,
         });
     }
-    /** Safe images and downloads for a material (GET `/api/v1/materials/{variantId}/assets`). */
+    /**
+     * THE QUESTION: "what images and documents may I SHOW for this material?" — the
+     * redistribution-safe set (GET `/api/v1/materials/{variantId}/assets`), not
+     * every file on record.
+     */
     materialAssets(variantId, signal) {
         return this.#get("list_material_assets", undefined, signal, {
             variantId,
         });
     }
-    /** Read one static governed schema resource. */
+    /**
+     * THE QUESTION: "what does the schema DEFINE?" — the governed static registry.
+     *
+     * Definitions, not data: use {@link MaterialGraphClient.specificationFacets} for
+     * what the corpus actually holds and {@link MaterialGraphClient.glossary} to
+     * explain one term.
+     */
     schema(resource, signal) {
         return this.#get(SCHEMA_RESOURCE_OPERATION_IDS[resource], undefined, signal);
     }
-    /** The "what pairs with this material" rail (GET `/api/v1/materials/{variantId}/pairings`). */
+    /**
+     * THE QUESTION: "what goes WITH this material?" — the companionship rail, hung
+     * off one resolved material (GET `/api/v1/materials/{variantId}/pairings`).
+     *
+     * Instead use {@link MaterialGraphClient.coordinate} for a whole palette of
+     * picks, {@link MaterialGraphClient.siblings} for the same product in another
+     * colour, and `search({ similarTo })` for a LIKE-THIS substitute — similar and
+     * complementary are opposite questions.
+     *
+     * READ `item.source` BEFORE PHRASING: the rail mixes three tiers of evidence —
+     * `cospec` (real orders), `considered` (board activity), `colour` (palette
+     * look-alike). Only `cospec` supports "specified together". `cospecCount` tells
+     * you how much of the rail is real order evidence.
+     */
     pairings(variantId, options, signal) {
         return this.#get("get_material_pairings", { categories: options?.categories, limit: options?.limit }, signal, { variantId });
     }
@@ -175,11 +313,20 @@ export class MaterialGraphClient {
         }, signal);
     }
     // ── Colour helpers ───────────────────────────────────────────────────────────
-    /** The three canonical colour vocabularies with live counts (GET `/api/v1/colours/facets`). */
+    /**
+     * THE QUESTION: "what colour WORDS may I use?" — family, mood and undertone
+     * with live counts. Vocabulary, not values: instead use `colours.profiles()`
+     * for a category's palette, {@link MaterialGraphClient.byColour} to search by a
+     * colour, {@link MaterialGraphClient.resolveColour} to turn a NAME into a hex.
+     */
     colourFacets(signal) {
         return this.#get("get_colour_facets", undefined, signal);
     }
-    /** Resolve a colour name/phrase to a hex (GET `/api/v1/search/colours/resolve`). */
+    /**
+     * THE QUESTION: "what hex is 'Hague Blue'?" — the step before
+     * {@link MaterialGraphClient.byColour} when you hold a name rather than a hex.
+     * A `null` match means unrecognised, not "no such colour".
+     */
     resolveColour(name, signal) {
         return this.#get("resolve_colour_name", { name }, signal);
     }
@@ -188,6 +335,11 @@ export class MaterialGraphClient {
         return this.#get("suggest_colour_names", { q, limit: options?.limit }, signal);
     }
     /**
+     * THE QUESTION: "what is the user starting to type?" It ranks NAMES, not
+     * materials — instead use {@link MaterialGraphClient.search} once they commit,
+     * {@link MaterialGraphClient.suggestColour} for colour names, and
+     * {@link MaterialGraphClient.searchVocabulary} for attribute/value tokens.
+     *
      * Entity typeahead across products, brands and categories
      * (GET `/api/v1/search/suggest`). Built for per-keystroke use: one indexed
      * lookup, no embedding call and no model. Every suggestion carries the
@@ -202,19 +354,53 @@ export class MaterialGraphClient {
         return this.#get("search_suggest", suggestQuery(q, options), signal);
     }
     // ── Catalog ──────────────────────────────────────────────────────────────────
-    /** Resolve a free-text spec phrase to canonical attribute ids (GET `/api/v1/catalog/attributes/resolve`). */
+    /**
+     * THE QUESTION: "the user said 'fire rating' — which canonical attribute is
+     * that?" Free text in, canonical `attributeId`s out; pair with
+     * {@link MaterialGraphClient.resolveAttributeValue} for the VALUE, then spend
+     * the pair on {@link MaterialGraphClient.bySpec} or `search({ filters })`.
+     * Instead use {@link MaterialGraphClient.specificationFacets} to browse rather
+     * than resolve.
+     */
     resolveAttribute(q, options, signal) {
         return this.#get("catalog_resolve_attribute", { q, limit: options?.limit, facetableOnly: options?.facetableOnly }, signal);
     }
-    /** Resolve a value phrase against one canonical attribute's dictionary. */
+    /**
+     * THE QUESTION: "the user said 'class A' — what canonical term is that, under
+     * THIS attribute?" The value half of the pair
+     * {@link MaterialGraphClient.resolveAttribute} starts. Read
+     * `resolution.recommendedAction`, not just `best`: `ambiguous` means ask.
+     *
+     * @param attributeId Canonical vocabulary, not an opaque id — discover it, do
+     * not invent it.
+     */
     resolveAttributeValue(attributeId, query, options, signal) {
         return this.#get("catalog_resolve_value", { q: query, limit: options?.limit }, signal, { attributeId });
     }
-    /** Search canonical attributes and value-dictionary terms together. */
+    /**
+     * THE QUESTION: "is 'FloorScore' an attribute or a value, and what is it called
+     * here?" The catch-all when you do not know which half of an `attribute:value`
+     * pair a phrase belongs to. Instead use
+     * {@link MaterialGraphClient.resolveAttribute} /
+     * {@link MaterialGraphClient.resolveAttributeValue} once you do, and
+     * {@link MaterialGraphClient.glossary} to EXPLAIN a term rather than find it.
+     */
     searchVocabulary(query, options, signal) {
         return this.#get("catalog_vocabulary_search", { q: query, limit: options?.limit, kind: options?.kind }, signal);
     }
     /**
+     * THE QUESTION: "which materials, from ANYONE, are ASTM E84 Class A AND
+     * GREENGUARD-certified?" — hard specifications, no ranking, every brand at once
+     * whatever each called the value in source.
+     *
+     * Instead use `search({ filters })` when the spec merely GATES a ranked
+     * question, `codes.advisory()` when the real question is what a space demands,
+     * and {@link MaterialGraphClient.specificationFacets} first if you do not know
+     * the canonical tokens — guessing one returns an honest, empty answer.
+     *
+     * A PAGE, NOT A CORPUS, unusually so: `totalMatches` is the size of the
+     * returned sample under `limit`, not a corpus count. See {@link BySpecResponse}.
+     *
      * Find materials by canonical specification across every brand — the
      * value-anchored, spec-only primitive (GET `/api/v1/search/specifications`).
      * Each `spec` is an `attribute:value` criterion; a variant must satisfy ALL of
@@ -229,16 +415,31 @@ export class MaterialGraphClient {
         return this.#get("catalog_by_spec", { spec: Array.isArray(spec) ? spec : [spec], limit: options?.limit }, signal);
     }
     // ── Taxonomy + meta ──────────────────────────────────────────────────────────
-    /** The product-category tree, flattened (GET `/api/v1/taxonomy/categories`). */
+    /**
+     * THE QUESTION: "what kinds of thing exist, and what are their canonical keys?"
+     * The source of every `categoryKey` / product-type id the other lenses accept
+     * (`search({ category })`, `colours.profiles()`,
+     * {@link MaterialGraphClient.applicableSpecs}). Discover, never hand-write.
+     */
     taxonomy(signal) {
         return this.#get("get_category_taxonomy", undefined, signal);
     }
-    /** Echo the authenticated principal and scopes (GET `/api/v1/whoami`). */
+    /**
+     * THE QUESTION: "what is this key allowed to do?" Check `scopes` before
+     * offering a capability: the write surfaces need `mg:ingest` / `mg:compose`,
+     * and `mg:admin` unlocks extra evidence fields.
+     */
     whoami(signal) {
         return this.#get("whoami", undefined, signal);
     }
     // ── Pairings / demand ────────────────────────────────────────────────────────
     /**
+     * THE QUESTION: "here is my whole scheme so far — what completes it?" The
+     * multi-seed form of {@link MaterialGraphClient.pairings}: lift is summed across
+     * seeds, so a companion suiting one pick ranks below one suiting several.
+     * Instead use `pairings` for a single material and `colours.palette()` when the
+     * scheme is COLOURS rather than materials. Check `unresolved` before presenting.
+     *
      * Coordinate a palette of already-chosen materials (POST
      * `/api/v1/pairings/coordinate`). Returns demand-lift-ranked companions with
      * colour swatches and an annotate-only `colourFit` (never reorders in v1).
@@ -247,13 +448,25 @@ export class MaterialGraphClient {
         return this.#post("coordinate_materials", input, signal);
     }
     /**
-     * How much a material is specified, plus what's specified alongside it (GET
-     * `/api/v1/demand`). Provide EXACTLY ONE of `variantId` or `material`.
+     * THE QUESTION: "how much is this material actually specified, and what gets
+     * specified alongside it?" — real order behaviour, trailing 36 months.
+     *
+     * Instead use {@link MaterialGraphClient.demandBatch} for many ids (this one
+     * also resolves free text, which the batch deliberately does not) and
+     * {@link MaterialGraphClient.pairings} for a presentable rail. A null `demand`
+     * means UNREAD, never zero. Provide EXACTLY ONE of `variantId` or `material`.
      */
     demand(params, signal) {
         return this.#get("get_material_demand", { variantId: params.variantId, material: params.material }, signal);
     }
     /**
+     * THE QUESTION: "for each of these picks I already hold, how much momentum does
+     * it have?" Enrichment, never discovery or ranking. Instead use
+     * {@link MaterialGraphClient.demand} for one material named in free text and
+     * {@link MaterialGraphClient.search} to find candidates at all. Only
+     * `state: "available"` carries numbers; the other three mean "no number", never
+     * "no demand".
+     *
      * Enrich a bounded set of ALREADY-CHOSEN candidate ids with their real
      * specification demand (POST `/api/v1/demand/batch`, 1–48 ids). The bounded
      * batch complement to {@link demand}: no fuzzy resolution, ranking, or
@@ -278,20 +491,36 @@ export class MaterialGraphClient {
     }
     // ── Codes (advisory building-code compliance) ────────────────────────────────
     /**
+     * THE QUESTION: "may I put these materials in an A-2 corridor in Texas?"
+     *
      * Badge materials against the advisory building-code registry (POST
      * `/api/v1/codes/advisory`). Identical to {@link CodesClient.advisory}, kept
-     * flat because it shipped before the `codes` namespace existed.
+     * flat because it shipped before the `codes` namespace existed — prefer
+     * `mg.codes.advisory()` in new code, and start at `mg.codes.context()` to
+     * discover every accepted context value. `unverified` is not a pass.
      */
     codeAdvisory(input, signal) {
         return this.codes.advisory(input, signal);
     }
     // ── Colour helpers (extract) ─────────────────────────────────────────────────
-    /** Extract a named colour palette from an uploaded image (POST `/api/v1/search/palettes/extract`). */
+    /**
+     * THE QUESTION: "what colours are in this image?" — the palette only, no
+     * materials. The bridge from an inspiration image into the colour lens: extract
+     * here, then feed the swatches to `colours.palette()` or
+     * {@link MaterialGraphClient.byColour}. Instead use
+     * {@link MaterialGraphClient.match} for the MATERIALS in the photo.
+     */
     extractPalette(input, signal) {
         return this.#post("extract_image_palette", input, signal);
     }
     // ── Catalog (facets / applicable specs / glossary) ───────────────────────────
     /**
+     * THE QUESTION: "what can I even filter on, and what values does the corpus
+     * actually hold?" The start of every spec-driven workflow. Instead use
+     * {@link MaterialGraphClient.attributeValues} for ONE attribute's distribution,
+     * {@link MaterialGraphClient.applicableSpecs} for what a product type COULD
+     * carry, {@link MaterialGraphClient.schema} for the definition.
+     *
      * Discover the live specification vocabulary (GET
      * `/api/v1/catalog/specifications/facets`) — the facetable spec attributes that
      * have real product-graph data, each with its top canonical values and the
@@ -318,20 +547,43 @@ export class MaterialGraphClient {
             attributeId,
         });
     }
-    /** The specs a product type COULD carry (GET `/api/v1/taxonomy/categories/{key}/specs`). */
+    /**
+     * THE QUESTION: "what specs COULD a material of this type carry?" — the
+     * template, not the data. Use it to know which absences are meaningful; instead
+     * use {@link MaterialGraphClient.specificationFacets} for what the corpus holds
+     * and {@link MaterialGraphClient.materialBlocks} for one material.
+     *
+     * @param key A canonical taxonomy key from {@link MaterialGraphClient.taxonomy}.
+     */
     applicableSpecs(key, signal) {
         return this.#get("get_applicable_specs", undefined, signal, { key });
     }
-    /** Resolve a term to its meaning in the schema (GET `/api/v1/glossary/{term}`). */
+    /**
+     * THE QUESTION: "what does 'DCOF' MEAN?" — one term explained, for a human.
+     * Explanation, not retrieval: instead use
+     * {@link MaterialGraphClient.searchVocabulary} to FIND a token and
+     * {@link MaterialGraphClient.attributeValues} for the values it takes.
+     */
     glossary(term, signal) {
         return this.#get("explain_material_term", undefined, signal, { term });
     }
     // ── Brands ───────────────────────────────────────────────────────────────────
-    /** List registered brands (GET `/api/v1/brands`). */
+    /**
+     * THE QUESTION: "whose catalogs are in here, and how big is each?" The SDK's
+     * one OFFSET-paginated surface: read `meta.total` for the collection size and
+     * `meta.hasMore` to keep walking. Instead use {@link MaterialGraphClient.brand}
+     * for one brand's profile and trade signals.
+     */
     brands(options = {}, signal) {
         return this.#get("list_brands", { q: options.q, limit: options.limit, offset: options.offset }, signal);
     }
-    /** Resolve a brand and return its profile + trade signals (GET `/api/v1/brands/{brandSlug}`). */
+    /**
+     * THE QUESTION: "who is this brand, and what do they claim?" — profile plus the
+     * trade/spec signals ON RECORD. `trade` is keyed by attribute id and an ABSENT
+     * key means no value is held — never infer `false`. Instead use
+     * {@link MaterialGraphClient.search} to find their materials; this describes the
+     * company, not the catalog.
+     */
     brand(brandSlug, options, signal) {
         return this.#get("get_brand_profile", { q: options?.q }, signal, {
             brandSlug,
@@ -358,15 +610,33 @@ export class MaterialGraphClient {
     sourceMaterialBatch(batchId, signal) {
         return getSourceMaterialBatchCall(this.#transport, batchId, signal);
     }
-    /** List invocable agents, workflows, and tools (GET `/api/v1/capabilities`). */
+    /**
+     * THE QUESTION: "what can the hosted agentic surface be asked to DO?" Start
+     * here before {@link MaterialGraphClient.createRun}: each capability carries its
+     * live input/output schemas, scopes and side-effect class, so nothing about a
+     * Run need be hardcoded.
+     */
     capabilities(signal) {
         return capabilitiesRun(this.#transport, signal);
     }
-    /** Start an asynchronous capability Run (POST `/api/v1/runs`). */
+    /**
+     * THE QUESTION: "do a whole job for me" — the ASYNC lens. Everything else here
+     * answers in one round trip; a Run may suspend for human input and finish
+     * minutes later. Follow with {@link MaterialGraphClient.streamRunEvents} (live)
+     * or {@link MaterialGraphClient.run} (poll); resume via
+     * {@link MaterialGraphClient.resumeRun}; pick the capability from
+     * {@link MaterialGraphClient.capabilities}. Pass `idempotencyKey` so a retry
+     * replays rather than duplicates.
+     */
     createRun(body, signal) {
         return createRun(this.#transport, body, signal);
     }
-    /** Get a Run's current state (GET `/api/v1/runs/{runId}`). */
+    /**
+     * THE QUESTION: "where has this Run got to?" — the caller-owned, redacted
+     * ledger record. Polling; prefer {@link MaterialGraphClient.streamRunEvents}
+     * when a human is waiting. `suspended` is not a failure — it means the Run is
+     * asking you something (see {@link MaterialGraphClient.resumeRun}).
+     */
     run(runId, signal) {
         return getRun(this.#transport, runId, signal);
     }
@@ -390,7 +660,11 @@ export class MaterialGraphClient {
     resumeRun(runId, resumeData, signalOrOptions) {
         return resumeRun(this.#transport, runId, resumeData, signalOrOptions);
     }
-    /** Request durable Run cancellation (POST `/api/v1/runs/{runId}/cancel`). */
+    /**
+     * THE QUESTION: "stop this Run." Requests DURABLE cancellation — the Run
+     * acknowledges and unwinds; the call returning does not mean it has stopped.
+     * Poll {@link MaterialGraphClient.run} for the terminal state.
+     */
     cancelRun(runId, signal) {
         return cancelRun(this.#transport, runId, signal);
     }
@@ -421,7 +695,11 @@ export class MaterialGraphClient {
     createProject(body = {}, signal) {
         return createProjectCall(this.#transport, body, signal);
     }
-    /** Read a project's assembled state (GET `/api/v1/projects/{projectId}`). */
+    /**
+     * THE QUESTION: "what has happened on this project?" — the append-only event log
+     * FOLDED into a read model, plus the raw `events`. Read the folded collections;
+     * the log is there for audit.
+     */
     getProject(projectId, signal) {
         return getProjectCall(this.#transport, projectId, signal);
     }
@@ -432,7 +710,10 @@ export class MaterialGraphClient {
     appendProjectEvent(projectId, body, signal) {
         return appendProjectEventCall(this.#transport, projectId, body, signal);
     }
-    /** List the caller's own projects, newest first (GET `/api/v1/projects`). */
+    /**
+     * THE QUESTION: "what Boxes do I have?" Scoped to the authenticated principal —
+     * another key's projects are invisible, not forbidden.
+     */
     listProjects(signal) {
         return listProjectsCall(this.#transport, signal);
     }

package/codes-client.d.ts

@@ -12,6 +12,16 @@
  *
  * ADVISORY ONLY: every verdict and every envelope carries the AHJ caveat — this
  * is model code as adopted, never a legal determination.
+ *
+ * ROUTING. Codes answers "is this material allowed in THIS SPACE?" — a question
+ * about a jurisdiction, an occupancy group and a finish location, not about a
+ * material alone.
+ * - "which materials carry Class A?" → `mg.bySpec("fire_classifications:...")`.
+ *   That is a property question; this namespace is what tells you the space
+ *   demands Class A in the first place.
+ * - "what does this one material hold?" → `mg.materialBlocks(variantId)`.
+ * - "find me something like this, but compliant" → `mg.search({ filters })`
+ *   once `requirements()` has told you which filter to apply.
  */
 import type { CodeAdvisoryInput, CodeAdvisoryResponse, CodeContextRequest, CodeContextResponse, CodeRequirementsResponse } from "./codes-types.js";
 import type { QueryParams } from "./http-transport.js";
@@ -25,6 +35,13 @@ export declare class CodesClient {
     #private;
     constructor(transport: CodesTransport);
     /**
+     * THE QUESTION: "what may I even say about a space?" — the vocabulary for
+     * stating a code context, and the first call of the three.
+     *
+     * Everything {@link CodesClient.requirements} and {@link CodesClient.advisory}
+     * accept is listed here, so nothing need be hardcoded and a 400 for an unknown
+     * jurisdiction / occupancy / space is always avoidable.
+     *
      * The vocabulary for stating a code context (GET `/api/v1/codes/context`):
      * seeded jurisdictions and their coverage tier, the occupancy groups the
      * registry keys on, finish locations, dimensions, classification scales with
@@ -43,6 +60,12 @@ export declare class CodesClient {
      */
     context(signal?: AbortSignal): Promise<CodeContextResponse>;
     /**
+     * THE QUESTION: "what does this space DEMAND?" — before any candidate exists.
+     *
+     * Run it before shortlisting, not after: it tells you which specification to
+     * filter on, which you then spend on `mg.bySpec()` or `mg.search({ filters })`.
+     * Use {@link CodesClient.advisory} once you hold candidates to badge.
+     *
      * What a space demands, before any candidate exists (GET
      * `/api/v1/codes/requirements`). State the space by explicit axes, or by a
      * `roomType` the axes are correlated from.
@@ -61,6 +84,19 @@ export declare class CodesClient {
      */
     requirements(input: CodeContextRequest, signal?: AbortSignal): Promise<CodeRequirementsResponse>;
     /**
+     * THE QUESTION: "do THESE candidates satisfy what this space demands?" — the
+     * third call, once you hold materials.
+     *
+     * Context is CONDITIONAL: supply `occupancyGroup` + `spaceType`, or a
+     * `roomType` for them to correlate from, or a mix — an explicit axis always
+     * wins, and an axis that resolves to nothing is a 400 naming it. The full rule,
+     * with the validator's own messages, is on {@link CodeContextRequest}.
+     *
+     * Read `summary.status` honestly: `unverified` means no comparable rating is on
+     * file. It is not a pass, and it is common. Use {@link CodesClient.requirements}
+     * when you have no candidates yet, and `mg.materialBlocks()` to see whether a
+     * material's fire/slip facts are missing or merely unverified.
+     *
      * Badge materials against the advisory building-code registry for one context
      * (POST `/api/v1/codes/advisory`, ≤ 100 ids). Each applicable requirement is
      * badged `meets` / `shortfall` / `unknown` from the material's accepted fire

package/codes-client.js

@@ -4,6 +4,13 @@ export class CodesClient {
         this.#transport = transport;
     }
     /**
+     * THE QUESTION: "what may I even say about a space?" — the vocabulary for
+     * stating a code context, and the first call of the three.
+     *
+     * Everything {@link CodesClient.requirements} and {@link CodesClient.advisory}
+     * accept is listed here, so nothing need be hardcoded and a 400 for an unknown
+     * jurisdiction / occupancy / space is always avoidable.
+     *
      * The vocabulary for stating a code context (GET `/api/v1/codes/context`):
      * seeded jurisdictions and their coverage tier, the occupancy groups the
      * registry keys on, finish locations, dimensions, classification scales with
@@ -24,6 +31,12 @@ export class CodesClient {
         return this.#transport.get("list_code_context", undefined, signal);
     }
     /**
+     * THE QUESTION: "what does this space DEMAND?" — before any candidate exists.
+     *
+     * Run it before shortlisting, not after: it tells you which specification to
+     * filter on, which you then spend on `mg.bySpec()` or `mg.search({ filters })`.
+     * Use {@link CodesClient.advisory} once you hold candidates to badge.
+     *
      * What a space demands, before any candidate exists (GET
      * `/api/v1/codes/requirements`). State the space by explicit axes, or by a
      * `roomType` the axes are correlated from.
@@ -50,6 +63,19 @@ export class CodesClient {
         }, signal);
     }
     /**
+     * THE QUESTION: "do THESE candidates satisfy what this space demands?" — the
+     * third call, once you hold materials.
+     *
+     * Context is CONDITIONAL: supply `occupancyGroup` + `spaceType`, or a
+     * `roomType` for them to correlate from, or a mix — an explicit axis always
+     * wins, and an axis that resolves to nothing is a 400 naming it. The full rule,
+     * with the validator's own messages, is on {@link CodeContextRequest}.
+     *
+     * Read `summary.status` honestly: `unverified` means no comparable rating is on
+     * file. It is not a pass, and it is common. Use {@link CodesClient.requirements}
+     * when you have no candidates yet, and `mg.materialBlocks()` to see whether a
+     * material's fire/slip facts are missing or merely unverified.
+     *
      * Badge materials against the advisory building-code registry for one context
      * (POST `/api/v1/codes/advisory`, ≤ 100 ids). Each applicable requirement is
      * badged `meets` / `shortfall` / `unknown` from the material's accepted fire