stylegallery 0.1.0 → 0.1.2

package/AGENTS.md

@@ -17,7 +17,10 @@ Before editing generated artifacts, validators, lifecycle state, or ownership po
 - Do not use one domain to bypass another domain's constraints.
 - Treat `consumer-reference/` as shared non-domain schema, provenance, routing, and evidence infrastructure; it owns no profile values, visual defaults, component implementation, or product CSS.
 - Keep dependency direction consumer/profile -> Layout. Do not import consumer-reference records, profile data, tokens, or decorative values into `layout/**`, `patterns/**`, `scripts/pattern-data.mjs`, or `CATALOG.md`.
-- Include the consumer-reference handoff field in implementation handoffs. Use one normalized repository-relative JSON record or `not_applicable` with a sentence reason.
+- Include the consumer-reference handoff field in implementation handoffs. For this repository-wide agent surface use `consumer_reference: consumer-reference/agent-native/registry.json`; otherwise use one normalized repository-relative JSON record or `not_applicable` with a sentence reason.
+- Keep material v2, v1 trust/conformance, CLI/MCP transport, and A2A/AG-UI extension planes separate. Material admission never imports profiles, source code, fixtures, schemas, tests, `.omo`, or visual defaults.
+- Validate canonical evidence v2 against its recorded immutable Git revision. Use current-authoring source checks only when creating or finalizing new capture evidence; do not recapture merely because later repository changes differ.
+- Treat `consumer-reference/policies/lifecycle-dispositions.json` as the lifecycle index. Preserve named owners, caller status `unknown`, deadlines, extension dispositions, and immutable archive bindings until their machine gate authorizes a transition.
 - Treat `patterns/**`, `recipes/**`, `GUIDE.md`, and `CATALOG.md` as the Layout corpus at their existing paths.
 - Treat the Layout domain as a layout pattern library, not a visual design system.
 - Start with semantic HTML before adding layout classes.

package/DOMAINS.md

@@ -32,7 +32,7 @@ This manifest is the source of truth for top-level StyleGallery domains. A domai
 
 ## Shared Non-Domain Infrastructure
 
-[Consumer Reference](consumer-reference/index.md) is shared schema, provenance, routing, and evidence infrastructure outside the five-domain contract. It owns no profile implementation or visual values and cannot add a sixth domain row. Consumer or profile records may depend on Layout; Layout and its generated corpus cannot import those records.
+[Consumer Reference](consumer-reference/index.md) is shared schema, provenance, routing, evidence, lifecycle, and machine-retrieval infrastructure outside the five-domain contract. Its source-bound material v2 index classifies admitted pages by these five domains but does not own their prose. It owns no profile implementation, visual values, or product CSS and cannot add a sixth domain row. Consumer or profile records may depend on Layout; Layout and its generated corpus cannot import consumer-reference, profile, material-registry, or transport records.
 
 ## External Adaptation Contract
 
@@ -53,11 +53,7 @@ External adaptations begin `experimental`. Promotion to `stable` requires a demo
 
 ### Consumer Reference Promotion
 
-Consumer-reference promotion does not add a domain. The StyleGallery-local `>=2` independent-consumer gateway applies only to consumer-local → shared-experimental invariant eligibility. Editorial and terminal are related examples in one fixture set, so neither counts as an independent consumer. Shared stable has no numeric adoption threshold.
-
-Normative correctness may waive adoption count only; regression evidence, invariant scope, owner and support capacity, compatibility, migration, deprecation, rollback, and provenance duties remain required. A failed stable contract is restricted, maintained, rolled back, or deprecated with migration, never silently relabeled experimental. Promotion records are JSON-only; the committed examples are synthetic, `example_only`, deferred, and contain zero adopter attestations.
-
-Consumer-reference maturity is governed independently from artifact mode. Stable records cannot have ended support, and related repository fixtures are not independent adoption evidence.
+Consumer-reference promotion does not add a domain. The [canonical promotion contract](consumer-reference/contract.md#promotion-boundary) owns the full human-readable boundary, and the [canonical JSON promotion policy](consumer-reference/policies/shared-experimental.json) owns machine policy. As a boundary summary: the `>=2` gateway applies only to consumer-local → shared-experimental invariant eligibility; Editorial and terminal are related examples in one fixture set; Shared stable has no numeric adoption threshold; and Normative correctness may waive adoption count only. A failed stable contract is never silently relabeled experimental. Promotion records are JSON-only, and the committed examples remain synthetic with zero adopter attestations.
 
 ## IA Navigation
 

package/GOVERNANCE.md

@@ -23,7 +23,10 @@ Use this file before editing repository documentation. It names which file is au
 | Layout recipes | `recipes/*.md` | Manual | None | `stable` | Pattern-stack changes, route changes, or broken recipe links. | `scripts/validate-okf.mjs`, `scripts/validate-links.mjs`, `scripts/validate-ia.mjs` | Recipe owner |
 | Quality gates and evidence | `quality/**/*.md` | Manual | None | `stable` | Claim-boundary changes, evidence-family changes, or broken quality links. | `scripts/validate-okf.mjs`, `scripts/validate-links.mjs`, `scripts/validate-ia.mjs` | Quality owner |
 | Consumer reference contract | `consumer-reference/contract.md`, `consumer-reference/schema/item.schema.json` | Manual | None | `stable` contract with related fixtures | Handoff shape, path boundary, lifecycle, ownership, or dependency-direction changes. | `scripts/validate-consumer-reference.mjs`, `scripts/test-validate-consumer-reference.mjs` | Repository governance owner with Validation owner |
-| Agent-native knowledge interface | `consumer-reference/agent-native/registry.json`, `consumer-reference/agent-native/schema/*.json`, `scripts/agent-native/*.mjs`, `scripts/sg.mjs`, `scripts/sg-mcp.mjs` | Manual, with protocol projections derived from one operation registry | CLI JSON, read-only MCP tools/resources, A2A Task projections, and AG-UI event projections | `experimental` interface over governed records | Identity grammar, canonical hashing, registry records, operation metadata, capability/effect semantics, receipt/conformance rules, protocol mapping, retrieval, or learning-promotion rules change. | `npm run test:agent-native`, syntax checks in `.github/workflows/validate.yml` | Repository governance owner with Validation owner |
+| Agent-native knowledge interface v1 | `consumer-reference/agent-native/registry.json`, `consumer-reference/agent-native/schema/*.json`, `scripts/agent-native/{registry,identity,queries}.mjs`, `scripts/sg.mjs`, `scripts/sg-mcp.mjs` | Manual, with protocol projections derived from one operation registry | Frozen v1 CLI JSON, read-only MCP tools/resources, and compatibility projections | `experimental`, byte-compatible v1 interface | Identity grammar, canonical hashing, registry records, operation metadata, capability/effect semantics, receipt/conformance rules, or retrieval changes. | `npm run test:agent-native` | Repository governance owner with Validation owner |
+| Governed material interface v2 | `consumer-reference/agent-native/v2/admission-policy.json`, its closed schemas, and admitted tracked Markdown | `scripts/agent-native/v2/generate-material-registry.mjs` | `consumer-reference/agent-native/v2/material-registry.json`; separate `sg-material` CLI and material MCP | `experimental`, read-only and isolated from v1 | Admission roots/exclusions, source hash, identity, operation inventory, query/context bounds, package exposure, or source drift changes. | `npm run validate:material`, `npm run test:material`, generated drift | Repository governance owner with Validation owner |
+| Experimental protocol extensions | `scripts/agent-native/v2/experimental-extension-registry.mjs`, `scripts/agent-native/v2/extensions/*.mjs`, lifecycle extension records | Manual | A2A `1.0` and AG-UI `0.0.57` projections | `experimental`, retained pending owner review | Protocol version, caller inventory, forwarding, migration evidence, or disposition changes. | `scripts/agent-native/v2/test-agent-extension-boundary.mjs`, lifecycle suites | Repository governance owner with protocol and Validation owners |
+| Lifecycle dispositions and archives | `consumer-reference/policies/lifecycle-dispositions.json`, its five records, and `consumer-reference/schema/lifecycle-disposition.schema.json` | Manual, with immutable archive receipts | Retrieval metadata for historical sentinel/calibration and page evidence | `pending_owner` for three families; both extensions `retain` | Owner, deadline, caller status, archive object/ref, approval, transition, or post-deadline action changes. | `npm run validate:lifecycle-dispositions`, `npm run test:lifecycle-dispositions` | Repository governance owner with named family owner and Validation owner |
 | Portable token source | `consumer-reference/fixtures/token-portability/valid-reference.json`, `consumer-reference/schema/portable-tokens.schema.json` | `scripts/build-reference-artifacts.mjs` with Style Dictionary `5.5.0` | `consumer-reference/generated/tokens.css`, `consumer-reference/generated/manifest.json` | `stable` restricted adapter contract, `generated` output | Allowed token shape, adapter/version pin, source token count, warning, declaration, or content hash changes. | `scripts/validate-reference-artifacts.mjs`, `scripts/test-reference-adapters.mjs` | Repository governance owner with Validation owner |
 | Governed local reference profiles | `design-engineering/reference-profiles/governed-local/editorial/profile.json`, `design-engineering/reference-profiles/governed-local/editorial/tokens.dtcg.json`, `design-engineering/reference-profiles/governed-local/editorial/local-foundations.json`, `design-engineering/reference-profiles/governed-local/terminal/profile.json`, `design-engineering/reference-profiles/governed-local/terminal/tokens.dtcg.json`, `design-engineering/reference-profiles/governed-local/terminal/local-foundations.json` | Manual | None | `experimental`, `example_only`, non-default related fixtures | Layout revision, identity values, UA/reset assumptions, explicit selection, or fixture relationship changes. | `scripts/validate-consumer-reference.mjs`, `scripts/test-validate-consumer-reference.mjs` | Design Engineering owner with Validation owner |
 | Component-state evidence matrices | Each profile's declared `components/*.component.json`, `states/*.states.json`, `fixtures/*.fixture.json`, and `evidence/*.evidence.json` records | `scripts/generate-consumer-reference-evidence.mjs` | `design-engineering/reference-profiles/governed-local/editorial/generated/state-matrix.md`, `design-engineering/reference-profiles/governed-local/editorial/generated/keyboard-matrix.md`, `design-engineering/reference-profiles/governed-local/editorial/generated/evidence-coverage.md`, `design-engineering/reference-profiles/governed-local/terminal/generated/state-matrix.md`, `design-engineering/reference-profiles/governed-local/terminal/generated/keyboard-matrix.md`, `design-engineering/reference-profiles/governed-local/terminal/generated/evidence-coverage.md` | `generated` output from `experimental` canonical records | Declared record paths, capture-session identity, scenario/mode/channel counts, claim boundary, generated escaping, or generator output changes. | `scripts/validate-component-state.mjs`, `scripts/test-validate-component-state.mjs`, `scripts/test-validate-component-state-artifacts.mjs`, `scripts/test-generate-consumer-reference-evidence.mjs` | Design Engineering owner with Validation owner |
@@ -74,7 +77,11 @@ Portable token artifacts are regenerated only from the restricted fixture throug
 
 Component-state evidence matrices are regenerated only from the records declared by each `profile.json`. Run `node scripts/generate-consumer-reference-evidence.mjs --json`; never hand-edit any of the six matrices or substitute undeclared record paths.
 
-Browser state evidence begins with `scripts/create-component-state-session.mjs`. Its closed receipt binds a random nonce and session ID to the checked-out revision, branch, attempt, exact runtime pins, viewport, intended profile/scenario/channel set, and a deterministic digest of the relevant capture sources before capture. Receipt creation rejects dirty relevant sources. DOM and AX artifacts embed the receipt digest and session identity; browser-authored visual sidecars bind the same session, scenario, capture time, source digest, PNG bytes, dimensions, and hash. Finalization accepts exactly 30 channel passes over the closed 40-file runtime set. Validation uses the receipt and completed manifest interval, not a wall-clock maximum age, so an unchanged downloaded session remains verifiable later.
+Browser state evidence begins with `scripts/create-component-state-session.mjs`. Its closed receipt binds a random nonce and session ID to the checked-out revision, branch, attempt, exact runtime pins, viewport, intended profile/scenario/channel set, and a deterministic digest of the relevant capture sources before capture. Receipt creation rejects dirty relevant sources. This is the current-authoring mode. Canonical evidence v2 stores environment, run, and session identity once in a shared content-addressed capture record; both profile records reference it and v1 readers remain available. Historical validation uses recorded-revision mode: it resolves commit, tree, and blob objects from the receipt's immutable revision and never trusts the working tree or index. DOM and AX artifacts embed the receipt digest and session identity; browser-authored visual sidecars bind the same session, scenario, capture time, source digest, PNG bytes, dimensions, and hash. Finalization accepts exactly 30 channel passes over the closed 40-file runtime set. Validation uses the receipt and completed manifest interval, not a wall-clock maximum age, so unchanged historical evidence remains verifiable after repository evolution.
+
+The agent-native implementation has four separate planes: governed Markdown material v2; v1 trust/conformance records; CLI/MCP transport adapters; and explicitly registered A2A/AG-UI extensions. Material retrieval cannot merge trust records, transports cannot expand admission, and extensions cannot alter either registry. Consumer/profile -> Layout remains the only dependency direction; no material registry value is a visual default or reusable Layout input.
+
+Lifecycle decisions are machine records, not inferred from deadlines. Sentinel/calibration and page evidence remain active pending their named owner deadlines; protocol-owner review retains archives; A2A and AG-UI remain retained extensions with external callers `unknown`. Archive retrieval must use each record's immutable repository/commit/tree/ref binding and pass `scripts/validate-lifecycle-disposition.mjs`; never copy historical evidence into current canonical records or treat archive presence as approval.
 
 ## Lifecycle States
 
@@ -122,13 +129,7 @@ Consumer-reference ownership records the current truth as `owner.enforcement: "p
 
 ## Shared Promotion Governance
 
-The StyleGallery-local `>=2` independent-consumer gateway applies only to consumer-local → shared-experimental invariant eligibility. It is neither a universal rule nor a stable threshold. Shared stable has no numeric adoption threshold; it requires claim-scoped evidence, active owner and support capacity, compatibility review, known-issue and exception visibility, migration and deprecation readiness, rollback triggers, resolved provenance debt, and an explicit scope decision.
-
-Normative accessibility, security, standards, or correctness fixes may waive adoption count only. They never waive regression proof, scope control, owner acceptance, support capacity, compatibility, migration, deprecation, or rollback. Palette, typography, imagery, motion character, and component skin remain consumer-local even when repeated.
-
-The committed RFC fixtures are synthetic `example_only` proposals with `decision: "deferred"`; they contain zero durable adopter attestations and record no promotion. Editorial and terminal remain related fixtures in one set and never count as independent consumers. Current review truth remains `review_independence: "single_account"`; booleans and multiple role labels do not create independent review.
-
-If evidence fails, restrict, maintain, or roll back the candidate. A consumed stable contract may be deprecated only with a named migration; it must never be silently relabeled shared-experimental. The canonical JSON policy and RFC records own these decisions; no YAML promotion record is valid.
+Promotion semantics are owned by the [canonical promotion contract](consumer-reference/contract.md#promotion-boundary) and the [canonical JSON promotion policy](consumer-reference/policies/shared-experimental.json). This document records only the repository ownership, review, and verification boundary.
 
 ## Staleness Control
 

package/README.md

@@ -6,6 +6,10 @@ description: Governed gallery of portable interface knowledge organized by domai
 
 # StyleGallery
 
+<p align="center">
+  <img src="https://cdn.jsdelivr.net/gh/changeroa/StyleGallery@c18bc87/assets/stylegallery-hero-infographic.webp" alt="StyleGallery infographic connecting five governed interface-knowledge domains to shared consumer and agent infrastructure" width="100%">
+</p>
+
 StyleGallery is a governed gallery of portable interface knowledge. It separates reusable spatial patterns, product-layer motion guidance, design-engineering practice, and platform-specific references into explicit domains with different evidence and ownership boundaries.
 
 Primary role: repository guide.
@@ -14,7 +18,7 @@ The existing Layout corpus remains a gallery of minimal, portable CSS layout pat
 
 [Consumer Reference](consumer-reference/index.md) is shared non-domain infrastructure for optional consumer-owned reference handoffs. It carries schema, routing, provenance, and evidence metadata without owning profiles, visual values, components, or a sixth domain.
 
-[Agent-Native StyleGallery](consumer-reference/agent-native/README.md) is the machine-facing entry point over that governed knowledge. It provides content-addressed identity, claim/evidence/governance records, deterministic retrieval, a shared operation registry, the `sg` CLI, and a read-only MCP projection. It does not create a sixth domain, replace the Markdown corpus, or permit MCP clients to mutate governed knowledge.
+[Agent-Native StyleGallery](consumer-reference/agent-native/README.md) is the machine-facing entry point over that governed knowledge. Frozen v1 provides claim/evidence/governance records through `sg` and its MCP; isolated material v2 indexes admitted Markdown and exposes `sg-material` plus a separate read-only MCP. Lifecycle records own extension and archive dispositions. These material, trust/conformance, transport, and extension planes do not create a sixth domain, replace the Markdown corpus, permit mutation, or feed visual defaults back into Layout.
 
 ## Quick Start
 
@@ -31,6 +35,8 @@ npm install --global stylegallery
 sg discover --format json
 ```
 
+The npm package includes the pinned `@chenglou/pretext@0.0.8` browser text-layout engine. StyleGallery uses it as a measurement and verification dependency for text-fit QA; the Node CLI and MCP servers do not execute browser Canvas APIs.
+
 Common read-only commands:
 
 ```sh
@@ -42,6 +48,18 @@ sg ops --format json
 
 Every command writes deterministic JSON to stdout. Invalid input returns an error object and a nonzero exit status. See [Agent-Native StyleGallery](consumer-reference/agent-native/README.md) for the command contract, StableRef and VersionID model, MCP resources, and trust boundaries.
 
+Material v2 searches the admitted Markdown corpus and returns JSON without an additional format flag:
+
+```sh
+sg-material discover
+sg-material search --query "sticky layout" --limit 5
+sg-material context --query "responsive sidebar" --budget-tokens 4096
+```
+
+### Worked homepage example
+
+The [StyleGallery homepage example](examples/stylegallery-homepage/README.md) was planned from a clean install of the published npm package. It demonstrates the Homepage recipe, selected layout patterns, agent-native CLI access, responsive behavior, and Chrome CDP verification in a standalone product-layer implementation.
+
 ### Read-only MCP server
 
 Launch the packaged stdio server with:
@@ -65,6 +83,8 @@ Example MCP client configuration:
 
 The MCP surface exposes governed read operations only. It cannot modify repository knowledge.
 
+The separate Material v2 MCP server is available as `stylegallery-material-mcp`.
+
 ## 한국어 빠른 시작
 
 StyleGallery는 Node.js 22 이상에서 실행됩니다. 전역 설치 없이 바로 사용하려면 다음 명령을 실행하세요.
@@ -80,7 +100,7 @@ npm install --global stylegallery
 sg discover --format json
 ```
 
-`discover`는 사용 가능한 인터페이스를 보여주고, `resolve`는 하나의 레코드를 조회하며, `claims`는 관련 주장과 근거를 분리해서 보여줍니다. `context`는 에이전트에 전달할 수 있는 제한된 컨텍스트 패키지를 만들고, `ops`는 지원하는 작업 목록을 반환합니다. 모든 결과는 자동화에 바로 사용할 수 있는 JSON입니다.
+`discover`는 사용 가능한 인터페이스를 보여주고, `resolve`는 하나의 레코드를 조회하며, `claims`는 관련 주장과 근거를 분리해서 보여줍니다. `context`는 에이전트에 전달할 수 있는 제한된 컨텍스트 패키지를 만들고, `ops`는 지원하는 작업 목록을 반환합니다. `sg-material search --query "검색어"`를 사용하면 Material v2에 등록된 Markdown 문서를 검색할 수 있습니다. 모든 결과는 자동화에 바로 사용할 수 있는 JSON입니다.
 
 CLI와 MCP의 상세 사용법은 [Agent-Native StyleGallery 가이드](consumer-reference/agent-native/README.md)를 참고하세요. 사람이 문서를 탐색하려면 아래의 도메인 표에서 목적에 맞는 진입점을 선택하면 됩니다.
 
@@ -141,7 +161,7 @@ Each common task has one primary route. Use secondary links only after the prima
 | `check whether a layout or design claim is admissible` | [Quality Gates](quality/index.md) | It routes claims to gates and evidence boundaries. |
 | `prove repository checks and evidence coverage` | [Executable Evidence Coverage](quality/evidence/executable-evidence.md) | It maps validators, fixtures, CI commands, and their boundaries. |
 | `declare consumer reference applicability` | [Consumer Reference](consumer-reference/index.md) | It provides the required handoff field without moving consumer values into Layout. |
-| `use StyleGallery from an agent or automation` | [Agent-Native StyleGallery](consumer-reference/agent-native/README.md) | It explains StableRef resolution, CLI commands, read-only MCP resources/tools, receipts, and mutation boundaries. |
+| `use StyleGallery from an agent or automation` | [Agent-Native StyleGallery](consumer-reference/agent-native/README.md) | It routes frozen v1 trust queries, material v2 discovery/search/get/context, both read-only MCPs, extensions, lifecycle dispositions, and archive boundaries. |
 | `prove an existing consumer migration` | [Consumer Migration Readiness](design-engineering/consumer-migration-readiness.md) | It requires thirteen explicit behavior classifications, runtime proof, adoption mappings, and source-bound page evidence when applicable. |
 | `change generated patterns, catalog, or governance policy` | [Governance, Lifecycle, And Docs-As-Code](GOVERNANCE.md) | It identifies source files, generated artifacts, validators, lifecycle state, and review ownership. |
 | `run findability QA` | [Tree-Test Findability QA](quality/index.md#tree-test-findability-qa) | It tests whether task routes are discoverable, not just linked. |
@@ -172,142 +192,24 @@ Each common task has one primary route. Use secondary links only after the prima
 
 ## Layout Domain Principles
 
-1. Layout problems only
-   - Patterns exist to solve spatial problems, not to define a visual brand.
-   - Core CSS should stay focused on layout responsibilities.
-
-2. Semantic structure first
-   - Start with meaningful HTML before adding layout classes.
-   - Class names explain layout responsibility, but they do not replace landmarks, headings, lists, buttons, links, or form controls.
-   - DOM order, reading order, and focus order should remain logical.
-
-3. One primary spatial problem
-   - Each pattern should optimize one primary spatial problem.
-   - Secondary behavior is allowed when it is incidental or required for composition.
-   - If a pattern has multiple primary problems, split it into smaller primitives or mark it as a shell/composite.
-
-4. Minimum robust CSS
-   - Use the smallest set of declarations that keeps the pattern stable under real content and container constraints.
-   - Minimal does not mean fragile; constraints, overflow rules, intrinsic sizing, and fallbacks are valid when they carry declared responsibility.
-
-5. Portable plain HTML/CSS
-   - Plain HTML and CSS are the source of truth.
-   - Framework-specific versions are optional derivatives, not canonical patterns.
-
-6. Explicit constraints and change points
-   - Widths, heights, gaps, breakpoints, scroll containers, fixed/sticky anchors, and other constraints should be easy to find.
-   - Values users are expected to tune should be surfaced clearly.
-
-7. Named scroll ownership
-   - If a pattern scrolls, the scrolling element must be obvious.
-   - The pattern should make clear what scrolls, what stays fixed, and where height is determined.
-
-8. No decorative debt
-   - Decorative styling does not belong in reusable pattern CSS unless it is required to explain layout behavior.
-   - Demo-only visual aids should be separate from the reusable pattern.
+Layout patterns solve one primary spatial problem with semantic structure, robust plain HTML/CSS, explicit constraints, named scroll ownership, and no decorative debt. The detailed principles live in the [Layout domain contract](layout/index.md#layout-domain-principles).
 
 ## CSS Authoring Policy
 
-- Prefer low-specificity, single-class selectors.
-- Avoid ID selectors for styling or layout naming.
-- Avoid deep combinators, selector chaining, and nesting unless the pattern is specifically demonstrating that tradeoff.
-- Use cascade layers when the CSS surface grows beyond isolated snippets.
-- Keep CSS declarations in alphabetical order inside each rule.
-- Prefer intrinsic sizing and content/container-driven adaptation.
-- Use viewport breakpoints only when the spatial problem is viewport-level.
-- Prefer container queries for component-local responsiveness.
-- Prefer logical properties for spacing and sizing unless physical direction is required.
-- Treat exceptions as explicit and local; use state hooks or `data-*` attributes for variants instead of escalating selector specificity.
+Reusable Layout CSS favors low specificity, intrinsic sizing, logical properties, and responsiveness at the correct container or viewport boundary. See the [detailed CSS authoring policy](layout/index.md#css-authoring-policy).
 
 ## Class Naming Policy
 
-Class names should read like a map of the layout structure.
-
-- Name layout responsibility, not appearance.
-- Make root-child, parent-child, area-element, and fixed-scroll relationships obvious.
-- Prefer pattern-scoped names for related nodes.
-- Avoid vague names like `container`, `wrapper`, `box`, `top`, `content`, and `bottom` unless the surrounding pattern name makes their responsibility unambiguous.
-- Avoid DOM-depth names such as `card_header_title_icon`; describe stable roles instead.
-- Do not use IDs for layout naming. IDs are reserved for JavaScript hooks or document-level targets when needed.
-
-Prefer:
-
-```html
-<div class="app_shell">
-    <header class="app_shell_header"></header>
-    <main class="app_shell_scroll_area"></main>
-    <footer class="app_shell_footer"></footer>
-</div>
-```
-
-Avoid:
-
-```html
-<div class="container">
-    <div class="top"></div>
-    <div class="content"></div>
-    <div class="bottom"></div>
-</div>
-```
+Layout class names describe stable spatial responsibilities and relationships rather than appearance or DOM depth. See the [detailed class naming policy](layout/index.md#class-naming-policy).
 
 ## Value And Token Policy
 
-- Tokenize reusable design intent, not every layout number.
-- Use tokens for stable, shared values such as `content-width`, `gutter`, `stack-gap`, `section-gap`, or density steps.
-- Keep browser/context mechanics in raw CSS: `auto`, percentages, `min-content`, `max-content`, `fit-content`, `clamp()`, viewport units, container-query units, and intrinsic sizing.
-- Put tokens behind logical CSS, for example `padding-block: var(--space-4)`.
-- Use breakpoint names for layout states, not device names.
+Tokens represent stable shared design intent; browser and context mechanics remain explicit CSS values. See the [detailed value and token policy](layout/index.md#value-and-token-policy).
 
 ## Pattern Contract
 
-Use this shape when adding a new pattern:
-
-```txt
-Pattern name
-Category
-Primary spatial problem
-Secondary spatial problems
-When to use
-HTML structure
-CSS
-Core properties
-Properties that break the layout if removed
-Constraints and change points
-Scroll ownership
-Accessibility and source-order notes
-Browser/fallback notes
-Composition notes
-Anti-patterns
-```
-
-Suggested categories:
-
-- Containment
-- Centering
-- Stacking
-- In-line grouping
-- Split / Sidebar
-- Grid / Repetition
-- Viewport / Shell
-- Overlay / Exception
-- Media / Fit
-- Reveal / Density control
+Every pattern documents its primary problem, structure, constraints, scroll ownership, accessibility, fallbacks, composition, and failure boundaries. See the [detailed pattern contract](layout/index.md#pattern-contract), and use the generated [Pattern Categories](patterns/index.md) as the category inventory.
 
 ## Verification Matrix
 
-Before accepting a pattern, verify the smallest relevant matrix:
-
-- Viewports: `320px`, `375px`, `768px`, `1024px`, `1440px`
-- Containers: tight, medium, roomy, and `100%` parent
-- Content: empty, short, long label, long paragraph, unbroken string
-- Direction: `ltr` and `rtl`
-- Writing mode: default, plus vertical writing mode if the pattern claims support
-- Interaction: default, hover, focus, active, expanded, scroll top/middle/bottom when relevant
-
-Acceptance checks:
-
-- The layout reflows without unusable two-dimensional scrolling.
-- Long and empty content do not break alignment or hide essential content.
-- Focus order remains logical and visible.
-- Scrollable regions and sticky elements behave as declared.
-- Screenshot diffs are reviewed when the pattern has visual fixtures.
+Pattern verification covers the relevant viewport, container, content, direction, writing-mode, interaction, overflow, focus, and sticky/scroll cases. See the [detailed verification matrix](layout/index.md#verification-matrix).