@instruments/materialgraph 0.5.0 → 0.6.1

package/client.d.ts

@@ -13,6 +13,7 @@ import type { BrandCatalogListPage, BrandsOptions } from "./brand-types.js";
 import type { MaterialAssetProjection } from "./material-asset-types.js";
 import type { MaterialBlockProjection } from "./material-block-types.js";
 import type { SchemaResource, SchemaResourceResponse } from "./schema-resource-types.js";
+import type { BatchId, ProjectId, RunId, VariantId } from "./identifiers.js";
 import type { ApplicableSpecsResponse, BrandOptions, BrandProfileResponse, ByColourParams, ByColourResponse, BySpecOptions, BySpecResponse, ColourFacetsResponse, CoordinateInput, CoordinateResponse, DemandBatchInput, DemandBatchResponse, DemandParams, DemandResponse, ExtractPaletteInput, ExtractPaletteResponse, GlossaryTermResponse, MaterialResponse, MaterialsBatchDetailResponse, MaterialsBatchGetOptions, MaterialsBatchOptions, MaterialsBatchTileResponse, MatchInput, MatchResponse, PairingsOptions, PairingsResponse, ResolveAttributeOptions, ResolveAttributeResponse, ResolveAttributeValueOptions, ResolveAttributeValueResponse, ResolveColourResponse, SearchGetParams, SearchInput, SearchResponse, SiblingsResponse, SpecFacetsDistributionResponse, SpecFacetsListResponse, SuggestColourResponse, SuggestOptions, SuggestResponse, TaxonomyResponse, VocabularySearchOptions, VocabularySearchResponse, WhoamiResponse } from "./types.js";
 export declare const DEFAULT_BASE_URL = "https://beta.materialgraph.com";
 export declare const MAX_BATCH_IDS = 100;
@@ -24,24 +25,85 @@ export interface MaterialGraphClientOptions {
     /** Inject a custom `fetch` (tests, proxies). Defaults to the global `fetch`. */
     fetch?: typeof fetch;
 }
+/**
+ * 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 declare class MaterialGraphClient {
     #private;
     readonly baseUrl: string;
+    /**
+     * 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.
+     */
     readonly browse: BrowseNamespace;
     /**
-     * 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.
      */
     readonly codes: CodesClient;
     /**
-     * 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.
      */
     readonly colours: ColoursClient;
     constructor(options: MaterialGraphClientOptions);
     get lastRateLimit(): RateLimit | null;
     /**
+     * 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:
@@ -53,7 +115,26 @@ export declare class MaterialGraphClient {
      * filters with the `certificationProgramme` / `specTerm` / `hasSpec` helpers.
      */
     search(input: SearchInput, signal?: AbortSignal): Promise<SearchResponse>;
+    /**
+     * 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: SearchGetParams, signal?: AbortSignal): Promise<SearchResponse>;
+    /**
+     * 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: MatchInput, signal?: AbortSignal): Promise<MatchResponse>;
     /**
      * Material Match as a PROGRESSIVE stream — the same POST
@@ -79,31 +160,93 @@ export declare class MaterialGraphClient {
      * buffered-only.
      */
     matchStream(input: MatchInput, signal?: AbortSignal): AsyncGenerator<MatchStreamEvent, void, unknown>;
+    /**
+     * 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: ByColourParams, signal?: AbortSignal): Promise<ByColourResponse>;
-    /** Get a single material's detail record (GET `/api/v1/materials/{variantId}`). */
-    material(variantId: string, options?: {
+    /**
+     * 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: VariantId, options?: {
         includeSiblings?: boolean;
     }, signal?: AbortSignal): Promise<MaterialResponse>;
-    /** The other variants of the same product (GET `/api/v1/materials/{variantId}/siblings`). */
-    siblings(variantId: string, signal?: AbortSignal): Promise<SiblingsResponse>;
-    /** Canonical block completeness for a material (GET `/api/v1/materials/{variantId}/blocks`). */
-    materialBlocks(variantId: string, signal?: AbortSignal): Promise<MaterialBlockProjection>;
-    /** Safe images and downloads for a material (GET `/api/v1/materials/{variantId}/assets`). */
-    materialAssets(variantId: string, signal?: AbortSignal): Promise<MaterialAssetProjection>;
-    /** Read one static governed schema resource. */
+    /**
+     * 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: VariantId, signal?: AbortSignal): Promise<SiblingsResponse>;
+    /**
+     * 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: VariantId, signal?: AbortSignal): Promise<MaterialBlockProjection>;
+    /**
+     * 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: VariantId, signal?: AbortSignal): Promise<MaterialAssetProjection>;
+    /**
+     * 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<K extends SchemaResource>(resource: K, signal?: AbortSignal): Promise<SchemaResourceResponse<K>>;
-    /** The "what pairs with this material" rail (GET `/api/v1/materials/{variantId}/pairings`). */
-    pairings(variantId: string, options?: PairingsOptions, signal?: AbortSignal): Promise<PairingsResponse>;
     /**
-     * Batch-read materials by id (POST `/api/v1/materials/batch`, ≤ 100 ids).
-     * Throws client-side before any request when more than {@link MAX_BATCH_IDS}
-     * ids are supplied.
+     * 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: VariantId, options?: PairingsOptions, signal?: AbortSignal): Promise<PairingsResponse>;
+    /**
+     * THE QUESTION: "hydrate these ids I already hold" (POST
+     * `/api/v1/materials/batch`, ≤ 100 ids) — never a discovery call. Throws
+     * client-side above {@link MAX_BATCH_IDS}. The response is NOT positional:
+     * match on `variantId` and read `missingIds` rather than comparing lengths.
+     * {@link MaterialGraphClient.materialsCached} is the CDN-friendly GET form.
+     *
+     * @param ids Opaque tokens, passed back verbatim.
      */
-    materials(ids: string[], options: {
+    materials(ids: VariantId[], options: {
         view: "detail";
         idKind?: MaterialsBatchOptions["idKind"];
     }, signal?: AbortSignal): Promise<MaterialsBatchDetailResponse>;
-    materials(ids: string[], options?: {
+    materials(ids: VariantId[], options?: {
         view?: "tile";
         idKind?: MaterialsBatchOptions["idKind"];
     }, signal?: AbortSignal): Promise<MaterialsBatchTileResponse>;
@@ -112,23 +255,37 @@ export declare class MaterialGraphClient {
      * `Cache-Control: public, max-age=300`). Same response as {@link materials};
      * prefer this for repeatable, cache-friendly id sets. Also ≤ 100 ids.
      */
-    materialsCached(ids: string[], options: {
+    materialsCached(ids: VariantId[], options: {
         view: "detail";
         idKind?: MaterialsBatchGetOptions["idKind"];
     }, signal?: AbortSignal): Promise<MaterialsBatchDetailResponse>;
-    materialsCached(ids: string[], options?: {
+    materialsCached(ids: VariantId[], options?: {
         view?: "tile";
         idKind?: MaterialsBatchGetOptions["idKind"];
     }, signal?: AbortSignal): Promise<MaterialsBatchTileResponse>;
-    /** 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?: AbortSignal): Promise<ColourFacetsResponse>;
-    /** 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: string, signal?: AbortSignal): Promise<ResolveColourResponse>;
     /** Ranked colour-name typeahead (GET `/api/v1/search/colours/suggest`). */
     suggestColour(q: string, options?: {
         limit?: number;
     }, signal?: AbortSignal): Promise<SuggestColourResponse>;
     /**
+     * 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
@@ -140,13 +297,47 @@ export declare class MaterialGraphClient {
      * const { suggestions } = await client.suggest("carr", { kind: "product" });
      */
     suggest(q: string, options?: SuggestOptions, signal?: AbortSignal): Promise<SuggestResponse>;
-    /** 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: string, options?: ResolveAttributeOptions, signal?: AbortSignal): Promise<ResolveAttributeResponse>;
-    /** 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: string, query: string, options?: ResolveAttributeValueOptions, signal?: AbortSignal): Promise<ResolveAttributeValueResponse>;
-    /** 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: string, options?: VocabularySearchOptions, signal?: AbortSignal): Promise<VocabularySearchResponse>;
     /**
+     * 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
@@ -158,22 +349,49 @@ export declare class MaterialGraphClient {
      * vocabulary with {@link specificationFacets} and {@link attributeValues}.
      */
     bySpec(spec: string | string[], options?: BySpecOptions, signal?: AbortSignal): Promise<BySpecResponse>;
-    /** 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?: AbortSignal): Promise<TaxonomyResponse>;
-    /** 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?: AbortSignal): Promise<WhoamiResponse>;
     /**
+     * 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).
      */
     coordinate(input: CoordinateInput, signal?: AbortSignal): Promise<CoordinateResponse>;
     /**
-     * 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: DemandParams, signal?: AbortSignal): Promise<DemandResponse>;
     /**
+     * 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
@@ -195,14 +413,30 @@ export declare class MaterialGraphClient {
      */
     demandBatch(input: DemandBatchInput, signal?: AbortSignal): Promise<DemandBatchResponse>;
     /**
+     * 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: CodeAdvisoryInput, signal?: AbortSignal): Promise<CodeAdvisoryResponse>;
-    /** 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: ExtractPaletteInput, signal?: AbortSignal): Promise<ExtractPaletteResponse>;
     /**
+     * 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
@@ -223,13 +457,36 @@ export declare class MaterialGraphClient {
      * or every fire classification and how many variants carry each.
      */
     attributeValues(attributeId: string, signal?: AbortSignal): Promise<SpecFacetsDistributionResponse>;
-    /** 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: string, signal?: AbortSignal): Promise<ApplicableSpecsResponse>;
-    /** 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: string, signal?: AbortSignal): Promise<GlossaryTermResponse>;
-    /** 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?: BrandsOptions, signal?: AbortSignal): Promise<BrandCatalogListPage>;
-    /** 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: string, options?: BrandOptions, signal?: AbortSignal): Promise<BrandProfileResponse>;
     /**
      * Upload one atomic source-material batch (POST `/api/v1/source-material`,
@@ -246,13 +503,31 @@ export declare class MaterialGraphClient {
      * immediately. A batch you do not own raises the same 404 as one that does not
      * exist. Requires the `mg:compose` scope.
      */
-    sourceMaterialBatch(batchId: string, signal?: AbortSignal): Promise<SourceMaterialBatchDetail>;
-    /** List invocable agents, workflows, and tools (GET `/api/v1/capabilities`). */
+    sourceMaterialBatch(batchId: BatchId, signal?: AbortSignal): Promise<SourceMaterialBatchDetail>;
+    /**
+     * 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?: AbortSignal): Promise<CapabilityManifestResponse>;
-    /** 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: CreatePublicRunRequest, signal?: AbortSignal): Promise<CreatePublicRunResponse>;
-    /** Get a Run's current state (GET `/api/v1/runs/{runId}`). */
-    run(runId: string, signal?: AbortSignal): Promise<PublicRunResponse>;
+    /**
+     * 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: RunId, signal?: AbortSignal): Promise<PublicRunResponse>;
     /**
      * Export a completed compose Run's scheme as a finish schedule — one row per
      * slot, every attribute value carrying its source and verification state
@@ -260,7 +535,7 @@ export declare class MaterialGraphClient {
      * `missing` cells, never blanks. The `.xlsx` form is a direct-URL download:
      * `GET /api/v1/runs/{runId}/schedule.xlsx` with the same bearer key.
      */
-    runSchedule(runId: string, options?: GetRunScheduleOptions): Promise<FinishScheduleResponse>;
+    runSchedule(runId: RunId, options?: GetRunScheduleOptions): Promise<FinishScheduleResponse>;
     /**
      * Resume a suspended Run (POST `/api/v1/runs/{runId}/resume`).
      *
@@ -268,9 +543,13 @@ export declare class MaterialGraphClient {
      * {@link ResumeRunOptions}, whose `stepId` guards against resuming a step the
      * run has already moved past — the API answers 409 on a mismatch (MG-608).
      */
-    resumeRun(runId: string, resumeData: unknown, signalOrOptions?: AbortSignal | ResumeRunOptions): Promise<PublicRunResponse>;
-    /** Request durable Run cancellation (POST `/api/v1/runs/{runId}/cancel`). */
-    cancelRun(runId: string, signal?: AbortSignal): Promise<PublicRunResponse>;
+    resumeRun(runId: RunId, resumeData: unknown, signalOrOptions?: AbortSignal | ResumeRunOptions): Promise<PublicRunResponse>;
+    /**
+     * 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: RunId, signal?: AbortSignal): Promise<PublicRunResponse>;
     /**
      * Derive an "option B" scheme from a succeeded compose Run along one
      * constraint axis (POST `/api/v1/schemes/vary`). Deterministic and
@@ -284,25 +563,32 @@ export declare class MaterialGraphClient {
      * `/api/v1/runs/{runId}/events`, SSE). Iterates until the stream ends or the
      * signal aborts; pass `after` to resume from the last observed sequence.
      */
-    streamRunEvents(runId: string, options?: StreamRunEventsOptions): AsyncGenerator<RunEvent>;
+    streamRunEvents(runId: RunId, options?: StreamRunEventsOptions): AsyncGenerator<RunEvent>;
     /**
      * Create a persistent project owned by the caller (POST `/api/v1/projects`).
      * Returns the freshly assembled state (an empty event log). Requires the
      * `mg:ingest` scope.
      */
     createProject(body?: CreateProjectRequest, signal?: AbortSignal): Promise<ProjectState>;
-    /** Read a project's assembled state (GET `/api/v1/projects/{projectId}`). */
-    getProject(projectId: string, signal?: AbortSignal): Promise<ProjectState>;
+    /**
+     * 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: ProjectId, signal?: AbortSignal): Promise<ProjectState>;
     /**
      * Append one event to a project's append-only process trail (POST
      * `/api/v1/projects/{projectId}/events`). Requires the `mg:ingest` scope.
      */
-    appendProjectEvent(projectId: string, body: AppendProjectEventRequest, signal?: AbortSignal): Promise<ProjectEventReceipt>;
-    /** List the caller's own projects, newest first (GET `/api/v1/projects`). */
+    appendProjectEvent(projectId: ProjectId, body: AppendProjectEventRequest, signal?: AbortSignal): Promise<ProjectEventReceipt>;
+    /**
+     * THE QUESTION: "what Boxes do I have?" Scoped to the authenticated principal —
+     * another key's projects are invisible, not forbidden.
+     */
     listProjects(signal?: AbortSignal): Promise<ProjectListResponse>;
     /**
      * Collect Run events until a terminal event, the deadline, or the stream ends
      * — the bounded events-log pattern (a single pass over {@link streamRunEvents}).
      */
-    drainRunEvents(runId: string, options: DrainRunEventsOptions): Promise<RunEvent[]>;
+    drainRunEvents(runId: RunId, options: DrainRunEventsOptions): Promise<RunEvent[]>;
 }