# MaterialGraph

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

## Overview

MaterialGraph is a product graph for architectural specification. It models a brand catalog as product families, product models, variants, and orderable configurations, with typed blocks backed by sources, source facts, claim sources, and scoped attribute values. The Operator Request Router uses Mastra agents, tools, and workflows to run source intake, site discovery, catalog ingestion, and product assessment.

The system ships as:
- A **Next.js web app** for browsing, reviewing, and operating on the graph
- A **CLI (`mg`)** for agent-first, pipe-friendly access to product data
- A **Mastra-based runtime** where the Operator Request Router delegates focused source and catalog work

## CLI

The `mg` CLI provides structured JSON output, NDJSON streaming, field masks, and `--dry-run` on all mutating commands.

- `mg variant list` — list product variants within the family/product hierarchy
- `mg variant get <id>` — full canonical variant record
- `mg variant blocks <id>` — block projections with status and gaps
- `mg variant assets <id>` — product images and downloads
- `mg brand list` — all brands with portfolio summaries
- `mg brand get <slug>` — full brand dossier
- `mg review list` — review tasks (filterable by status)
- `mg review get <id>` — review task detail with source support
- `mg source intake <url>` — classify and plan source-level URL intake
- `mg source intake <url> --apply` — apply source-level intake artifacts
- `mg schema blocks` — 31 canonical block definitions
- `mg schema attributes` — all 269 attribute definitions with types
- `mg schema verticals` — vertical and category identifiers
- `mg schema introspect <command>` — parameter schema for any CLI command
- `mg skills list` — discover agent skill files
- `mg skills get <name>` — load a skill by name
- `mg skills context` — the root CONTEXT.md for agent onboarding

## Agent System

The Operator Request Router is the main interface. Capability agents and workflows stay focused: source intake maps site structure, catalog agents extract families, product models, variants, brand options, and product options, and block capability agents assess source-backed attributes when needed.

## Schema

31 blocks, 269 attributes, 4 verticals (Materials, FF&E, Architectural, Equipment). The schema registry provides typed definitions, category compositions, applicability tags, value shapes, interoperability mappings (schema.org, IFC, GDSN, ETIM, Uniclass), and category profiles for jurisdiction/channel overrides.

## API

Public REST API — `/api/v1` (56 endpoints, grouped):

- **Search** — /api/v1/search, /api/v1/search/specifications, /api/v1/search/match, /api/v1/search/colours, /api/v1/search/browse, /api/v1/search/palettes/extract, /api/v1/search/colours/resolve, /api/v1/search/colours/suggest, /api/v1/colours/facets
- **Materials** — /api/v1/materials/{variantId}, /api/v1/materials/{variantId}/blocks, /api/v1/materials/{variantId}/assets, /api/v1/materials/{variantId}/siblings, /api/v1/materials/{variantId}/substitutes, /api/v1/materials/{variantId}/revit, /api/v1/materials/batch
- **Pairings** — /api/v1/materials/{variantId}/pairings, /api/v1/pairings/coordinate, /api/v1/demand, /api/v1/demand/batch
- **Catalog** — /api/v1/codes/advisory, /api/v1/catalog/attributes/resolve, /api/v1/catalog/attributes/{attributeId}/values/resolve, /api/v1/catalog/vocabulary/search, /api/v1/catalog/specifications/facets, /api/v1/catalog/attributes/{attributeId}/values, /api/v1/taxonomy/categories, /api/v1/taxonomy/categories/{key}/specs, /api/v1/glossary/{term}
- **Brands** — /api/v1/brands, /api/v1/brands/{brandSlug}, /api/v1/brands/{brandSlug}/revit/library
- **Meta** — /api/v1/whoami

- Auth: `Authorization: Bearer mg_<read|compose|ingest|write|admin>_<random>` or `X-API-Key`; every key grants `mg:read`, while compose (designer uploads, projects, compose runs), ingest, and write are separate tiers
- `GET /openapi.yaml` — OpenAPI document for the public API
- `POST /mcp` — live MCP endpoint (stateless Streamable HTTP), same `Bearer mg_<…>` auth, exposing the read tools
- `GET /.well-known/agent-card.json` — A2A agent card describing capabilities
- `GET /.well-known/oauth-protected-resource` — OAuth protected-resource metadata
- `POST /api/auth/token` — RFC 8693 token exchange
- `/developers` — human-readable API documentation