docs: adopt MmdMaterialAPI policy

README.md

@@ -82,17 +82,22 @@ contract is [docs/design/PHYSICS_INTEGRATION.md](docs/design/PHYSICS_INTEGRATION
 | `mmdMotionAdapter` | plain C++ library | turns fully evaluated MMD poses into `MotionClip`; no target-avatar knowledge | exists |
 | `vmd_inspect` | CLI | what a VMD contains, without a model or USD | exists ([guide](docs/guides/inspecting.md)) |
 
-`mmdSchema` exists only if an MMD API schema passes the
-[admission test](docs/design/DESIGN_POLICY.md#6-the-schema-admission-test); the
-first stage uses standard schemas only. Identities and dependency directions
-are fixed in [docs/architecture/WORKSPACE.md](docs/architecture/WORKSPACE.md).
+`MmdMaterialAPI` passed the
+[admission test](docs/design/DESIGN_POLICY.md#6-the-schema-admission-test) on
+2026-09-22 for the `hydra-toon` consumer. The current stage-contract v1 still
+uses schema-less `mmd:material:*` attributes; Phase 8 adds `mmdSchema`, applies
+the API as a backward-compatible contract-v1 addition, and adds the independent
+`mmdImaging` bridge without renaming those properties. Identities and dependency
+directions are fixed in
+[docs/architecture/WORKSPACE.md](docs/architecture/WORKSPACE.md).
 
 ## What the importer will author
 
 ```text
 /Asset                    UsdSkelRoot, kind = component, defaultPrim; Y-up, meters
   geo/Mesh                UsdGeomMesh, skinned; one GeomSubset per material
   mtl/<material>          UsdShadeMaterial: MMD semantics + /preview and /mtlx graphs
+                          (Phase 8 target: + MmdMaterialAPI)
   skel/Skeleton           UsdSkelSkeleton in canonical joint order
   morph/<morph>           UsdSkelBlendShape for vertex morphs; others preserved declaratively
   rig/Bones, rig/ik/<bone> MMD control semantics: IK chains, append relations, axes — never solved

docs/README.md

@@ -53,8 +53,9 @@ place that says what is implemented.
     skinning, morph layout, and the stage-contract version;
   - [design/PMX_CONTRACT.md](design/PMX_CONTRACT.md) — how PMX 2.0/2.1 bytes are
     read and what each source concept becomes in the canonical model;
-  - [design/MATERIAL_POLICY.md](design/MATERIAL_POLICY.md) — `UsdPreviewSurface`,
-    MaterialX `gltf_pbr`, and the native MMD material semantics;
+  - [design/MATERIAL_POLICY.md](design/MATERIAL_POLICY.md) — `MmdMaterialAPI`,
+    native MMD semantics, `UsdPreviewSurface` / MaterialX fallbacks, and the
+    `mmdImaging` → `hydra-toon` boundary;
   - [design/TEXT_ENCODING_POLICY.md](design/TEXT_ENCODING_POLICY.md) — text
     decoding, source names versus USD identifiers, collisions, texture paths;
   - [design/MOTION_CONTRACT.md](design/MOTION_CONTRACT.md) — the MMD-specific

docs/architecture/DEPENDENCIES.md

@@ -50,7 +50,7 @@ calls the MaterialX library. The MaterialX document version it declares
 | An image decoder in the importer | the importer never reads texture pixels; authoring stays independent of image content and of whether files exist ([TEXT_ENCODING_POLICY.md §7.3](../design/TEXT_ENCODING_POLICY.md#73-no-filesystem-access-while-authoring)) |
 | ICU, `iconv`, OS code-page APIs | PMX text is UTF-8 or UTF-16LE, decoded by the parser; CP932 (for VMD, PMD) uses a table the project owns ([TEXT_ENCODING_POLICY.md §9](../design/TEXT_ENCODING_POLICY.md#9-pmd-and-vmd)) |
 | A third-party PMX parser, by default | PMX is a bounded format; a purpose-built parser avoids inheriting an application's semantics ([DESIGN_POLICY.md §10](../design/DESIGN_POLICY.md#10-parser-strategy)) — adoption is possible only through §4 |
-| OpenExec, Hydra, `hydra-toon`, `usd-stage-runner` | the importer neither evaluates nor renders ([WORKSPACE.md §2.2](WORKSPACE.md#22-forbidden-edges)); `mmdControl` evaluates as a plain library, and a runtime that wants it as an OpenExec node wraps it there |
+| OpenExec, Hydra render delegates, `hydra-toon`, `usd-stage-runner` | the importer neither evaluates nor renders ([WORKSPACE.md §2.2](WORKSPACE.md#22-forbidden-edges)); `mmdImaging` uses only OpenUSD's UsdImaging API, `mmdControl` evaluates as a plain library, and a runtime that wants it as an OpenExec node wraps it there |
 | `motion-connectors`, device SDKs, network transports | live input reaches this repository only as the shared core's types, if at all ([WORKSPACE.md §2.2](WORKSPACE.md#22-forbidden-edges)) |
 | A copy of any `usd-motion-plugins` algorithm | generic motion is consumed, never duplicated ([WORKSPACE.md §7](WORKSPACE.md#7-invariants), invariant 9) |
 

docs/architecture/PACKAGE_CONTRACT.md

@@ -7,7 +7,7 @@ installed-consumer lane
 ([WORKSPACE.md §6](WORKSPACE.md#6-tests)) builds against a clean repository
 prefix plus the explicitly pinned external motion packages to keep it true.
 
-Status (2026-09-21): the two Phase 0 packages exist, `mmd_inspect` installs
+Status (2026-09-22): the two Phase 0 packages exist, `mmd_inspect` installs
 with the workspace since Phase 1, `mmdModel` since Phase 2, `motionVmd`,
 `mmdMotionBinding` and `vmd_inspect` since Phase 7, and `mmdControl`,
 `mmdSkeletonAdapter` and `mmdMotionAdapter` since Phase 9. Identities and
@@ -145,6 +145,22 @@ installed package contract. The installed-consumer lane binds a
 generated VMD to a generated PMX, evaluates it, and builds a shared
 `MotionClip` through both installed adapters.
 
+## Planned Phase 8 plugin packages
+
+These identities are admitted by the design but do not exist in the current
+install. Their exact library filenames and resource layout become binding when
+the first installed-consumer fixture lands:
+
+| Bundle | Discovery | Public responsibility |
+| --- | --- | --- |
+| `mmdSchema` | OpenUSD plug registry and generated C++/Python API | Single-apply `MmdMaterialAPI`, its `mmd:material:*` declarations and tokens; no PMX record mirror |
+| `mmdImaging` | OpenUSD plug registry | UsdImaging adapter from a composed `MmdMaterialAPI` to renderer-consumable Hydra data; no parser, importer or GPU implementation |
+
+The two bundles are separately discoverable: tools that only inspect the
+schema do not load an imaging adapter. `mmdImaging` requires `mmdSchema` and
+the matching OpenUSD UsdImaging runtime. Neither package requires
+`hydra-toon`; the renderer consumes the published imaging contract.
+
 ## `usdMmdFileFormat`
 
 A plugin bundle, found by OpenUSD's plug registry rather than by CMake. It
@@ -161,7 +177,10 @@ relative to itself, and the installed bundle keeps the source bundle's shape.
 
 A host makes the plugin available by putting
 `plugin/resources/usdMmdFileFormat` on `PXR_PLUGINPATH_NAME`, with OpenUSD
-26.08's libraries on the loader path. It needs no other package at run time.
+26.08's libraries on the loader path. The current bundle needs no other package
+at run time. From the Phase 8 migration it will include `mmdSchema` in its
+declared plugin closure so the applied `MmdMaterialAPI` is discoverable;
+it will not depend on `mmdImaging` or `hydra-toon`.
 
 ## `mmd_inspect`
 

docs/architecture/WORKSPACE.md

@@ -70,7 +70,8 @@ created ahead of that.
 | Identity | Kind | Directory | Role | Created when |
 | --- | --- | --- | --- | --- |
 | `mmdMaterial` | plain static CMake library | `libs/mmdMaterial/` | Canonical material semantics, extracted from `mmdModel` | material translation outgrows `mmdModel`, or a second consumer needs it alone ([DESIGN_POLICY.md §5.3](../design/DESIGN_POLICY.md#53-mmdmaterial--deferred)) |
-| `mmdSchema` | plugin bundle (`usd-schema`) | `plugins/mmdSchema/` | Narrow applied API schemas | an API passes the admission test ([DESIGN_POLICY.md §6](../design/DESIGN_POLICY.md#6-the-schema-admission-test)) |
+| `mmdSchema` | plugin bundle (`usd-schema`) | `plugins/mmdSchema/` | `MmdMaterialAPI`; no catch-all PMX schema | Phase 8 material work. The API passed the admission test on 2026-09-22 for the `hydra-toon` consumer ([DESIGN_POLICY.md §6](../design/DESIGN_POLICY.md#6-the-schema-admission-test)) |
+| `mmdImaging` | plugin bundle (`usd-imaging`) | `plugins/mmdImaging/` | Exposes `MmdMaterialAPI` through UsdImaging data; no PMX parsing and no renderer-private GPU representation | Phase 8, after `MmdMaterialAPI` exists ([MATERIAL_POLICY.md §12](../design/MATERIAL_POLICY.md#12-rendering-and-integration-belong-elsewhere)) |
 | `usdVmdFileFormat` | plugin bundle (`usd-fileformat`) | `plugins/usdVmdFileFormat/` | `.vmd` `SdfFileFormat` over `motionVmd` | MOT-O2 is resolved against `usd-motion-plugins`' standalone motion stage (`/Animation`) ([MOTION_CONTRACT.md §9](../design/MOTION_CONTRACT.md#9-open-questions)) |
 | `mmd_convert` | CLI executable | `tools/mmdConvert/` | PMX → `.usda`/`.usdc` on disk | `usdcat` over the file format proves insufficient |
 | `mmdPmd` | plain static CMake library | `libs/mmdPmd/` | PMD syntax with its own CP932 policy | PMD support is decided ([DESIGN_POLICY.md §16](../design/DESIGN_POLICY.md#16-decisions-deliberately-left-flexible)) |
@@ -87,7 +88,7 @@ live in a lower-camel directory.
 mmdPmx ──────────────→ (nothing in this repository; no OpenUSD)
 mmdModel ────────────→ mmdPmx                          (no OpenUSD)
 usdMmdFileFormat ────→ mmdModel, mmdPmx, OpenUSD
-                       mmdSchema                       (only if it exists)
+                       mmdSchema                       (from Phase 8)
 mmd_inspect ─────────→ mmdPmx                          (no OpenUSD)
 motionVmd ───────────→ nothing                         (no OpenUSD)
 mmdMotionBinding ────→ mmdModel, motionVmd             (no OpenUSD)
@@ -97,6 +98,7 @@ mmdControl ──────────→ mmdMotionBinding, mmdModel      (no
                        (later)
 mmdMaterial ─────────→ nothing in this repository; mmdModel → mmdMaterial
 mmdSchema ───────────→ OpenUSD only
+mmdImaging ──────────→ mmdSchema, OpenUSD UsdImaging only
 mmdSkeletonAdapter ──→ mmdModel,
                        usd-motion-plugins motionRetarget (OpenUSD foundation
                                                           types only, through it)
@@ -124,13 +126,14 @@ USD in the process
 | `mmdPmx → OpenUSD` | the parser exposes source facts, not USD policy |
 | `mmdPmx → mmdModel`, `mmdPmx → usdMmdFileFormat` | syntax never knows its consumers |
 | `mmdModel → OpenUSD`, `mmdModel → Hydra` | canonical semantics are renderer- and USD-independent |
+| `mmdImaging → mmdPmx`, `mmdModel`, `usdMmdFileFormat`, `hydra-toon` | the adapter reads the composed `MmdMaterialAPI` contract and publishes imaging data; it neither reparses source data nor owns renderer code |
 | `motionVmd → usdMmdFileFormat`, `motionVmd → mmdModel`, `motionVmd → mmdPmx`, `vmd_inspect → mmdModel`, `vmd_inspect → mmdPmx` | a VMD never needs a model to parse |
 | `mmdModel → motionVmd`, `mmdModel → mmdMotionBinding` | a model never knows the motions bound to it; binding is its own step ([MOTION_CONTRACT.md §8](../design/MOTION_CONTRACT.md#8-binding-a-vmd-to-a-pmx-model)) |
 | `mmdMotionBinding → OpenUSD` | binding produces data a runtime consumes, not a stage |
 | `mmdControl → OpenUSD`, `mmdControl → usd-motion-plugins`, `mmdModel → mmdControl`, `mmdMotionBinding → mmdControl` | evaluation produces MMD-domain transforms; the model and the binding stay data, and normalization is the adapter's alone |
 | `mmdPmx`, `mmdModel`, `motionVmd`, `mmdMotionBinding`, `mmdControl` or `usdMmdFileFormat` `→ usd-motion-plugins` | only the two narrow adapter components cross into the shared motion core (§2.4), so parsing and evaluation remain independent |
 | any component → `motion-connectors`, a device SDK, a network transport | live input is normalized by `motion-connectors` into the shared core, never read here |
-| `usdMmdFileFormat → hydra-toon` | the renderer consumes the stage, never the reverse |
+| `usdMmdFileFormat → hydra-toon` | the renderer consumes `MmdMaterialAPI` through the USD/UsdImaging contract, never the importer or PMX |
 | `usdMmdFileFormat → usd-stage-runner` | the importer has no update loop |
 | parser, canonical model or importer → `usd-physics-plugins` | the static path only preserves physics; only a future MMD runtime adapter may consume the optional shared package ([PHYSICS_INTEGRATION.md §8](../design/PHYSICS_INTEGRATION.md#8-dependency-policy)) |
 | any component → Jolt, PhysX, Bullet or another physics backend | backend ownership is `usd-physics-plugins`'; even the future MMD coupling adapter depends only on the shared contract |