# MaterialGraph — Full Reference

> Product communication protocol for architectural materials. A structured graph of textiles, lighting, hardware, tile, and surfaces — with agent-driven data quality.

## Overview

MaterialGraph models architectural product catalogs as a hierarchy of brands, product families, product models, variants, and orderable configurations. Blocks can apply at brand, family, product, variant, or attribute scope, and every canonical value is backed by source materials, source facts, claim sources, and typed scoped attribute values. A typed schema registry defines every block, attribute, vertical, category, and value shape. A Mastra-based runtime orchestrates focused agents and workflows for source intake, site discovery, catalog ingestion, and source-backed product assessment.

The system is designed for both human and agent consumers. The CLI outputs structured JSON, supports field masks for response shaping, streams NDJSON in pipe contexts, and provides runtime schema introspection so agents can discover accepted parameters without documentation.

---

## CLI Reference (`mg`)

Environment variables:
- `DIRECT_DATABASE_URL` / `DATABASE_URL` — Canonical Neon connection string (required for read commands)

Global behaviors:
- All commands output JSON
- In non-TTY contexts (pipes), arrays stream as NDJSON
- Use `--fields` to limit response size: `mg variant list --fields variantId,brandName`
- Use `--body <json>` or stdin pipe for structured input
- Use `--dry-run` on all mutating commands to validate before acting

### variant

#### `mg variant list`
List product variants within the canonical brand -> family -> product model hierarchy. Streams NDJSON when piped.

Options:
- `--brand <slug>` — Filter by brand slug
- `--body <json>` — Raw JSON payload. Shape: `{ brandSlugs?: string[], limit?: number }`
- `--fields <mask>` — Comma-separated dot-path field mask
- `--json` — Force JSON output even in TTY

Body schema: `{ brandSlugs?: string[]; limit?: number }`

Example: `echo '{"brandSlugs":["maharam"]}' | mg variant list`

#### `mg variant get <variantId>`
Get the full canonical variant record. A variant is a concrete option or SKU-like expression of a product model, not the product family itself.

Arguments:
- `variantId` (required) — Canonical variant id.

Options:
- `--body <json>` — Raw JSON payload. Shape: `{ variantId: string }`
- `--fields <mask>` — Comma-separated dot-path field mask
- `--json` — Force JSON output even in TTY

#### `mg variant blocks <variantId>`
Get block projections for a variant — status, fields, and gaps per canonical block.

Arguments:
- `variantId` (required)

Options:
- `--body <json>` — Shape: `{ variantId: string }`
- `--fields <mask>` — e.g. `canonicalBlockId,status,missingAttributeIds`
- `--json` — Force JSON output even in TTY

#### `mg variant assets <variantId>`
Get all product assets (images, downloads) for a variant.

Arguments:
- `variantId` (required)

Options:
- `--body <json>` — Shape: `{ variantId: string }`
- `--fields <mask>` — e.g. `key,visualRole,proxyPath,status`
- `--json` — Force JSON output even in TTY

### brand

#### `mg brand list`
List all brands with portfolio summaries. Streams NDJSON when piped.

Options:
- `--fields <mask>` — e.g. `brandSlug,name,posture`
- `--json` — Force JSON output even in TTY

#### `mg brand get <brandSlug>`
Get the full dossier for a brand — portfolio, posture, recommendations.

Arguments:
- `brandSlug` (required)

Options:
- `--fields <mask>` — e.g. `name,posture,portfolio.slug,portfolio.score`
- `--json` — Force JSON output even in TTY

### review

#### `mg review list`
List all review tasks. Streams NDJSON when piped.

Options:
- `--status <status>` — Filter by status: `open`, `queued`, `approved`
- `--fields <mask>` — e.g. `id,title,status,severity`
- `--json` — Force JSON output even in TTY

#### `mg review get <taskId>`
Get full detail for a review task, including source support and record context.

Arguments:
- `taskId` (required)

Options:
- `--fields <mask>` — e.g. `task.id,task.title,task.status`
- `--json` — Force JSON output even in TTY

### source

#### `mg source intake <url>`
Classify a manufacturer, catalog, product, PDF, or image URL and return the
bounded source-intake route.

Arguments:
- `url` (required) — Public HTTP(S) source URL

Options:
- `--apply` — Apply source-level artifacts and review tasks; downstream catalog and attribute rows are provisional until reviewed
- `--title <title>` — Optional source title
- `--fields <mask>` — Comma-separated dot-path field mask
- `--json` — Force JSON output even in TTY

### schema

#### `mg schema blocks`
List all 31 canonical block definitions with their attribute IDs and descriptions.

Options:
- `--json` — Force JSON output even in TTY

#### `mg schema attributes`
List all 269 canonical attribute definitions with types, units, enums, and descriptions.

Options:
- `--json` — Force JSON output even in TTY

#### `mg schema verticals`
List all vertical and category identifiers.

Options:
- `--json` — Force JSON output even in TTY

#### `mg schema introspect <commandPath>`
Return the parameter schema for a CLI command path.

Arguments:
- `commandPath` (required) — e.g. `"variant list"`, `"source intake"`, `"review list"`

Returns accepted options, types, valid enum values, and whether each is required.

Options:
- `--json` — Force JSON output even in TTY

### skills

#### `mg skills list`
List all available skills with name, description, and version. Streams NDJSON when piped.

Options:
- `--json` — Force JSON output even in TTY

#### `mg skills get <name>`
Print the full content of a skill file. Agents load this at conversation start for guardrails and patterns.

Arguments:
- `name` (required) — Lowercase letters, digits, and hyphens only

Options:
- `--json` — Wrap output in JSON envelope: `{ name, content }`

#### `mg skills context`
Print the root CONTEXT.md — the recommended starting point for agents new to mg.

Options:
- `--json` — Wrap output in JSON envelope: `{ content }`

---

## Schema Registry

### Verticals

| ID | Name | Description |
|----|------|-------------|
| `materials` | Materials | Finish and construction material products used across specification workflows. |
| `ffe` | FF&E | Furniture, fixtures, and equipment products captured for specification and procurement. |
| `architectural` | Architectural | Architectural systems, assemblies, sanitaryware, and hardware used in project delivery. |
| `equipment` | Equipment | Performance-led equipment products such as lighting and technical systems. |

### Canonical Blocks (31)

Each block represents a domain of product data. Products compose blocks based on their category.

| Block ID | Name | Attributes |
|----------|------|------------|
| `identity` | Identity | brand_name, family_name, variant_name, manufacturer_code, designer_name, product_summary, source_url, material_families, tagline, description, founded_year, headquarters_city, headquarters_country, ownership_type, legal_entity_name, positioning, distribution_model, design_philosophy, primary_materials, key_markets, employee_count_range, revenue_range, stock_ticker, trading_names, logo_url |
| `trade` | Trade Signals | material_bank_presence, bim_library_url, sample_program_url, trade_program_url, cpd_ceu_offerings, trade_email |
| `links` | Links & Contact | homepage_url, general_email, press_email, phone_number, press_kit_url, brand_guidelines_url |
| `material_composition` | Material Composition | hide_size, hide_configuration, primary_material, finish_name, composition_breakdown, material_content, abrasion_resistance, abrasion_classifications, leather_types, tannage_methods, fiber_types, wood_species, species_latin_name, wood_grade, wood_cut |
| `colour` | Colour | colour_name, colour_code, colour_hex, colour_oklch, colour_family, colour_mood, colour_undertone, colour_ral, colour_ncs, colour_pantone, colour_palette, light_reflectance_value |
| `physical_dimensions` | Physical Dimensions | dimensions, physical_form |
| `photometric` | Photometric | lumens, cri, color_temperature_k, diffuser_type |
| `electrical` | Electrical | current_rating, voltage, voltage_range, frequency_hz, wattage, maximum_circuit_load, supported_load_types, control_protocols, protocol_power_limits, multi_gang_derating, minimum_circuit_load, screwless |
| `installation` | Installation | installation_summary, minimum_back_box_depth_mm, recommended_back_box_depth_mm, breaker_rating_range, supported_wiring_modes, max_control_points, canopy_type, affixing_systems, recommended_grout |
| `acoustic` | Acoustic | nrc_rating, stc_rating, absorption_class |
| `fire_rating` | Fire Rating | euroclass, fire_classifications, flame_spread_index, smoke_development_index, performance_test_results |
| `environmental_rating` | Environmental Rating | ip_rating |
| `sustainability` | Sustainability | voc_emissions, epd_available, cdph_v1_2_compliant, sustainability_certifications, environmental_product_declaration, epd_expiration_date, ingredient_disclosure, 75percent_of_ingredients_disclosed, material_health_certifications, leed, voc_emissions_testing_certificate, voc_emissions_testing_methodology, emissions, global_warming_potential_gwp, gwp_functional_unit, post_consumer_recycled_content_percentage, post_industrial_recycled_content_percentage, fsc_certified_wood, environmental_benefits, environmental_benefits_filter, sustainability_action_plan, climate_impact, circular_economy, ecosystem_health, human_health_impact, social_equity_impact, sustainability_claims, bio_based_content_percentage, feature_tags |
| `compliance` | Compliance | certifications, csi_masterformat, country_of_origin, state_of_origin, city_of_origin |
| `availability` | Availability | availability_summary, lead_time_days, lead_time_min_days, lead_time_text |
| `product_option_controls` | Product Option Controls | variant_axes, orderable_option_count, default_variant_axis_values, option_matrix_source_url, declared_size_options, declared_thickness_options, declared_finish_options |
| `application_scope` | Application Scope | suitability_claims, application_locations, substrate_compatibility, application_methods, environmental_exposure, material_roles, industry_sectors, applications, application_rooms, category_paths |
| `performance_tests` | Performance Tests | water_resistance, performance_test_results, slip_resistance_dcof, pei_rating, mohs_hardness, water_absorption_pct, abrasion_cycles, breaking_strength_n, chemical_resistant, frost_resistant, stain_resistance_rating, performance_category |
| `coating_system` | Coating System | coating_product_type, sheen, tint_base, coating_vehicle, volume_solids_pct, spread_rate, film_thickness, dry_time, recoat_time, recommended_coats, coating_application_methods, coating_cleanup_method, voc_content_g_l, application_temperature_range |
| `tile_surface` | Tile Surface | tile_material_family, tile_body_type, tile_format, nominal_tile_size, actual_tile_size, tile_thickness, tile_finish, tile_look, tile_pattern, edge_type, shade_variation, tile_faces_count, grout_joint_width, rectified, mesh_mounted, backing_type, trim_profile |
| `textile_construction` | Textile Construction | textile_product_type, textile_construction, construction_methods, textile_backing, textile_finish_treatment, roll_width, pattern_repeat, pattern_repeat_vertical_mm, pattern_repeat_horizontal_mm, railroaded, fiber_types |
| `cleanability` | Cleanability | cleaning_code, cleaning_protocols, bleach_cleanable, disinfectant_compatible, antimicrobial_treatment, moisture_barrier, pfas_free, flame_retardant_free, ink_resistance |
| `packaging_logistics` | Packaging and Logistics | packaging_units, coverage_per_package, package_coverage_unit, pieces_per_package, package_weight, sample_size, sample_notes, sample_width_mm, sample_height_mm, sample_image_mm_per_px, mb_sample_type, mb_fulfillment_mode, mb_associated_samples |
| `pricing` | Pricing | price_tier, display_price, orderable_price, list_price, currency, moq |
| `sampleability` | Sampleability | sample_sources |
| `warranty` | Warranty | warranty_years, warranty_text, expected_lifespan, cleaning_method, maintenance_frequency |
| `imagery` | Imagery | image_count, downloaded_image_count, primary_image_url |
| `digital_assets` | Digital Assets | digital_assets |
| `documents` | Documents | spec_sheet_url, install_guide_available, download_count, declaration_of_conformity_url |
| `aesthetic` | Aesthetic | style_families, mood_descriptors, character_tags, shape_descriptors, compositional_roles, pattern_type, pattern_density, pattern_scale, pattern_regularity, directionality, imitative_appearance, surface_sheen, surface_reflectivity, surface_texture, transparency |
| `lighting` | Lighting | lighting_fixture_types, lighting_lamp_types, lighting_features, light_count, max_wattage |

### Attribute Types

Attributes use these data types: `string`, `text`, `integer`, `number`, `boolean`, `enum`, `object`, `array`, `reference`.

Applicability levels: `required`, `recommended`, `optional`, `unusual`.

### Category Composition

Each product category defines which blocks apply and at what applicability level. For example, a lighting product requires identity, photometric, electrical, imagery, and documents blocks; acoustics is not applicable.

### Interoperability Mappings

The schema registry includes mappings to external standards:
- **schema.org** — web-standard structured data
- **IFC PSets** — BIM interoperability
- **GDSN** — global data synchronization
- **ETIM** — electro-technical classification
- **Uniclass** — construction classification

---

## Agent System

### Architecture

The agent runtime is built on Mastra. The Operator Request Router is the main interface, and it delegates to focused capability agents and deterministic workflows for source intake, site discovery, catalog ingestion, and source-backed product assessment.

Agent definition structure:
```
agents/<block-id>/
  role.md       — what the agent is responsible for
  domain.md     — domain expertise, standards, heuristics
  tools.md      — capabilities the agent needs
  playbook.md   — step-by-step assessment procedure
```

### Agent Capabilities

Every agent may: **validate**, **enrich**, **assess**, **explain**, **monitor**. Not every agent activates all five capabilities initially — the playbook specifies which are active.

### Autonomy Levels

- **assess-only** — reads data, produces findings, no writes
- **propose** — produces proposed writes requiring human review
- **auto-accept** — writes directly for low-risk, high-confidence changes

All agents start at assess-only. Promotion requires demonstrated accuracy.

### Supervisor Delegation

The Operator Request Router chooses the smallest focused path for the operator's goal:
site discovery for brand roots, catalog ingestion for families/products/options,
document extraction for PDFs, and block capability agents for targeted
source-backed attribute assessment.

### Quality Scoring

MaterialGraph computes product quality from canonical graph coverage:

```
score = blockCoverage * 55
      + attributeCoverage * 25
      + sourceSignal * 10
      + sourceSignal * 10
      - penalty
```

Posture assignment:
- 85+ = "Spec ready"
- 70-84 = "Strong with follow-up"
- 55-69 = "In progress"
- <55 = "Needs capture"

### Cross-Block Consistency Checks

Product review includes cross-block checks:
1. Material vs imagery — material claims should match visual source support
2. Electrical vs installation — breaker ratings must align with circuit load
3. Dimensions vs imagery — claimed dimensions should match visual proportions
4. Compliance vs sustainability — certifications should align with declared standards
5. Pricing vs availability — pricing without availability is half-specified
6. Documents vs all — spec sheet claims should not contradict domain agent findings

---

## Ingest Pipeline

The pipeline runs in four sequential stages:

### 1. Discover
Maps the manufacturer's website into source zones for brand information, family indexes, family detail pages, product-model pages, variant/option surfaces, documents, images, and locale-specific paths.

### 2. Capture
Fetches selected source materials such as HTML, images, PDFs, and documents from the discovered zones.

### 3. Normalize
Transforms source facts into canonical families, product models, variants, options, assets, and scoped attribute values. Agents must return strict structured data matching the runtime and schema contracts.

### 4. Persist
Writes source-backed catalog data directly into the canonical database as brand, family, product, variant, orderable configuration, asset, source fact, claim source, attribute value, source-backed change, and quality-gap records.

Each stage supports `--dry-run` to validate inputs and report what would happen without side effects.

---

## Data Model

### Product Family
A manufacturer collection or line that groups related product models. A family should not collapse into one catch-all product simply because it has many colours or sizes.

### Product Model
The primary product concept within a family: for example a field tile, bullnose trim, cove base, chair, fixture, fabric pattern, or paint line. A product model carries the shared identity and category that variants refine.

### Product Variant
A concrete option or SKU-like expression of a product model, usually defined by axes such as colour, finish, size, format, backing, or mounting. A bullnose or cove base is normally a separate product model when it has a distinct functional role, not merely a size variant of a field tile.

### Orderable Configuration
The purchasable configuration or SKU when the source distinguishes sellable combinations below the variant layer.

### Block Projection
The per-block view of a brand, family, product, variant, or attribute scope. Each projection has:
- `canonicalBlockId` — which block this is
- `status` — coverage state (complete, partial, missing)
- `populatedAttributeIds` — which attributes have values
- `missingAttributeIds` — which expected attributes lack values

### Brand Dossier
Aggregate brand-level view including portfolio statistics, quality posture, and recommendations.

### Review Task
A finding from an agent run that requires human review. Has status (open, queued, approved), severity, and linked sources.

---

## Public REST API (/api/v1)

The stable, authenticated public surface. Every operation requires a bearer
token or API key with at least the `mg:read` scope. Full contract:
`GET /openapi.yaml`.

- `GET /api/v1/search` — Query-string search — text, colour, mood, or 'looks like this' by variant id
- `POST /api/v1/search` — Full search contract — text, image, palette, similarity, typed filters, one primitive
- `GET /api/v1/search/specifications` — Find materials by canonical specification across every brand, with per-criterion trust
- `POST /api/v1/search/match` — Material Match — image → category-scoped matches; `?stream=1` for scene workflow NDJSON
- `GET /api/v1/search/colours` — Find materials by colour palette, ranked by closeness across every brand
- `GET /api/v1/search/browse` — Browse the corpus by colour — lightest to darkest, muted to vivid, true pagination
- `POST /api/v1/search/palettes/extract` — Extract a named colour palette from an uploaded image
- `GET /api/v1/search/colours/resolve` — Resolve a colour name or phrase — 'sage', a paint name — to a hex
- `GET /api/v1/search/colours/suggest` — Ranked colour-name typeahead for autocomplete, fuzzy-tolerant
- `GET /api/v1/colours/facets` — The colour value dictionaries — family, mood, undertone — with per-term variant and brand counts
- `GET /api/v1/materials/{variantId}` — Full material detail — identity, colour, category, palette, facets, dimensions
- `GET /api/v1/materials/{variantId}/blocks` — Canonical blocks, field values and statuses, and missing attribute ids
- `GET /api/v1/materials/{variantId}/assets` — Proxy images, safe downloads, and asset counts without provider internals
- `GET /api/v1/materials/{variantId}/siblings` — The other colourways and finishes of the same product
- `GET /api/v1/materials/{variantId}/pairings` — Materials specified together on real projects first, colour-similar top-up — every item labelled by source
- `POST /api/v1/materials/{variantId}/substitutes` — Find same-spec candidates across brands with explicit trust — discovery, not substitution approval
- `GET /api/v1/materials/{variantId}/revit` — Download a material's Revit specification package as a zip
- `GET /api/v1/materials/batch` — Batch-read up to 100 materials by id, cacheable query-string form
- `POST /api/v1/materials/batch` — Batch-read up to 100 materials by id, JSON body form
- `POST /api/v1/pairings/coordinate` — Coordinate several chosen materials into demand-ranked, colour-annotated companions
- `GET /api/v1/demand` — How much a material is specified, plus the materials specified alongside it
- `POST /api/v1/demand/batch` — Enrich up to 48 exact candidate ids with specification demand — one ordered result per id, no ranking
- `POST /api/v1/codes/advisory` — Badge materials against the advisory building-code registry — fire, floor, slip — by jurisdiction and occupancy (advisory, never a legal determination)
- `POST /api/v1/schemes/vary` — Derive an option-B scheme from a composed Run along a constraint axis — palette, sustainability, brand diversity, or price tier — preserving the brief's hard gates
- `GET /api/v1/catalog/attributes/resolve` — Resolve a free-text spec phrase — 'double rubs' — to canonical attribute ids, ranked by meaning
- `GET /api/v1/catalog/attributes/{attributeId}/values/resolve` — Resolve a free-text value phrase — 'navy' — to a canonical term for one dictionary-backed attribute
- `GET /api/v1/catalog/vocabulary/search` — Lexical + semantic search over the controlled vocabularies — attributes and canonical terms — ranked by meaning
- `GET /api/v1/catalog/specifications/facets` — Discover facetable specification attributes and their top live values
- `GET /api/v1/catalog/attributes/{attributeId}/values` — List one attribute's live value distribution across variants and brands
- `GET /api/v1/taxonomy/categories` — The product-category tree — groups and their product types, with display-name paths
- `GET /api/v1/taxonomy/categories/{key}/specs` — The specs a product type could carry — blocks and attributes graded by applicability
- `GET /api/v1/glossary/{term}` — Resolve a term to its meaning — an attribute definition or a canonical dictionary value
- `GET /api/v1/schema/blocks` — Canonical blocks with governed semantic identity and attribute membership
- `GET /api/v1/schema/attributes` — Canonical attributes with types, units, dictionaries, source rules, and mappings
- `GET /api/v1/schema/verticals` — Top-level architectural-material vertical definitions
- `GET /api/v1/schema/product-types` — Governed product types and their applicable blocks
- `GET /api/v1/schema/units` — Canonical units, accepted source units, and conversions
- `GET /api/v1/schema/value-dictionaries` — Governed controlled vocabularies and canonical terms
- `GET /api/v1/schema/source-requirements` — Source, extraction, confidence, and review requirements
- `GET /api/v1/schema/product-type-templates` — Product-type block applicability and completeness templates
- `GET /api/v1/schema/mappings` — Interoperability mappings from canonical paths to external standards
- `GET /api/v1/brands` — List registered brands with product and variant counts
- `GET /api/v1/brands/{brandSlug}` — Resolve a brand to its identity and trade / specification signals
- `GET /api/v1/brands/{brandSlug}/revit/library` — Download a brand's bulk Revit library as a zip (?limit=, default 1000, cap 5000)
- `POST /api/v1/source-material` — Upload a source-material batch — a pile of files (PDF, text, images) the pipeline classifies
- `GET /api/v1/capabilities` — List the governed agents, workflows, and tools available through durable Runs
- `POST /api/v1/runs` — Start a validated, asynchronous capability Run
- `GET /api/v1/runs/{runId}` — Read the caller-owned, redacted state of a Run
- `GET /api/v1/runs/{runId}/events` — Read ordered, redacted events after a Run sequence cursor
- `POST /api/v1/runs/{runId}/resume` — Resume a suspended Run through the durable command outbox
- `POST /api/v1/runs/{runId}/cancel` — Request cancellation of a Run's Inngest execution
- `POST /api/v1/projects` — Create a persistent Material Box project owned by your principal
- `GET /api/v1/projects` — List your projects, newest first — summaries, capped at 50
- `GET /api/v1/projects/{projectId}` — Read a project's assembled state — identity plus the collections folded from its event log
- `POST /api/v1/projects/{projectId}/events` — Append one event to a project's process trail — a batch, run, answer, preference, reference, or adopted scheme
- `GET /api/v1/whoami` — Echo the authenticated principal and scopes — verify your key

### Authentication

- `Authorization: Bearer <token>` — an API key or JWT. An API key may
  alternatively be sent via `X-API-Key`.
- Key format: `mg_<read|compose|ingest|write|admin>_<random>`, e.g. `mg_read_...`.
- Scope grants:
  - `read` → `mg:read`
  - `compose` → `mg:read`, `mg:compose` (designer working data: uploads, projects, compose runs)
  - `ingest` → `mg:read`, `mg:ingest`, `mg:compose`
  - `write` → `mg:read`, `mg:write`
  - `admin` → `mg:read`, `mg:write`, `mg:admin`, `mg:ingest`, `mg:compose`
- Every `/api/v1` operation requires `mg:read`. A missing/invalid credential
  returns a 401 problem; insufficient scope returns a 403 problem.
- `POST /api/auth/token` — RFC 8693 token exchange. Accepts form-encoded
  input, returns a short-lived MaterialGraph token or an RFC 7807 problem.

### Errors

Every `/api/v1` route returns RFC 7807 problem details
(`application/problem+json`) on error, with these fields:
- `type` — stable URI identifying the error type
- `title` — short human-readable summary
- `status` — HTTP status code
- `detail` — human-readable explanation of this occurrence
- `is_retriable` — whether the caller should retry the request
- `suggestions` — concrete recovery hints aimed at agent consumers
- `trace_id` — request-scoped identifier for log correlation

### Rate limits

Every 2xx response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`,
and `X-RateLimit-Reset` headers. Today these are static defaults (not yet
tracked per key); per-key enforcement is pending. Do not rely on the exact
values, but do honor `X-RateLimit-Reset` before retrying a 429.

### Revit Export

Two endpoints return a downloadable Revit "specification package" as a
`application/zip` attachment (`Content-Disposition: attachment`), built fresh
per request (`Cache-Control: no-store`):

- `GET /api/v1/materials/{variantId}/revit` — one material's package: a
  shared-parameters definition, a type catalog (parameter ids are stable,
  GUID-derived), a CSI MasterFormat classification, a `manifest.json`, a
  `README.txt`, and a `swatch.png` when the variant has one. 404
  (`MATERIAL_NOT_FOUND`) when the variant id does not resolve.
- `GET /api/v1/brands/{brandSlug}/revit/library` — the whole brand as one bulk zip:
  shared parameters, one type-catalog row per material, a `colours.csv`, and a
  README. `?limit=` bounds it (default 1000, capped at 5000); when the brand
  overflows the cap the library is truncated, the response carries
  `X-MG-Truncated: true`, and the README states the truncation in band.

The packages carry no PBR textures and no self-authored `.adsklib`; the
native-appearance rung is marked "planned" in the manifest (it goes through APS
Design Automation).

---

## Endpoints

| Path | Description |
|------|-------------|
| `/` | Web application |
| `/llms.txt` | LLM-oriented summary (this project) |
| `/llms-full.txt` | Extended reference (this file) |
| `/mcp` | Live MCP endpoint (stateless Streamable HTTP, `Bearer mg_<…>`) |
| `/.well-known/agent-card.json` | A2A agent card |
| `/robots.txt` | Crawler directives |