docs: canonicalize generator and validation docs

API.md

@@ -10,6 +10,16 @@ In an interactive terminal, running bare `interfacectl` with no arguments opens
 
 `interfacectl validate` is the canonical command for contract compliance. Use it to gate changes before merge or deployment. For deterministic, category-based exit codes, use `--exit-codes v2` or set `INTERFACECTL_EXIT_CODES=v2`. The command `enforce --mode fail` runs a structural diff and applies a policy threshold. It is optional and useful when you want to block on diff severity separately from compliance. For the minimal contract format and where contract semantics live in the repo, see [docs/contract-baseline.md](docs/contract-baseline.md). For optional generator-facing authoring metadata, see [docs/authoring-contracts.md](docs/authoring-contracts.md).
 
+Canonical docs for adjacent validation and generation workflows:
+
+- [docs/contract-validation.md](docs/contract-validation.md)
+- [docs/runtime-edge.md](docs/runtime-edge.md)
+- [docs/ai-generator-adapter-quickstart.md](docs/ai-generator-adapter-quickstart.md)
+- [docs/ai-generator-adapter-api.md](docs/ai-generator-adapter-api.md)
+- [docs/ai-tool-playbooks.md](docs/ai-tool-playbooks.md)
+- [docs/generator-consumption.md](docs/generator-consumption.md)
+- [docs/shell-boundary.md](docs/shell-boundary.md)
+
 ## Commands
 
 ### `init`

README.md

@@ -61,6 +61,19 @@ interfacectl init --url https://app.example.com --surface customer-app --auth-pr
 
 `interfacectl` replays the saved browser session in Chromium, analyzes the rendered authenticated page, and keeps auth state out of generated artifacts.
 
+## Canonical docs
+
+Reusable platform semantics live in `interfacectl`:
+
+- [API reference](API.md)
+- [Contract validation reference](docs/contract-validation.md)
+- [Runtime (edge) enforcement guide](docs/runtime-edge.md)
+- [AI Generator Adapter Quick Start](docs/ai-generator-adapter-quickstart.md)
+- [AI Generator Adapter API](docs/ai-generator-adapter-api.md)
+- [AI Tool Playbooks](docs/ai-tool-playbooks.md)
+- [Generator-Aware Contract Consumption](docs/generator-consumption.md)
+- [Shell Boundary Semantics](docs/shell-boundary.md)
+
 ## Commands Overview
 
 The CLI provides two first-run commands, browser-session auth helpers, and the validation and enforcement commands:

docs/ai-generator-adapter-api.md

@@ -0,0 +1,130 @@
+# AI Generator Adapter API
+
+This page defines the canonical request/response semantics for generator adapters built around `interfacectl` validation.
+
+Consumer repos may materialize this contract as JSON Schema, typed interfaces, CLI wrappers, or HTTP endpoints, but they should not change the meaning of the fields or the `pass|warn|block` verdict model.
+
+## Request contract
+
+```json
+{
+  "requestId": "uuid",
+  "tool": "codex|cursor|lovable|figma-make",
+  "surfaceId": "reference-target-web",
+  "mode": "workspace|descriptor",
+  "workspaceRoot": "/absolute/path/optional",
+  "descriptor": [
+    {
+      "surfaceId": "reference-target-web",
+      "primitives": [],
+      "colors": [],
+      "icons": [{ "value": "@heroicons/react/24/outline", "source": "generated.tsx" }]
+    }
+  ],
+  "contractPath": "/absolute/path/optional",
+  "provenance": {
+    "sessionId": "string",
+    "userId": "string",
+    "timestamp": "ISO-8601"
+  }
+}
+```
+
+Field notes:
+
+- `requestId` is caller-supplied when available and otherwise may be generated by the consumer.
+- `tool` identifies the caller for provenance and debugging; it does not change policy meaning.
+- `surfaceId` selects the governed surface within the target contract.
+- `mode=workspace` requires `workspaceRoot`.
+- `mode=descriptor` requires `descriptor`.
+- `contractPath` is an optional consumer override for contract resolution.
+- `provenance` is optional but recommended for auditability.
+
+Descriptor entries commonly include:
+
+- `primitives`: emitted shell/surface roles with counts and sources
+- `colors`: observed generated color values and sources
+- `icons`: observed icon import sources and sources
+- additional additive fields supplied by the consumer's extraction pipeline
+
+## Response contract
+
+```json
+{
+  "requestId": "uuid",
+  "status": "pass|warn|block",
+  "surfaceId": "reference-target-web",
+  "contract": {
+    "id": "surfaces.web",
+    "version": "0.1.0"
+  },
+  "coverage": {
+    "generationGuard": true,
+    "fullValidate": true,
+    "shellBoundaryEvaluated": true,
+    "colorPolicyEvaluated": true,
+    "iconPolicyEvaluated": true
+  },
+  "findings": [
+    {
+      "code": "color.disallowed|icon.source-disallowed|shell-owned-primitive-emitted|...",
+      "severity": "error|warning",
+      "policy": "strict|warn|off",
+      "message": "human-readable",
+      "location": {
+        "file": "path",
+        "line": 0
+      },
+      "evidence": {}
+    }
+  ],
+  "timings": {
+    "totalMs": 0
+  },
+  "provenance": {
+    "sessionId": "string",
+    "userId": "string",
+    "timestamp": "ISO-8601",
+    "evaluatedAt": "ISO-8601"
+  }
+}
+```
+
+Field notes:
+
+- `status` is the canonical verdict.
+- `coverage.generationGuard` is `true` when generation-time guard checks ran.
+- `coverage.fullValidate` is `true` only when a full validation pass ran.
+- Category-specific coverage flags state whether that policy area was actually evaluated for this request.
+- `findings` carry the structured remediation payload that tools should feed back into generation.
+- `timings` and `provenance` are additive operational metadata.
+
+## Status semantics
+
+- `block`: at least one strict/error finding exists.
+- `warn`: findings exist, but none are blocking.
+- `pass`: no findings exist.
+
+Consumers must preserve these semantics even if they map the result onto repo-local HTTP status codes, CLI exit codes, or in-product publish gates.
+
+## Transport guidance
+
+This contract is transport-agnostic.
+
+- CLI wrappers may emit JSON and map `block` to a non-zero exit code.
+- HTTP wrappers may map `block` to `422` or another non-success status.
+- Editor or MCP wrappers may return the payload directly.
+
+Transport choices are local. Verdict and finding meaning are canonical.
+
+## Versioning policy
+
+- Additive fields are backward compatible.
+- Breaking request/response changes require coordinated updates across canonical docs and consumer wrappers.
+- Consumers may add transport metadata, but they should not rename or reinterpret the canonical verdict fields.
+
+## Related docs
+
+- [AI Generator Adapter Quick Start](./ai-generator-adapter-quickstart.md)
+- [AI Tool Playbooks](./ai-tool-playbooks.md)
+- [Generator-Aware Contract Consumption](./generator-consumption.md)

docs/ai-generator-adapter-quickstart.md

@@ -0,0 +1,68 @@
+# AI Generator Adapter Quick Start
+
+Use this flow when a generator authors or modifies UI and you want immediate contract feedback at `Generation time`.
+
+## Purpose
+
+The generator adapter loop gives tools a stable verdict contract:
+
+- `pass`
+- `warn`
+- `block`
+
+The adapter is not a separate policy system. It translates generator output into the same contract-aware feedback loop that `interfacectl validate` uses for authoritative compliance checks.
+
+## Integration flow
+
+1. Load the target contract and surface id.
+2. Choose execution mode:
+   - `descriptor` for hosted builders or tools without a full checkout
+   - `workspace` for local agents or CI jobs with a checkout
+3. Convert generated output into a descriptor or point the adapter at the workspace.
+4. Run generation guard checks so shell-boundary violations and other generation-time findings surface immediately.
+5. In `workspace` mode, run full `interfacectl validate` and treat that result as the authoritative promotion gate.
+6. Feed structured findings back into the generator and regenerate until the result is `pass` or an accepted `warn`.
+
+## Mode guidance
+
+### `descriptor`
+
+Use `descriptor` mode for tools such as Lovable, Figma Make, or other hosted builders that do not operate inside a repo checkout.
+
+- Always evaluate shell-boundary signals.
+- Evaluate any additional parity checks that the consumer repo enables for descriptor-mode rollout.
+- Never treat descriptor-only success as the final shipping gate.
+
+### `workspace`
+
+Use `workspace` mode for tools such as Codex, Cursor, Claude Code, or any local generator that can inspect the real repo state.
+
+- Run generation guard checks first for fast feedback.
+- Run full `interfacectl validate` before promotion or merge.
+- Prefer deterministic exit-code modes in CI so generated changes can be blocked cleanly.
+
+## Adapter outputs
+
+Every adapter wrapper should return:
+
+- `requestId`
+- `status`
+- `findings`
+- `coverage`
+- `contract` metadata
+- `timings`
+- `provenance`
+
+See [AI Generator Adapter API](./ai-generator-adapter-api.md) for the canonical request/response contract.
+
+## Consumer wiring
+
+Consumer repos may expose the adapter through wrapper commands, HTTP endpoints, editor tasks, or MCP tools. Those entrypoints are repo-local concerns. They should preserve the canonical verdict semantics documented here and in the adapter API.
+
+## Related docs
+
+- [AI Generator Adapter API](./ai-generator-adapter-api.md)
+- [AI Tool Playbooks](./ai-tool-playbooks.md)
+- [Generator-Aware Contract Consumption](./generator-consumption.md)
+- [Shell Boundary Semantics](./shell-boundary.md)
+- [Generation Boundaries Guide](./generation-boundaries.md)

docs/ai-tool-playbooks.md

@@ -0,0 +1,75 @@
+# AI Tool Playbooks
+
+This page shows how generators should use the same contract and verdict loop across local agents, IDE coders, hosted builders, and template engines.
+
+## Shared model
+
+All tools should follow the same pattern:
+
+1. Load the target contract and surface id before generation.
+2. Constrain generation with the contract instead of treating validation as a post-hoc lint step.
+3. Validate generated output through an adapter or a workspace validation flow.
+4. Feed structured findings back into the generator context and regenerate when needed.
+5. Keep `interfacectl validate` as the final CI/CD gate.
+
+The transport can change. The contract semantics do not.
+
+## Agentic coders
+
+Examples: Codex, Cursor, Claude Code, repo-local codegen workflows.
+
+Recommended flow:
+
+1. Read the contract and identify the target surface.
+2. Generate directly in the repo or a checked-out workspace.
+3. Run `workspace` mode or `interfacectl validate`.
+4. Treat `block` as a hard stop.
+5. Feed findings back into the next generation attempt.
+
+These tools benefit most from the full workspace path because they can validate against the actual repo state before code lands.
+
+## Hosted builders
+
+Examples: Lovable, Figma Make, or other tools that produce UI outside the repo.
+
+Recommended flow:
+
+1. Map generated output into a descriptor.
+2. Submit the descriptor to an adapter wrapper.
+3. Surface the returned findings in-product.
+4. Gate export or publish on `block` whenever the host allows it.
+5. Keep a CI fallback that runs workspace validation before merge or deploy.
+
+Hosted tools usually start with `descriptor` mode and rely on a later workspace gate for authoritative promotion.
+
+## Template engines and scaffolds
+
+Examples: internal generators, boilerplate scaffolds, CMS-to-code exporters.
+
+Recommended flow:
+
+1. Use the contract as an input spec for allowed structure, layout, color, icon, motion, and shell boundary rules.
+2. Emit provenance in generated output.
+3. Produce descriptors or run workspace validation as part of generation.
+4. Fail the generation job when a blocking finding is returned.
+
+## What can vary by tool
+
+- how the contract is injected into prompts or generation config
+- whether the tool uses `descriptor` or `workspace` mode first
+- how findings are surfaced back to the user
+- whether publish/export can be blocked in-product or only in CI
+
+## What must stay stable
+
+- contract semantics
+- shell-boundary meaning
+- `pass|warn|block` verdict meaning
+- the use of CI/CD validation as the final shipping gate
+
+## Related docs
+
+- [AI Generator Adapter Quick Start](./ai-generator-adapter-quickstart.md)
+- [AI Generator Adapter API](./ai-generator-adapter-api.md)
+- [Generator-Aware Contract Consumption](./generator-consumption.md)
+- [Shell Boundary Semantics](./shell-boundary.md)