diff --git a/docs/specifications/dcm-admin-gui-spec.md b/docs/specifications/dcm-admin-gui-spec.md
new file mode 100644
index 0000000..9f1fb06
--- /dev/null
+++ b/docs/specifications/dcm-admin-gui-spec.md
@@ -0,0 +1,253 @@
+# DCM Admin Web GUI Specification
+
+> **AEP Alignment:** Admin API endpoints referenced in this spec follow [AEP](https://aep.dev) conventions — custom methods use colon syntax (`POST /admin/providers/{uuid}:approve`). See `schemas/openapi/dcm-admin-api.yaml` for the normative specification.
+
+
+**Document Status:** 🔄 In Progress
+**Document Type:** Specification — Platform Administration Interface
+**Related Documents:** [Admin API Specification](dcm-admin-api-spec.md) | [Consumer GUI Specification](dcm-consumer-gui-spec.md) | [Provider GUI Specification](dcm-provider-gui-spec.md) | [Flow GUI Specification](dcm-flow-gui-spec.md)
+
+> **Status:** Draft — Ready for implementation feedback
+>
+> The Admin GUI is the platform operations console for Platform Admins, SREs, Policy Owners, Security teams, and Auditors. It wraps the Admin API and exposes all platform management capabilities. Like the Consumer GUI, it participates in the same session model — same login, role-gated access to the admin panel.
+
+---
+
+## 1. Architecture
+
+### 1.1 Unified Shell Model
+
+The Admin GUI is not a separate application. It is an **additional surface within the DCM web application**, revealed when the authenticated actor holds a platform-level role (`platform_admin`, `sre`, `auditor`, `security`, `policy_owner`).
+
+```
+DCM Web Application
+├── Consumer Portal (visible to all authenticated actors)
+│     └── [section 2–11 of Consumer GUI spec]
+│
+├── Admin Panel (visible to platform-level role holders)
+│     └── [this spec — section 2–11]
+│
+├── Provider Management (visible to provider owner roles)
+│     └── [Provider GUI spec — dcm-provider-gui-spec.md]
+│
+└── Flow GUI (linked / embedded for policy_owner and sre)
+      └── [dcm-flow-gui-spec.md]
+```
+
+Navigation adapts to the actor's highest privilege level. A Platform Admin sees all three surfaces. A consumer-only actor sees only the Consumer Portal.
+
+### 1.2 Authentication and Role Mapping
+
+The Admin GUI requires the session to carry a platform-level role. The role check is performed client-side on every page load and server-enforced by the Admin API on every request.
+
+| Role | Admin sections available |
+|------|--------------------------|
+| `platform_admin` | All Admin sections |
+| `sre` | Health, Discovery, Orphan Management, Scoring, Session Management |
+| `security` | Audit, Session Management (force revoke), Accreditation |
+| `policy_owner` | Policy management, Approval management, Tier Registry |
+| `auditor` | Audit (read-only), Scoring audit trail |
+| `finops` | Quota management, Cost aggregation (if FinOps module enabled) |
+
+---
+
+## 2. Platform Overview Dashboard
+
+Landing page for all platform-level roles. Data aggregated from `GET /api/v1/admin/health` and related endpoints.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  DCM Platform Health                              ● All Systems ✅│
+│  ─────────────────────────────────────────────────────────────  │
+│  Control Plane                    Providers                      │
+│  API Gateway      ✅ pass         Registered:    12             │
+│  Policy Engine    ✅ pass         Healthy:       11             │
+│  Scoring Engine   ✅ pass         Degraded:       1  ⚠️         │
+│  Request Sched.   ✅ pass         Unhealthy:      0             │
+│  Drift Reconciler ✅ pass                                        │
+│                                   Auth Providers                 │
+│  Stores                           Registered:     2             │
+│  Session Store    ✅ pass         Healthy:        2             │
+│  Audit Store      ✅ pass                                        │
+│  ─────────────────────────────────────────────────────────────  │
+│  Pending Approvals: 3 🔔  |  Open Drift Records: 7  |  Orphans: 0│
+└─────────────────────────────────────────────────────────────────┘
+```
+
+Dashboard widgets (configurable per role):
+- Control plane component health grid
+- Provider health summary with degraded/unhealthy callouts
+- Pending approvals count (with link to approval queue)
+- Open drift records by severity
+- Active sessions count
+- Request pipeline throughput (requests/minute, last 1 hour)
+- Scheduled requests queue depth
+
+---
+
+## 3. Tenant Management
+
+**API:** `GET /api/v1/admin/tenants`, `POST /api/v1/admin/tenants`, `POST /api/v1/admin/tenants/{uuid}:suspend`, `POST /api/v1/admin/tenants/{uuid}:reinstate`, `DELETE /api/v1/admin/tenants/{uuid}`
+
+- Tenant list with status, member count, resource count, quota utilization
+- Create tenant form: name, description, initial quota set, initial admin member
+- Tenant detail: members, resource count by type, quota view, active sessions count
+- Suspend / reinstate / decommission with confirmation dialog requiring typed tenant name
+- Tenant audit trail: all admin actions taken on this tenant
+
+---
+
+## 4. Provider Management
+
+**API:** `GET /api/v1/admin/providers`, `GET /api/v1/admin/providers/pending`, `POST /api/v1/admin/providers/{uuid}:approve`, `POST /api/v1/admin/providers/{uuid}:reject`, `POST /api/v1/admin/providers/{uuid}:suspend`
+
+> **Full provider management** (configuration, capacity, entity lists, type-specific management) is in the **[Provider GUI](dcm-provider-gui-spec.md)**. This section covers the admin-level registration approval workflow.
+
+- Pending registrations list: provider type, submitter, submission time, capability declaration summary
+- Registration review: full capability declaration YAML, validation result, automated checks passed/failed
+- Approve / reject with comment (recorded in audit trail)
+- Active providers list: health status, entity count, last health check time
+- Suspend provider: warns if active entities will be affected and shows count
+
+---
+
+## 5. Accreditation Management
+
+**API:** `GET /api/v1/admin/accreditations`, `POST /api/v1/admin/accreditations/{uuid}:approve`, `DELETE /api/v1/admin/accreditations/{uuid}`
+
+- Pending accreditations queue with submission detail
+- Approve / revoke with required comment
+- Accreditation expiry calendar: upcoming renewals in P90D window highlighted
+- Accreditation gap detection: data classifications that require accreditations not currently held
+
+---
+
+## 6. Discovery and Orphan Management
+
+**API:** `POST /api/v1/admin/discovery:trigger`, `GET /api/v1/admin/discovery/jobs/{uuid}`, `GET /api/v1/admin/orphans`, `POST /api/v1/admin/orphans/{uuid}/resolve`
+
+### 6.1 Discovery Console
+
+- Trigger on-demand discovery by resource type and provider
+- Discovery job status with progress (resources scanned, new discoveries, changes detected)
+- Discovery history: recent jobs with outcome summary
+
+### 6.2 Orphan Resolution Queue
+
+- List orphan candidates: resources discovered in provider that have no DCM Realized State record
+- Per-orphan action: Ingest (create Realized State record), Decommission (instruct provider to delete), Ignore (mark as known-unmanaged)
+- Bulk actions for same-type orphans
+
+---
+
+## 7. Quota Management
+
+**API:** `GET /api/v1/admin/tenants/{uuid}/quotas`, `PUT /api/v1/admin/tenants/{uuid}/quotas/{resource_type}`
+
+- Per-tenant quota view: current limits vs current usage vs projected usage
+- Inline edit quota values; save triggers `PUT /api/v1/admin/tenants/{uuid}/quotas/{resource_type}`
+- Quota utilization heatmap across all tenants (who is using the most of what)
+- Quota alert configuration: threshold for "approaching limit" notifications
+
+---
+
+## 8. Scoring Model Administration
+
+**API:** `GET /api/v1/admin/profiles/{name}/scoring`, `PATCH /api/v1/admin/profiles/{name}/scoring`, `POST /api/v1/admin/profiles/{name}/scoring/overrides`, `GET /api/v1/admin/scoring/audit`, `GET /api/v1/admin/actors/{uuid}/risk-history`
+
+### 8.1 Profile Scoring Configuration
+
+- Score threshold table per profile: approval routing tiers vs score ranges
+- Visual slider interface for threshold adjustment (guardrail: auto_approve_below ≤ 50 enforced — slider hard-stops at 50)
+- Signal weight editor: operational_gatekeeper (45%), completeness (15%), actor_risk_history (20%), quota_pressure (10%), provider_accreditation (10%) — weights must sum to 100%
+- Preview: submit a sample request to see the score it would receive under current config
+
+### 8.2 Policy Enforcement Override
+
+- Per-policy enforcement class override: escalate operational → compliance, or demote compliance → operational
+- Required justification field; change recorded in audit trail
+- Shadow policies table with divergence rates — promotes action for high-divergence policies
+
+### 8.3 Actor Risk History
+
+- Search by actor UUID or handle
+- Risk signal history timeline: what events contributed to elevated risk score
+- Manual reset capability (requires `platform_admin` role + comment)
+
+---
+
+## 9. Approval Management
+
+**API:** `GET /api/v1/admin/approvals/pending`, `POST /api/v1/admin/approvals/{uuid}:vote`, `GET /api/v1/admin/approvals/{uuid}`
+
+- All pending approvals across all tenants (Platform Admin view) vs own queue (approver view)
+- Filter by tier (reviewed / verified / authorized), resource type, tenant, age
+- Approval detail: request payload, risk score breakdown, policy evaluation results, existing votes
+- Vote with comment; authorized-tier quorum tracker
+- Expired approvals: review and optionally reopen
+
+---
+
+## 10. Authority Tier Registry
+
+**API:** `POST /api/v1/admin/tier-registry/changes`, `GET /api/v1/admin/tier-registry/changes/{uuid}/impact`, `POST /api/v1/admin/tier-registry/changes/{uuid}:accept-degradation`, `POST /api/v1/admin/tier-registry/changes/{uuid}:activate`
+
+- Current tier registry: ordered list display (auto → reviewed → verified → authorized → [custom tiers])
+- Propose change: drag-and-drop reordering with add/remove custom tier
+- Impact report: automatically fetched after proposal; displays SECURITY_DEGRADATION (red), BROKEN_REFERENCE (orange), PROFILE_GAP (yellow), SECURITY_UPGRADE (green)
+- Degradation acceptance: per-item accept flow with required compensating control rationale
+- Activate button disabled until all blocking items are resolved
+
+---
+
+## 11. Audit and Compliance
+
+**API:** `GET /api/v1/audit/...` (admin-scoped, cross-tenant)
+
+Visible to `auditor` and `platform_admin` roles.
+
+- **Platform-wide audit trail**: all DCM actions across all tenants; filterable by actor, tenant, resource type, operation, date range
+- **Compliance reports**: pre-built reports for common frameworks (SOC 2 Type II, FedRAMP, HIPAA) — export to PDF/CSV
+- **Audit chain integrity status**: last verification timestamp; trigger re-verification; alert on chain break
+- **Cross-tenant correlation**: enter correlation ID to trace a request end-to-end across tenants and providers
+
+---
+
+## 12. Session and Security Management
+
+**API:** `GET /api/v1/admin/actors/{uuid}/...`, `POST /api/v1/admin/actors/{uuid}:revoke-sessions`
+
+Visible to `security` and `platform_admin` roles.
+
+- **Active sessions**: all active sessions across all actors; filterable by auth provider, role, tenant
+- **Force revoke**: select one or all sessions for an actor; requires reason (logged to audit)
+- **Security events**: real-time feed of auth.security_session_revoked and ICOM_UNAUTHORIZED_SOURCE events
+- **Internal component certificates**: table of component cert expiry dates; alert on certs expiring within P14D; ICOM-006 compliance view
+
+---
+
+## 13. Health and Operations
+
+**API:** `GET /api/v1/admin/health`, `GET /api/v1/admin/discovery:trigger`, `POST /api/v1/admin/search-index:rebuild`
+
+Visible to `sre` and `platform_admin` roles.
+
+- Full component health detail (Section 2 dashboard expanded view)
+- Prometheus metrics viewer (embedded Grafana or linked)
+- Manual operations: trigger discovery, rebuild search index, rotate bootstrap credential
+- Deployment info: DCM version, instance UUID, profile, uptime
+- **Runbook links**: direct links to doc 41 (Operational Reference) scenarios from health page
+
+---
+
+## 14. Flow GUI Integration
+
+The Flow GUI (policy authoring tool — separate spec) is accessible to actors with `policy_owner` or `sre` roles:
+
+- **Link** from the Admin Panel navigation to the Flow GUI
+- **Embedded iframe** option for deployments that want a unified navigation experience
+- Active profile and policy summary widgets from Flow GUI embeddable on the Admin dashboard
+
+---
+
+*Document maintained by the DCM Project. For questions or contributions see [GitHub](https://github.com/dcm-project).*
diff --git a/docs/specifications/dcm-consumer-gui-spec.md b/docs/specifications/dcm-consumer-gui-spec.md
new file mode 100644
index 0000000..eb3af20
--- /dev/null
+++ b/docs/specifications/dcm-consumer-gui-spec.md
@@ -0,0 +1,922 @@
+# DCM Consumer Web GUI Specification
+
+> **AEP Alignment:** Consumer API endpoints referenced in this spec follow [AEP](https://aep.dev) conventions — custom methods use colon syntax, async operations return `Operation` resources, and `operation_uuid == request_uuid`. See `schemas/openapi/dcm-consumer-api.yaml` for the normative specification.
+
+
+**Document Status:** 🔄 In Progress
+**Document Type:** Specification — Consumer Web Interface
+**Related Documents:** [RHDH Integration Specification](dcm-rhdh-integration-spec.md) | [Consumer API Specification](consumer-api-spec.md) | [Admin GUI Specification](dcm-admin-gui-spec.md) | [Provider GUI Specification](dcm-provider-gui-spec.md) | [Flow GUI Specification](dcm-flow-gui-spec.md) | [Auth Providers](https://github.com/croadfeldt/udlm/blob/main/governance/auth-providers.md) | [Session Revocation](../../architecture/control-plane/session-revocation.md)
+
+> **Status:** Draft — Ready for implementation feedback
+>
+> **Primary deployment target:** Red Hat Developer Hub (RHDH) or upstream Backstage. The DCM Consumer Portal is implemented as a Backstage plugin suite. The standalone SPA mode is an alternative for deployments that do not run RHDH. See [RHDH Integration Specification](dcm-rhdh-integration-spec.md) for the complete Backstage plugin architecture.
+>
+> **Design goals (in priority order):**
+> 1. **Low time to market** — RHDH brings auth, search, TechDocs, RBAC, GitOps integration, and a full component library pre-built. DCM plugins extend rather than rebuild.
+> 2. **Ease of use** — familiar mental models (PatternFly/OpenShift language); task-oriented navigation; zero-ticket provisioning.
+> 3. **Extensible** — plugin architecture means new resource types surface automatically; no GUI code changes for new catalog items.
+> 4. **Security and governance by design** — tenancy, RBAC, audit, and policy constraints are architectural, not add-ons.
+
+---
+
+## 1. Deployment Models
+
+### 1.1 RHDH / Backstage Mode (Primary)
+
+DCM is implemented as a Backstage plugin suite loaded into an RHDH or Backstage instance. DCM capabilities appear as a first-class section within the existing RHDH navigation.
+
+```
+RHDH Instance
+├── Pre-built RHDH capabilities (Catalog, Create, TechDocs, Search, ...)
+│     └── These work unchanged — DCM augments them
+│
+└── DCM Plugin Suite (loaded as Dynamic Plugins)
+      ├── @dcm/plugin                 frontend plugin — nav + pages + entity tabs
+      ├── @dcm/plugin-backend         backend plugin — API proxy, SSE relay, auth
+      ├── @dcm/plugin-catalog-backend catalog processor + entity provider
+      ├── @dcm/plugin-scaffolder-backend custom scaffolder actions
+      └── @dcm/permission-policy      DCM → Backstage permission bridge
+```
+
+**Why RHDH first:**
+- Auth (RHSSO/Keycloak/OIDC) is already configured — no auth plumbing
+- RBAC plugin already provides no-code permission management
+- Search indexes DCM entities alongside existing catalog entities
+- TechDocs renders DCM data model docs and runbooks in-portal
+- Dynamic Plugins — DCM plugins load without rebuilding the RHDH image (OCI or npm)
+- Existing integrations: ArgoCD/GitOps (layer store visibility), Tekton (scaffolding pipelines), AAP (DCM providers that use Ansible), OCM (cluster management alongside DCM service catalog)
+
+### 1.2 Standalone SPA Mode (Alternative)
+
+For deployments without RHDH, DCM ships a standalone React SPA using PatternFly components. The same plugin modules are used; the host application is a lightweight Backstage-compatible shell rather than full RHDH.
+
+```
+Standalone DCM App
+├── PatternFly Page shell (Header, Sidebar, Content)
+├── Auth: DCM Auth Provider (OIDC/LDAP/built-in)
+└── DCM plugin modules (same packages as RHDH mode)
+```
+
+The standalone mode provides feature parity. RHDH mode is recommended because it provides broader platform capabilities without additional investment.
+
+---
+
+## 2. Navigation Architecture
+
+### 2.1 Design Principles
+
+**Organized by what users want to accomplish, not by API object.** A user who wants to "check on my database VM" thinks "My Resources" — not "Realized State Entity Management." The navigation labels match the user's mental model.
+
+**PatternFly grouped hierarchical left nav.** Following OpenShift console and PatternFly's recommended pattern for administrative interfaces with multiple entity types. Consistent with what Red Hat users already know.
+
+**Stable groups, role-gated items.** Group headings are always visible; items within them hide (not disable) based on the actor's roles. A user who gains the `approver` role sees Approvals appear without any change to the application.
+
+**Tenant context in the header, not in the nav.** Following RHDH's namespace/group context selector pattern — the active tenant is ambient context shown in the masthead, switchable without navigating away.
+
+### 2.2 Navigation Structure
+
+```
+[RHDH Masthead]
+┌──────────────────────────────────────────────────────────────┐
+│ ⬡ Red Hat Developer Hub     [Search]    👤 User  🏢 Tenant  │
+└──────────────────────────────────────────────────────────────┘
+
+[Sidebar — DCM section within RHDH nav]
+━━━━━━━━━━━━━━━━━━
+ DCM                           ← Section header in RHDH sidebar
+━━━━━━━━━━━━━━━━━━
+ 🏪 Service Catalog
+
+ MY WORK                       ← NavGroup (non-clickable group label)
+   📋 Requests
+   🖥  Resources
+   🔗 Dependency Groups
+
+ 🔔 Approvals        [3]       ← NavItem with NotificationBadge (orange, count)
+
+ GOVERNANCE                    ← NavGroup
+   💰 Cost & Quota
+   📤 Contributions            ← hidden if not contributor role
+
+ SETTINGS                      ← NavGroup
+   🔔 Notifications
+   🔐 Sessions
+━━━━━━━━━━━━━━━━━━
+```
+
+**PatternFly components used:**
+- `Nav` with `variant="default"` — left sidebar navigation
+- `NavGroup` — non-clickable group labels (MY WORK, GOVERNANCE, SETTINGS)
+- `NavItem` — clickable navigation items with optional `<NotificationBadge>`
+- `NavItemSeparator` — visual divider between major areas
+- `PageHeader` with `Masthead` — tenant context selector (ContextSelector component)
+
+### 2.3 Tenant Context Selector
+
+The active tenant is displayed in the masthead as a `ContextSelector` (PatternFly):
+
+```
+[Masthead right side]
+  👤 alice@corp.com    🏢 Payments Team ▾
+                            ├── Payments Team      ← current
+                            ├── Platform Team
+                            └── ─────────────
+                                All My Tenants
+```
+
+- Single-tenant actors: selector hidden; tenant name displayed static
+- Multi-tenant actors: dropdown triggers `X-DCM-Tenant` header change; page data refreshes
+- Tenant switch does not navigate; current page re-fetches with new tenant context
+
+### 2.4 Role-Gating Rules
+
+| NavItem | Visible when actor has |
+|---------|----------------------|
+| Service Catalog | Any role (always visible) |
+| Requests | `consumer` or any role |
+| Resources | `consumer` or any role |
+| Dependency Groups | `consumer` or any role |
+| Approvals + badge | `approver` role |
+| Cost & Quota | `consumer` or `tenant_admin` |
+| Contributions | `contributor` role |
+| Notifications | Any role |
+| Sessions | Any role |
+
+Items not shown for a role are **hidden entirely** — no disabled states in the nav.
+
+---
+
+## 3. Service Catalog
+
+**Route:** `/dcm/catalog`  
+**API:** `GET /api/v1/catalog`, `GET /api/v1/catalog/{uuid}`, `GET /api/v1/catalog/search`
+
+### 3.1 In RHDH Mode — Software Templates Integration
+
+In RHDH, DCM catalog items are exposed as **Backstage Software Templates**. The standard RHDH "Create" page becomes the DCM service catalog.
+
+```
+RHDH "Create" page
+└── DCM Templates category
+      ├── 🖥  Standard VM (t-shirt sizes)
+      ├── 🗄  Database — PostgreSQL
+      ├── 🌐  Virtual Network
+      ├── 🔒  TLS Certificate
+      └── 📦  [More DCM catalog items...]
+```
+
+Templates are auto-generated by `@dcm/plugin-catalog-backend` — it reads `GET /api/v1/catalog` and emits one Template entity per DCM catalog item. The template's input schema is derived directly from the DCM catalog item's field schema. No manual template authoring needed when a new resource type appears.
+
+DCM-specific catalog view at `/dcm/catalog` provides additional DCM context:
+- Cost estimate per item (calls `POST /api/v1/cost/estimate` with default values)
+- Availability indicator (quota headroom)
+- Dependency graph preview
+- Provider badge and SLA indicators
+
+### 3.2 Catalog Browser
+
+- **Card grid** — PatternFly `Gallery` with `GalleryItem` cards
+- **Filter toolbar** — PatternFly `Toolbar` with category chips, tag filter, search input
+- Card shows: name, description, provider type badge, cost estimate, availability
+- Quick-request button opens the scaffolder template directly from the card
+
+### 3.3 Catalog Item Detail
+
+- Full description, field schema viewer, dependency declaration, TechDocs link
+- Live cost estimate — updates as user adjusts quantity/size fields (debounced)
+- Quota check: remaining quota for this resource type in active tenant
+- "Request This Service" → opens Scaffolder wizard
+
+---
+
+## 4. Request Submission — Scaffolder Integration
+
+**In RHDH mode:** Request submission uses the Backstage Scaffolder. DCM does not build a separate request form. The Scaffolder is the request form.
+
+### 4.1 Template Structure
+
+Each DCM catalog item generates a Backstage Software Template:
+
+```yaml
+apiVersion: scaffolder.backstage.io/v1beta3
+kind: Template
+metadata:
+  name: dcm-compute-vm-standard
+  title: "Standard VM"
+  description: "Provision a standard virtual machine"
+  annotations:
+    dcm.io/catalog-item-uuid: "<uuid>"
+    dcm.io/resource-type: "Compute.VirtualMachine"
+  tags: [dcm, compute, infrastructure]
+spec:
+  type: dcm-resource
+  parameters:
+    # Auto-generated from DCM catalog item field schema
+    - title: "Configure Your VM"
+      required: [cpu_count, memory_gb, os_family, name]
+      properties:
+        cpu_count:
+          title: CPU Cores
+          type: integer
+          enum: [2, 4, 8, 16, 32]
+          default: 4
+          ui:widget: select
+        memory_gb:
+          title: Memory (GB)
+          type: integer
+          enum: [8, 16, 32, 64, 128]
+          default: 16
+        name:
+          title: Resource Name
+          type: string
+          pattern: "^[a-z0-9-]{3,63}$"
+          ui:help: "Lowercase letters, numbers, hyphens. 3-63 characters."
+
+    - title: "Scheduling (Optional)"
+      properties:
+        dispatch:
+          title: When to provision
+          type: string
+          enum: [immediate, at, window]
+          default: immediate
+        not_before:
+          title: Not before (UTC)
+          type: string
+          format: date-time
+          ui:widget: datetime
+          ui:if: "dispatch === 'at'"
+        window_id:
+          title: Maintenance Window
+          type: string
+          ui:field: dcm:MaintenanceWindowPicker
+          ui:if: "dispatch === 'window'"
+
+    - title: "Review"
+      # Auto-populated review step showing cost estimate and policy pre-check
+
+  steps:
+    - id: dcm-cost-estimate
+      name: "Estimate cost"
+      action: dcm:request:estimate
+      input:
+        catalogItemUuid: "${{ parameters.catalog_item_uuid }}"
+        fields: "${{ parameters }}"
+
+    - id: dcm-submit
+      name: "Submit request"
+      action: dcm:request:submit
+      input:
+        catalogItemUuid: "${{ parameters.catalog_item_uuid }}"
+        fields: "${{ parameters }}"
+        schedule:
+          dispatch: "${{ parameters.dispatch }}"
+          notBefore: "${{ parameters.not_before }}"
+
+    - id: dcm-wait
+      name: "Waiting for provisioning..."
+      action: dcm:request:wait
+      input:
+        requestUuid: "${{ steps.dcm-submit.output.requestUuid }}"
+        timeoutMinutes: 30
+
+    - id: register
+      name: "Register in catalog"
+      action: dcm:catalog:refresh
+      input:
+        entityUuid: "${{ steps.dcm-submit.output.entityUuid }}"
+
+  output:
+    links:
+      - title: "View Resource"
+        url: "${{ steps.dcm-wait.output.entityUrl }}"
+      - title: "View Request"
+        url: "${{ steps.dcm-submit.output.requestUrl }}"
+```
+
+### 4.2 Custom Scaffolder Actions
+
+Provided by `@dcm/plugin-scaffolder-backend`:
+
+| Action | Description |
+|--------|-------------|
+| `dcm:request:estimate` | Call `POST /api/v1/cost/estimate`; output cost breakdown for review step |
+| `dcm:request:submit` | `POST /api/v1/requests`; output requestUuid, entityUuid |
+| `dcm:request:wait` | Poll `GET /api/v1/requests/{uuid}/status` (or SSE); surface live status in Scaffolder log; resolve on terminal state |
+| `dcm:request:group` | `POST /api/v1/request-groups`; submit multiple requests with dependency graph |
+| `dcm:catalog:refresh` | Trigger entity provider refresh for new entity; output entityUrl for output links |
+| `dcm:approval:notify` | Fire notification to approver group when approval required |
+
+### 4.3 Live Status in Scaffolder
+
+The `dcm:request:wait` action streams progress to the Scaffolder log panel using the Scaffolder's built-in log streaming UI:
+
+```
+⏳  Waiting for provisioning...
+    09:00:05  Status: ACKNOWLEDGED
+    09:00:07  Status: ASSEMBLING layers
+    09:00:12  Status: DISPATCHED to provider
+    09:01:05  Status: PROVISIONING
+              Step 3/7: Configuring network interfaces
+              ████████████░░░░░░░░  3 of 7 complete
+    09:03:12  ✅ Status: REALIZED
+              Resource: payments-api-server-01
+              IP: 10.42.0.105
+```
+
+This reuses the Scaffolder's existing log streaming rather than building a custom progress component.
+
+---
+
+## 5. My Work — Requests
+
+**Route:** `/dcm/requests`  
+**API:** `GET /api/v1/requests`, `GET /api/v1/requests/{uuid}/status`, `GET /api/v1/requests/{uuid}/stream`, `DELETE /api/v1/requests/{uuid}`
+
+### 5.1 Requests List
+
+PatternFly `Table` with Toolbar filter:
+
+```
+[MY REQUESTS]
+Filter: [Status ▾] [Resource Type ▾] [Date Range ▾]   [Search name...]
+
+  Name                    Type         Status           Submitted
+  ─────────────────────────────────────────────────────────────────
+  payments-api-server-01  Compute.VM   ● REALIZED       2h ago
+  dev-db-postgres-02      Database     ⏳ PROVISIONING  15m ago   [Live ▶]
+  uat-lb-internal         LoadBalancer ⚠ REQUIRES APPR. 1h ago   [Review →]
+  batch-runner-scheduled  Compute.VM   🕐 SCHEDULED     Tomorrow
+```
+
+Status badges use PatternFly `Label` component:
+- `● REALIZED` — green Label
+- `⏳ PROVISIONING` — blue Label + spinner
+- `⚠ REQUIRES APPROVAL` — orange Label
+- `🕐 SCHEDULED` — grey Label
+- `✗ FAILED` — red Label
+
+"Live ▶" button opens an inline `Drawer` (PatternFly) showing the SSE status stream — no page navigation required.
+
+### 5.2 Live Status Drawer
+
+Clicking "Live ▶" opens a right-side Drawer anchored to the page:
+
+```
+┌─── Request Status ───────────────────────────────── ✕ ─┐
+│  dev-db-postgres-02            ⏳ PROVISIONING          │
+│                                                          │
+│  Timeline:                                              │
+│  ✅ 09:00:00  ACKNOWLEDGED                              │
+│  ✅ 09:00:02  ASSEMBLING                                │
+│  ✅ 09:00:47  DISPATCHED → provider-postgres-prod       │
+│  ⏳ 09:01:05  PROVISIONING                              │
+│                                                          │
+│  Progress: Step 3 of 7                                  │
+│  Configuring network interfaces                          │
+│  ████████████░░░░░░░░░░░░  43%                          │
+│                                                          │
+│  Est. completion: ~4 minutes                            │
+│                               [Cancel Request]          │
+└──────────────────────────────────────────────────────────┘
+```
+
+Powered by `GET /api/v1/requests/{uuid}/stream` (SSE). Drawer closes automatically on terminal status, replaces status badge in the table row.
+
+---
+
+## 6. My Work — Resources
+
+**Route:** `/dcm/resources`  
+**API:** `GET /api/v1/resources`, resource sub-resource endpoints
+
+### 6.1 Resource List
+
+```
+[MY RESOURCES]
+Filter: [State ▾] [Type ▾] [Group ▾] [Tag ▾]       [Search...]    [Table/Card ▾]
+
+  ● 3 resources with drift detected  [View Drift Report →]
+
+  Name                  Type        State        Provider     TTL
+  ────────────────────────────────────────────────────────────────
+  payments-api-01  ⚡  Compute.VM   ✅ OPER.      k8s-prod    87d   [···]
+  dev-db-001            Database    ✅ OPER.      db-prod     —     [···]
+  uat-loadbalancer  🔴  Network.LB  ⚠ DRIFT      net-prod    —     [···]
+```
+
+Icons:
+- `⚡` — TTL warning (< 14 days)
+- `🔴` dot — open drift record
+- `···` — action menu (Suspend, Update, Extend TTL, Transfer, Decommission)
+
+State badges use PatternFly `Label`:
+- `✅ OPERATIONAL` — green
+- `🟡 SUSPENDED` — yellow
+- `🔵 MAINTENANCE` — blue
+- `⚠ DRIFT` — orange (custom — shows worst drift severity)
+- `✗ FAILED` — red
+
+### 6.2 Resource Entity Page
+
+Clicking a resource opens its **Backstage entity page** (standard RHDH pattern). DCM contributes tabs via entity page tab extensions:
+
+```
+[Entity Header]
+payments-api-server-01                               ✅ OPERATIONAL
+Compute.VirtualMachine  |  provider: k8s-prod  |  owner: payments-team
+
+[Tabs]
+  Overview │ Drift 🔴 │ Audit │ Cost │ Credentials │ Relations │ Docs
+```
+
+**Overview tab:** IP address, hostname, CPU, memory, OS, provider, realized date, TTL, all realized fields from provider.
+
+**Drift tab 🔴** (badge shows drift severity):
+```
+Open Drift Records (1 significant, 1 minor)
+
+  Field          Realized Value    Discovered Value    Severity
+  cpu_count      4                 8                   ⚠ significant
+  memory_gb      16                16                  ✅ no drift
+  tags           [app:api]         [app:api, env:prod]  ℹ minor
+
+  Actions: [Revert All]  [Accept Changes (Update Definition)]  [Acknowledge Minor]
+```
+
+**Cost tab:** Actual cost from `GET /api/v1/resources/{uuid}/cost`. PatternFly `ChartBar` for cost by billing dimension.
+
+**Credentials tab:**
+```
+  Credential           Type         Expires      Last Retrieved
+  ssh-key-payments-01  ssh_key      2027-06-01   2 days ago
+  api-key-svc-acct     api_key      never         —
+
+  [Retrieve Value →]   ← triggers inline step-up MFA prompt
+  [Request Rotation →]
+```
+
+**Relations tab:** PatternFly `TopologyView` or a simple dependency graph showing what this resource depends on and what depends on it.
+
+### 6.3 Drift Report — Cross-Resource View
+
+**Route:** `/dcm/resources/drift`  
+Accessible via "View Drift Report →" banner on resource list when drift exists.
+
+```
+[DRIFT REPORT — Payments Team]           3 resources with open drift
+
+  Severity  Resource              Field           Realized    Discovered  Since
+  ──────────────────────────────────────────────────────────────────────────────
+  ● Critical  prod-db-primary     replication      enabled     disabled    4h
+  ● Signif.   uat-lb-internal     cpu_count        4           8           2d
+  ● Minor     dev-app-01          tag:env          staging     (missing)   1w
+
+  [Revert All Critical]   [Export Drift Report]   [Configure Drift Alerts]
+
+  Auto-remediation status:
+  prod-db-primary: REVERT_PENDING — waiting for maintenance window
+```
+
+Severity filter chips at top (PatternFly `ChipGroup`). Clicking a row opens the resource entity Drift tab.
+
+
+---
+
+## 7. My Work — Dependency Groups
+
+**Route:** `/dcm/dependency-groups`  
+**API:** `GET /api/v1/request-groups`, `GET /api/v1/request-groups/{uuid}`, `DELETE /api/v1/request-groups/{uuid}`
+
+```
+[MY DEPENDENCY GROUPS]
+
+  three-tier-app-deploy          in_progress          Started 30m ago
+  ├── db          ✅ REALIZED    payments-db-01        09:01
+  ├── app         ⏳ DISPATCHED  (pending db IP → db_host injected)
+  └── lb          ○ PENDING      (waiting for app)
+
+  [Cancel Group]  [View All Requests]
+```
+
+Progress bar shows N of M constituents realized.
+
+---
+
+## 8. ITSM Integration
+
+DCM is designed to eliminate the infrastructure ticket as the primary provisioning mechanism. However, organizations that operate ITSM systems (ServiceNow, Jira Service Management, Remedy) still require bidirectional traceability — change records for compliance, incident linkage for troubleshooting, and CMDB accuracy.
+
+DCM's ITSM integration is a **bridge, not a dependency.** DCM does not require an ITSM system to function. ITSM integration is additive — it enriches DCM entities with ITSM metadata and notifies ITSM of DCM lifecycle events.
+
+### 8.1 ITSM Reference Linking
+
+Every DCM resource entity supports an optional `itsm_references` metadata block in its business data:
+
+```
+[Resource Entity Header]
+payments-api-server-01                                ✅ OPERATIONAL
+
+[ITSM References — visible as a metadata card on Overview tab]
+  Change Record    CHG0012345    Approved 2026-03-15   [View in ServiceNow ↗]
+  Incident         INC0048291    (linked on creation)  [View in Jira ↗]
+  CMDB Item        CI-VM-08821   Auto-synced           [View in CMDB ↗]
+```
+
+References are stored as business data fields on the entity — they follow the entity through its full lifecycle and appear in audit records. They are **not** required for DCM to function.
+
+### 8.2 ITSM Event Webhook Integration
+
+DCM fires lifecycle events to the Message Bus. An ITSM notification service subscribes to these events and creates/updates ITSM records accordingly:
+
+| DCM Event | ITSM Action (configurable) |
+|-----------|---------------------------|
+| `request.requires_approval` | Create Change Request draft in ServiceNow / Jira |
+| `request.realized` | Close Change Request; update CMDB CI |
+| `request.failed` | Create Incident; link to Change Request |
+| `entity.state_changed` | Update CMDB CI state |
+| `drift.detected` (significant/critical) | Create Incident in ITSM |
+| `entity.decommissioned` | Retire CMDB CI; close related Change Requests |
+
+This is implemented as a **notification service** registered in DCM — a webhook consumer that translates DCM events to ITSM API calls. No changes to DCM core are needed.
+
+### 8.3 ITSM Ticket as Approval Mechanism
+
+For organizations that require ITSM change board approval, DCM's `authorized` tier approval mechanism accepts votes recorded via the ITSM system:
+
+```
+[Request reaches authorized tier → approval required]
+  │
+  ▼ DCM fires request.requires_approval
+  │   notification service creates Change Request in ServiceNow
+  │
+  ▼ Change Board reviews in ServiceNow (existing process unchanged)
+  │   Approval decision → ServiceNow calls DCM Admin API:
+  │   POST /api/v1/admin/approvals/{uuid}:vote
+  │   { "decision": "approve", "recorded_via": "servicenow", "voter_uuid": "..." }
+  │
+  ▼ DCM records vote; quorum tracked by DCM
+  │   Audit trail includes: who voted, via which system, at what time
+```
+
+The approval decision is made in ServiceNow using the organization's existing CAB process. DCM records the outcome. Neither system depends on the other's internal workflow model.
+
+### 8.4 ITSM Reference UI
+
+In the Consumer GUI, ITSM references surface in two places:
+
+**On resource entity Overview tab** — ITSM References card (shown only when references exist):
+```
+ITSM References
+  ┌────────────────────────────────────────────────────────┐
+  │  CHG0012345  Change Request   Approved  [Open ↗]      │
+  │  INC0048291  Incident         Resolved  [Open ↗]      │
+  └────────────────────────────────────────────────────────┘
+  [Add Reference]  (opens modal: type, ID, system URL)
+```
+
+**On request status page** — when a request is at `requires_approval` and an ITSM reference is attached:
+```
+⏳ REQUIRES APPROVAL — verified tier
+   Approval being tracked via ServiceNow Change Board
+   CHG0012345 [View in ServiceNow ↗]
+   Quorum: 0 / 2 votes recorded
+```
+
+### 8.5 CMDB Sync
+
+DCM entities are the **system of record** for realized state. The CMDB is a **consumer** of DCM data, not a producer. CMDB sync flows one way: DCM → CMDB.
+
+The sync is implemented via the notification service subscription to `entity.*` events. A CMDB sync notification service maps DCM entity fields to CMDB CI attributes and calls the CMDB API on every state change.
+
+**CMDB field mapping** is declared in the provider registration — it is not hardcoded. Different CMDB systems (ServiceNow CMDB, iTop, Device42) use the same event subscription pattern with different field mapping configurations.
+
+---
+
+## 9. Approvals
+
+**Route:** `/dcm/approvals`  
+**API:** `GET /api/v1/approvals/pending`, `POST /api/v1/approvals/{uuid}`
+
+Visible only to actors with `approver` role. NavItem shows orange badge with pending count.
+
+```
+[PENDING APPROVALS — 3]
+
+  Request                  Tenant      Tier       Risk   Expires
+  ────────────────────────────────────────────────────────────────
+  Large GPU VM (8x A100)   AI Team     verified    72/100  2h 14m
+  Prod DB 32-core          Data Team   reviewed    41/100  23h
+  Bulk decommission (12)   Platform    authorized  88/100  45m  ← quorum 1/3
+
+  [Review →]
+```
+
+Clicking "Review →" opens the Approval Detail page:
+- Full request payload summary
+- Risk score breakdown (signal chart)
+- Policy evaluation results (which policies flagged this)
+- Existing votes (for authorized tier quorum tracking)
+- [Approve] [Reject] buttons with required comment field
+- Approver cannot vote on own requests (blocked UI-side + server-side)
+
+---
+
+## 10. Governance — Cost and Quota
+
+**Route:** `/dcm/cost`
+
+```
+[COST & QUOTA — Payments Team]   This month: $12,450   vs budget: $15,000
+
+  Quota Utilization
+  Compute.VM          ████████████████░░░░  80%  (16/20 allocated)  ⚠
+  Storage.Block       ████░░░░░░░░░░░░░░░░  22%  (11/50 TB)
+  Network.LB          ██░░░░░░░░░░░░░░░░░░   8%  (2/25 units)
+
+  Cost by Resource Type (last 30 days)
+  [PatternFly ChartDonut or ChartBar]
+
+  Top Cost Resources
+  payments-api-01    Compute.VM    $3,200/mo
+  payments-db-01     Database      $2,800/mo
+  ...
+
+  [Export CSV]  [View All Resources]
+```
+
+---
+
+## 11. Governance — Audit Trail
+
+**Route:** `/dcm/audit`  
+**API:** `GET /api/v1/resources/{uuid}/audit`, `GET /api/v1/audit/correlation/{correlation_id}`
+
+Visible to all actors for their own resources. Cross-tenant audit is in the Admin Panel.
+
+```
+[MY AUDIT TRAIL]
+Filter: [Resource Type ▾] [Operation ▾] [Date Range ▾]   [Correlation ID search...]
+
+  Time          Resource                Operation        Actor
+  ─────────────────────────────────────────────────────────────────────
+  5m ago        payments-api-01         PATCH            alice@corp.com
+  2h ago        dev-db-001              DRIFT_REVERT     system
+  Yesterday     uat-lb-internal         REALIZED         alice@corp.com
+  2 days ago    batch-runner-01         DECOMMISSIONED   bob@corp.com
+
+  [View Full Record →]   [Export CSV]
+```
+
+**Record detail drawer:** Operation, Resource, Actor (with auth method), Time, Correlation ID trace, fields changed, policy evaluations, risk score.
+
+**Correlation ID trace:** links to full request pipeline view — Intent → Requested → Dispatch → Realized → Provider chain — for the actor's own requests.
+
+---
+
+## 12. Governance — Contributions
+
+**Route:** `/dcm/contributions`  
+**API:** `GET /api/v1/contribute`, `POST /api/v1/contribute/policy`, `DELETE /api/v1/contribute/{uuid}`
+
+Visible only to actors with `contributor` role.
+
+```
+[MY CONTRIBUTIONS]
+
+  Handle                     Type              Status         Submitted
+  ─────────────────────────────────────────────────────────────────────
+  payments-network-policy    policy            ● active       3 months ago
+  gpu-quota-validator        policy            🔵 shadow      1 week ago   [Divergence: 2.3%]
+  ml-resource-group          resource_group    ⏳ reviewing   2 days ago
+
+  [Submit New Policy]  [Submit Resource Group]
+```
+
+Shadow divergence percentage shown for shadow-mode contributions — clicking opens divergence case viewer.
+
+---
+
+## 13. Settings — Notifications
+
+**Route:** `/dcm/notifications`  
+**API:** `GET /api/v1/notifications`, `GET /api/v1/webhooks`, `POST /api/v1/webhooks`
+
+```
+[NOTIFICATIONS]     [Mark All Read]
+
+  🔔 Request REALIZED: payments-api-server-01          2m ago   [View →]
+  ⚠  Drift detected: uat-loadbalancer (significant)    1h ago   [View →]
+  ⏰ TTL Warning: dev-db-001 expires in 7 days          3h ago   [Extend →]
+
+  ─────────────────
+  [WEBHOOK SUBSCRIPTIONS]
+
+  URL                                  Events                Status
+  https://my-system/dcm-webhook        request.*, drift.*    ✅ active  [Test] [Delete]
+
+  [Add Webhook]
+```
+
+---
+
+## 14. Settings — Sessions
+
+**Route:** `/dcm/sessions`  
+**API:** `GET /api/v1/auth/sessions`, `DELETE /api/v1/auth/sessions/{uuid}`
+
+```
+[ACTIVE SESSIONS]
+
+  Device                    Auth Method   Created         Last Active
+  ──────────────────────────────────────────────────────────────────
+  This session ●            OIDC          Today 09:00     Active now
+  Chrome / Mac (10.0.1.5)   OIDC          Yesterday       2h ago       [Revoke]
+  API Client (svc-acct)     api_key       3 days ago      1h ago       [Revoke]
+
+  [Sign Out All Other Sessions]
+```
+
+---
+
+## 15. In RHDH — TechDocs Integration
+
+DCM publishes TechDocs for:
+- Service catalog item documentation (from DCM layer store)
+- Resource type specifications
+- DCM data model documentation (this spec set)
+
+TechDocs are indexed by RHDH search — users can search "how do I provision a GPU cluster" and find both the catalog item and the documentation.
+
+DCM entity pages link to TechDocs automatically via `backstage.io/techdocs-ref` annotation on generated catalog entities.
+
+---
+
+## 16. Search Integration
+
+In RHDH mode, DCM entities are indexed in Backstage search:
+
+- DCM catalog items indexed as `DCMService` entities — searchable by name, description, tags
+- DCM realized resources indexed as `DCMResource` entities — searchable by handle, IP, type
+- TechDocs content indexed — searchable documentation
+- Search collator provided by `@dcm/plugin-catalog-backend`
+
+Search result rendering:
+```
+  🖥 payments-api-server-01    DCMResource    Compute.VM    ● OPERATIONAL
+     10.42.0.105 · k8s-prod · payments-team
+```
+
+---
+
+
+### 16.1 Global Search Bar
+
+PatternFly `SearchInput` in masthead — keyboard shortcut `/` to focus. Searches across catalog items, resources, requests, and TechDocs (RHDH mode).
+
+### 16.2 Search Results Page
+
+**Route:** `/dcm/search?q=<query>`
+
+```
+[SEARCH RESULTS: "payments db"]                    12 results
+
+  [All ▾] [Catalog Items] [Resources] [Requests] [Docs]   ← filter chips
+
+  CATALOG ITEMS (2)
+  ● Database.PostgreSQL   Managed PostgreSQL instance   [Request →]
+  ● Database.MySQL        Managed MySQL instance        [Request →]
+
+  MY RESOURCES (3)
+  ● payments-db-primary   Database.PostgreSQL  ✅ OPERATIONAL  [View →]
+  ● payments-db-replica   Database.PostgreSQL  ✅ OPERATIONAL  [View →]
+
+  MY REQUESTS (1)
+  ● payments-db-archive   SCHEDULED  Tomorrow 02:00  [View →]
+```
+
+Results render incrementally per category with PatternFly `Spinner` while loading. Keyboard navigation through results supported.
+
+## 17. Path to Production — Effort Reduction Summary
+
+| Traditional Workflow | DCM + RHDH |
+|---------------------|------------|
+| Submit infrastructure ticket | Browse catalog → click "Request" → Scaffolder wizard |
+| Wait for human review (hours/days) | Policy engine auto-approves in seconds; escalates if needed |
+| Infrastructure team provisions manually | DCM dispatches to provider automatically |
+| Receive confirmation email | SSE live status in Scaffolder; notification in portal |
+| Manually update CMDB | Entity appears in RHDH catalog automatically after REALIZED |
+| Track cost in spreadsheet | Cost tab on every resource entity page |
+| Periodic compliance audits | Drift detection continuous; audit trail always current |
+| Decommission via ticket | Self-service Delete with stake resolution |
+| Document runbooks separately | TechDocs in same portal, linked from entity pages |
+| Separate access management | RHDH RBAC + DCM permission policy — one place |
+
+**Time to first production resource (new user):**
+1. Log in (SSO — already have corporate credentials)
+2. Browse catalog or search for service
+3. Fill in Scaffolder form (5–10 fields, schema-driven, cost estimate live)
+4. Submit → watch live provisioning log
+5. Resource appears in catalog and "My Resources"
+
+**Target: < 10 minutes from login to operational resource.**
+
+---
+
+## 18. Security Model
+
+### 16.1 Tenancy Enforcement
+
+- Active tenant: RHDH Group context → `X-DCM-Tenant` header on all DCM API calls
+- All data filtered server-side by DCM Consumer API (defense in depth)
+- Entity ownership in RHDH catalog: `spec.owner = group:<tenant-uuid>` — users see only own-tenant entities
+
+### 16.2 RBAC
+
+- RHDH RBAC plugin maps Backstage permissions to DCM roles
+- DCM roles in session token drive nav visibility (client-side, defense-in-depth)
+- DCM Consumer API enforces roles server-side on every request
+- New roles propagate from IdP via SCIM or OIDC claims — no manual assignment
+
+### 16.3 Step-Up MFA
+
+Credential retrieval, ownership transfer, and bulk decommission trigger inline MFA:
+- PatternFly `Modal` overlay — no page navigation
+- User completes second factor in RHDH auth provider
+- Step-up token cached PT10M (per session model)
+
+### 16.4 Content Security Policy (Standalone Mode)
+
+- `default-src 'self'`
+- `connect-src 'self' <dcm-api-origin> <rhdh-origin>`
+- No inline scripts; no eval(); SRI on external assets
+
+### 16.5 Governance and Regulatory Compliance
+
+All compliance constraints are enforced by the DCM control plane — the GUI is a client. The GUI surfaces compliance state:
+- Data classification badges on entity detail pages (from `data_classification` fields)
+- Sovereignty constraint indicators on entities with cross-boundary restrictions
+- Accreditation status visible in entity overview
+- Audit trail always accessible; chain integrity status shown
+
+The GUI cannot be used to bypass policy — every action goes through the Consumer API which applies the full five-check boundary model (doc 26), scoring, GateKeeper, and policy evaluation.
+
+---
+
+## 19. Extensibility
+
+### 17.1 New Resource Types — Zero GUI Code
+
+When a new resource type is registered in DCM:
+1. `@dcm/plugin-catalog-backend` detects it via the resource type registry
+2. A new Software Template is auto-generated from the field schema
+3. A new `DCMService` catalog entity appears in RHDH
+4. The template's input form renders from JSON Schema — no UI code needed
+5. The resource entity page uses the same Overview/Drift/Audit/Cost/Credentials/Relations tabs — no new tabs needed for standard resource types
+
+Resource type-specific UI extensions are possible via entity page tab contributions if a resource type requires specialized visualization (e.g. a topology view for network types).
+
+### 17.2 Custom Plugin Extensions
+
+Teams can contribute additional entity page tabs, catalog cards, or nav items via standard Backstage plugin extension points. DCM plugin APIs for contributing extensions:
+
+```typescript
+// Register a custom entity tab for a specific resource type
+dcmPlugin.registerEntityTab({
+  resourceType: 'Network.VirtualNetwork',
+  component: NetworkTopologyTab,
+  title: 'Topology',
+  icon: NetworkIcon,
+});
+
+// Register a custom catalog card
+dcmPlugin.registerCatalogCard({
+  component: GPUAvailabilityCard,
+  position: 'right',
+});
+```
+
+### 17.3 Multi-Portal Deployments
+
+Large organizations with multiple RHDH instances (one per business unit) can:
+- Point multiple RHDH instances at the same DCM control plane
+- Each RHDH instance filters DCM entities to its tenant scope
+- DCM federation handles cross-instance resource visibility where permitted
+
+---
+
+## 20. Conformance
+
+A conforming Consumer GUI implementation must:
+
+1. Implement all DCM nav groups: Service Catalog, My Work (Requests/Resources/Groups), Approvals, Governance (Cost & Quota/Contributions), Settings
+2. Implement SSE-based live status with constituent tracking (with polling fallback)
+3. Enforce tenancy context (`X-DCM-Tenant`) on all API calls
+4. Hide (not disable) role-gated navigation items
+5. Implement step-up MFA inline for gated operations
+6. Surface drift, audit, cost, credentials, and relationships as entity page tabs
+7. In RHDH mode: implement all six plugin packages with the specified capabilities
+8. Auto-generate Software Templates from DCM catalog item schemas (RHDH mode)
+
+---
+
+*Document maintained by the DCM Project. For questions or contributions see [GitHub](https://github.com/dcm-project).*
diff --git a/docs/specifications/dcm-flow-gui-spec.md b/docs/specifications/dcm-flow-gui-spec.md
new file mode 100644
index 0000000..f63bffe
--- /dev/null
+++ b/docs/specifications/dcm-flow-gui-spec.md
@@ -0,0 +1,1007 @@
+# DCM Flow GUI Specification
+
+**Document Status:** 📋 Draft — Ready for Implementation Feedback
+**Document Type:** User Interface Specification
+
+
+> **📋 Draft**
+>
+> This specification defines the DCM Flow GUI — the visual interface for platform engineers to compose, test, simulate, and manage DCM's policy-driven orchestration. All views, data contracts, API endpoints, and component structure are specified. Feedback and contributions welcome via [GitHub Issues](https://github.com/dcm-project/issues).
+
+**Version:** 0.1.0-draft
+**Status:** Draft — Ready for implementation feedback
+**Document Type:** Technical Specification
+**Related Documents:** [Foundational Abstractions](https://github.com/croadfeldt/udlm/blob/main/foundations/foundations.md) | [Control Plane Components](../../architecture/control-plane/components.md) | [OPA Integration Specification](dcm-opa-integration-spec.md) | [Policy Profiles](../../architecture/governance-enforcement/policy-profiles.md) | [Policy Contract](https://github.com/croadfeldt/udlm/blob/main/contracts/policy-contract.md) | [Consumer API](consumer-api-spec.md) | [Admin API](dcm-admin-api-spec.md)
+
+---
+
+## Abstract
+
+> **AEP Alignment:** This specification follows [AEP](https://aep.dev) conventions.
+> Custom methods use colon syntax (e.g., `POST /flow/api/v1/shadow/{uuid}:promote`).
+> List endpoints use `page_size` and `page_token` parameters.
+> The Flow GUI API is a dedicated backend for the visual tooling — it is separate from the
+> main Consumer and Admin APIs. See `schemas/openapi/dcm-consumer-api.yaml` for the
+> normative consumer-facing API specification.
+
+
+The DCM Flow GUI is the visual interface for platform engineers to compose, test, and manage DCM's data-driven orchestration. Because policies ARE the orchestration in DCM, the Flow GUI is fundamentally a **visual policy composer** — it makes the active policy graph visible and editable without requiring direct YAML or Rego authoring.
+
+The Flow GUI is a **platform engineer tool**, not a consumer tool. It operates with platform admin or policy author role permissions. Consumers interact with DCM through the Consumer API and Web UI, not through the Flow GUI.
+
+---
+
+## 1. Architecture and Component Structure
+
+### 1.1 Component Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Browser (SPA)                            │
+│   Flow GUI Application — React single-page application          │
+│   Authentication: Bearer token (same session as Consumer API)   │
+└──────────────────────────────┬──────────────────────────────────┘
+                               │ HTTPS REST
+                               ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                   Flow GUI Service                               │
+│   Purpose: aggregate data for Flow GUI views                     │
+│   Deployed alongside DCM control plane                           │
+│   Authentication: validates Bearer token; requires policy_author │
+│                   or platform_admin role                         │
+│                                                                  │
+│   Reads from:                                                    │
+│     Policy Engine  — live graph, firing frequency                │
+│     GitOps stores  — policy artifacts, PR status                 │
+│     Observability  — event volumes, error rates                  │
+│     OPA sidecar    — test harness, shadow results                │
+│   Writes via:                                                    │
+│     Git API        — create PRs for policy changes               │
+│     Admin API      — shadow mode promotion, profile changes      │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 1.2 Authentication and Authorization
+
+The Flow GUI uses the same session token as the Consumer API. Required roles:
+
+| Role | Access |
+|------|--------|
+| `platform_admin` | Full read/write — all views, all authoring, profile management |
+| `policy_author` | Read all views; author policies in assigned domains; cannot manage profiles or promote shadow policies |
+| `platform_observer` | Read-only — all views; no authoring; no simulation write |
+
+### 1.3 Base URL
+
+```
+https://{dcm-instance}/flow/api/v1/
+```
+
+Distinct from the Consumer API base URL to make routing and access control clear.
+
+---
+
+## 2. The Execution Graph View
+
+### 2.1 What It Shows
+
+The primary view shows the live execution graph: which policies are active, which payload types they match, how they compose with each other, and their firing frequency. This is the "live map" of DCM's orchestration state.
+
+```
+[request.initiated] ──→ [IntentCapturePolicy] ──→ [request.intent_captured]
+                                                          │
+                                          ┌───────────────┼───────────────┐
+                                          ▼               ▼               ▼
+                                  [LayerAssembly]   [CostCheck]   [AuthzCheck]
+                                  (system/blue)     (tenant/yellow)(system/blue)
+                                          │
+                                          ▼
+                               [request.layers_assembled]
+                                          │
+                              ┌───────────┼───────────┐
+                              ▼           ▼            ▼
+                      [GateKeeper:      [Transform:   [GovMatrix:
+                       vm-size-limits]  inject-mon.]  phi-boundary]
+                              └───────────┼───────────┘
+                                          ▼
+                               [request.policies_evaluated]
+```
+
+**Visual conventions:**
+- **Node color by domain:** system=blue, platform=green, tenant=yellow, resource_type=purple
+- **Node shape by policy type:** GateKeeper=shield, Transformation=gear, Recovery=arrow, Governance Matrix=lock, Orchestration Flow=rectangle
+- **Edge thickness:** proportional to firing frequency (last 1h)
+- **Edge color:** green=allow path, red=deny path, amber=conditional
+- **Node badge:** shadow mode indicator (S), deprecated indicator (D)
+
+### 2.2 API — Fetch Execution Graph
+
+```
+GET /flow/api/v1/graph
+
+Query parameters:
+  payload_type=<type>      filter to policies matching this payload type
+  resource_type=<fqn>      filter to policies applicable to this resource type
+  domain=<domain>          filter by policy domain
+  policy_type=<type>       filter by policy type
+  tenant_uuid=<uuid>       include tenant-domain policies for this Tenant
+
+Response 200:
+{
+  "graph": {
+    "nodes": [
+      {
+        "node_id": "<uuid>",                 # policy_uuid
+        "label": "vm-size-limits",
+        "policy_type": "gatekeeper",
+        "domain": "tenant",
+        "tenant_uuid": "<uuid>",
+        "handle": "tenant/payments/gatekeeper/vm-size-limits",
+        "version": "1.2.0",
+        "status": "active",
+        "shadow_mode": false,
+        "match_payload_types": ["request.layers_assembled"],
+        "match_conditions_summary": "cpu_count > 32 OR memory_gb > 256",
+        "firing_frequency": {
+          "last_1h": 3,
+          "last_24h": 47,
+          "last_7d": 312
+        },
+        "deny_rate_24h": 0.06             # 6% of evaluations resulted in deny
+      }
+    ],
+    "edges": [
+      {
+        "from_payload_type": "request.layers_assembled",
+        "to_node_id": "<policy_uuid>",
+        "edge_type": "policy_fires_on",
+        "volume_24h": 47
+      },
+      {
+        "from_node_id": "<policy_uuid>",
+        "to_payload_type": "request.policies_evaluated",
+        "edge_type": "produces",
+        "condition": "on_allow"
+      }
+    ]
+  },
+  "payload_types": [
+    {
+      "payload_type": "request.layers_assembled",
+      "volume_24h": 789,
+      "active_policy_count": 4
+    }
+  ],
+  "last_updated": "<ISO 8601>"
+}
+```
+
+### 2.3 API — Get Policy Node Detail
+
+```
+GET /flow/api/v1/graph/nodes/{policy_uuid}
+
+Response 200:
+{
+  "policy_uuid": "<uuid>",
+  "handle": "tenant/payments/gatekeeper/vm-size-limits",
+  "version": "1.2.0",
+  "policy_type": "gatekeeper",
+  "domain": "tenant",
+  "concern_type": "security",
+  "enforcement": "soft",
+  "status": "active",
+
+  "match_conditions": {
+    "payload_type": "request.layers_assembled",
+    "conditions": [
+      { "field": "payload.fields.cpu_count.value", "operator": "gt", "value": 32 }
+    ]
+  },
+
+  "output_schema": {
+    "decision": "deny",
+    "reason_template": "cpu_count {value} exceeds maximum 32"
+  },
+
+  "firing_history": [
+    { "timestamp": "<ISO 8601>", "result": "deny", "request_uuid": "<uuid>" },
+    { "timestamp": "<ISO 8601>", "result": "allow", "request_uuid": "<uuid>" }
+  ],
+
+  "git_path": "policy-store/tenant/payments/gatekeeper/vm-size-limits/v1.2.0.yaml",
+  "pr_url": null,             # null if no pending PR; URL if change in review
+
+  "compliance_basis": null,
+  "review_required_before": null,
+
+  "test_suite": {
+    "test_count": 3,
+    "last_run": "<ISO 8601>",
+    "result": "pass"
+  }
+}
+```
+
+---
+
+## 3. Policy Canvas — Static Flow Builder
+
+### 3.1 Interaction Model
+
+The Policy Canvas is a drag-and-drop interface for building named Orchestration Flow Policies (Level 1 orchestration — named workflow artifacts). The output is a valid DCM Orchestration Flow Policy YAML committed via a Git PR.
+
+**Key constraint:** The canvas never writes directly to the Policy Store. All saves generate a Git PR. The PR goes through the standard review process. Shadow mode activates automatically when the PR is created — the proposed workflow evaluates against real traffic in shadow mode until merged.
+
+### 3.2 Canvas Operations
+
+| Operation | Description | Backend action |
+|-----------|-------------|----------------|
+| Drag payload type node | Add a workflow step | Canvas state update (local) |
+| Connect nodes | Declare step sequence | Canvas state update (local) |
+| Set step conditions | Add conditions to a step | Canvas state update (local) |
+| Set failure behavior | halt / skip / escalate | Canvas state update (local) |
+| Preview YAML | Show generated policy YAML | `GET /flow/api/v1/canvas/preview` |
+| Save as PR | Create Git PR with policy YAML | `POST /flow/api/v1/canvas/save` |
+| Load existing | Load an existing flow policy | `GET /flow/api/v1/policies/{policy_uuid}/canvas` |
+
+### 3.3 API — Preview Canvas as YAML
+
+```
+POST /flow/api/v1/canvas/preview
+
+Request body:
+{
+  "handle": "org/orchestration/vm-provisioning-flow",
+  "concern_type": "orchestration_flow",
+  "ordered": true,
+  "steps": [
+    {
+      "step": 1,
+      "payload_type": "request.initiated",
+      "policy_handle": "system/orchestration/capture-intent",
+      "on_fail": "halt"
+    },
+    {
+      "step": 2,
+      "payload_type": "request.intent_captured",
+      "policy_handle": "system/orchestration/assemble-layers",
+      "on_fail": "halt"
+    },
+    {
+      "step": 3,
+      "payload_type": "request.layers_assembled",
+      "policy_handle": "system/orchestration/run-placement",
+      "on_fail": "halt",
+      "condition": "not payload.placement_complete"
+    }
+  ],
+  "applicable_resource_types": ["Compute.VirtualMachine"]
+}
+
+Response 200:
+{
+  "yaml": "# Generated by DCM Flow GUI\n# Handle: org/orchestration/vm-provisioning-flow\n...",
+  "rego": "package dcm.orchestration.vm_provisioning_flow\n...",
+  "validation": {
+    "valid": true,
+    "warnings": ["Step 3 condition references 'payload.placement_complete' which is not in the standard payload vocabulary"]
+  }
+}
+```
+
+### 3.4 API — Save Canvas as Git PR
+
+```
+POST /flow/api/v1/canvas/save
+
+Request body:
+{
+  "canvas_definition": { ... },  # same as preview request
+  "commit_message": "Add VM provisioning orchestration flow",
+  "pr_title": "feat(orchestration): VM provisioning named workflow",
+  "pr_description": "Defines explicit sequence for VM provisioning requests",
+  "target_branch": "main",
+  "shadow_mode": true            # proposed status — shadow evaluates before merge
+}
+
+Response 201 Created:
+{
+  "pr_uuid": "<uuid>",
+  "pr_url": "https://git.corp.example.com/dcm-policies/pulls/142",
+  "pr_status": "open",
+  "shadow_mode_activated": true,
+  "policy_handle": "org/orchestration/vm-provisioning-flow",
+  "policy_status": "proposed"   # active in shadow mode; not yet enforced
+}
+```
+
+### 3.5 API — Load Existing Flow Policy into Canvas
+
+```
+GET /flow/api/v1/policies/{policy_uuid}/canvas
+
+Response 200:
+{
+  "canvas_definition": {
+    "handle": "...",
+    "ordered": true,
+    "steps": [...]
+  },
+  "yaml": "...",
+  "policy_uuid": "<uuid>",
+  "version": "1.2.0",
+  "git_path": "..."
+}
+```
+
+---
+
+## 4. Policy Authoring Interface
+
+### 4.1 Visual Condition Builder
+
+For simple policies (field comparisons, role checks, quota checks), a visual condition builder generates valid Rego without requiring Rego knowledge.
+
+**Supported condition types:**
+
+| Field type | Operators | Example |
+|-----------|-----------|---------|
+| Numeric field | equals, not_equals, gt, gte, lt, lte, in_range | `cpu_count > 32` |
+| String field | equals, not_equals, in_list, matches_regex | `os_family in [rhel, ubuntu-lts]` |
+| List field | contains, does_not_contain | `actor.roles contains platform_admin` |
+| Boolean field | is_true, is_false | `payload.fields.production_workload = true` |
+| Existence | exists, does_not_exist | `payload.fields.cost_center exists` |
+
+### 4.2 API — Generate Policy from Visual Conditions
+
+```
+POST /flow/api/v1/policies/generate
+
+Request body:
+{
+  "policy_type": "gatekeeper",
+  "handle": "tenant/payments/gatekeeper/vm-size-limits",
+  "concern_type": "security",
+  "domain": "tenant",
+  "tenant_uuid": "<uuid>",
+  "enforcement": "soft",
+  "match": {
+    "payload_type": "request.layers_assembled",
+    "resource_type": "Compute.VirtualMachine",
+    "conditions": [
+      { "field": "payload.fields.cpu_count.value", "operator": "gt", "value": 32 }
+    ],
+    "condition_logic": "any"
+  },
+  "output": {
+    "decision": "deny",
+    "reason_template": "cpu_count {payload.fields.cpu_count.value} exceeds maximum 32 for this Tenant"
+  },
+  "audit_on": ["DENY"],
+  "notification_on": ["DENY"]
+}
+
+Response 200:
+{
+  "yaml": "# DCM GateKeeper Policy\n...",
+  "rego": "package dcm.gatekeeper.vm_size_limits\n\ndeny contains reason if {\n    input.payload.type == \"request.layers_assembled\"\n    input.payload.fields.cpu_count.value > 32\n    reason := sprintf(\"cpu_count %d exceeds maximum 32\", [input.payload.fields.cpu_count.value])\n}\n",
+  "validation": {
+    "valid": true,
+    "warnings": []
+  }
+}
+```
+
+### 4.3 Rego Editor
+
+For complex policies requiring full Rego expressiveness, the GUI includes an embedded Rego editor with:
+
+- **Input schema autocomplete:** all valid `input.*` paths from the DCM input document schema
+- **DCM built-in reference:** sidebar showing available built-in functions and constants
+- **Real-time syntax validation:** calls OPA `/v1/compile` to validate without evaluation
+- **Test case runner:** executes the policy against saved test cases
+
+### 4.4 API — Validate Rego
+
+```
+POST /flow/api/v1/policies/validate-rego
+
+Request body:
+{
+  "rego": "package dcm.gatekeeper.example\n\ndeny contains reason if {\n    input.payload.fields.cpu_count.value > 32\n    reason := \"too many CPUs\"\n}\n",
+  "policy_type": "gatekeeper"
+}
+
+Response 200:
+{
+  "valid": true,
+  "warnings": [],
+  "errors": [],
+  "output_schema_match": true,   # output matches declared policy_type schema
+  "input_paths_used": [
+    "input.payload.fields.cpu_count.value"
+  ],
+  "input_paths_unknown": []      # paths that don't exist in the input document schema
+}
+
+Response 200 (with errors):
+{
+  "valid": false,
+  "errors": [
+    { "line": 4, "column": 5, "message": "undefined variable: reason_text" }
+  ]
+}
+```
+
+### 4.5 Test Case Management
+
+```
+# List test cases for a policy
+GET /flow/api/v1/policies/{policy_uuid}/tests
+
+Response 200:
+{
+  "test_cases": [
+    {
+      "test_uuid": "<uuid>",
+      "name": "Reject oversized VM",
+      "input_payload": { "payload": { "type": "request.layers_assembled", "fields": { "cpu_count": { "value": 64 } } } },
+      "expected_output": { "deny": ["cpu_count 64 exceeds maximum 32"] },
+      "last_result": "pass",
+      "last_run": "<ISO 8601>"
+    }
+  ]
+}
+
+# Create test case from a real recent request
+POST /flow/api/v1/policies/{policy_uuid}/tests/from-request
+{
+  "request_uuid": "<uuid>",      # saves that request's payload as a test case
+  "expected_output": { "deny": [] },
+  "test_name": "Normal VM request — should allow"
+}
+
+# Run all test cases
+POST /flow/api/v1/policies/{policy_uuid}/tests:run
+
+Response 200:
+{
+  "run_uuid": "<uuid>",
+  "result": "pass",             # pass | fail | error
+  "test_results": [
+    {
+      "test_uuid": "<uuid>",
+      "name": "Reject oversized VM",
+      "result": "pass",
+      "actual_output": { "deny": ["cpu_count 64 exceeds maximum 32"] },
+      "expected_output": { "deny": ["cpu_count 64 exceeds maximum 32"] }
+    }
+  ],
+  "duration_ms": 42
+}
+```
+
+---
+
+## 5. Flow Simulation
+
+### 5.1 Simulation Model
+
+Platform engineers simulate a synthetic request through the active policy engine without creating real state. The simulation runs against the live Policy Engine with a caller-constructed payload. No audit records are written. No Requested State is created.
+
+### 5.2 API — Simulate Request
+
+```
+POST /flow/api/v1/simulate
+
+Request body:
+{
+  "catalog_item_uuid": "<uuid>",     # optional; used to seed field schema
+  "resource_type": "Compute.VirtualMachine",
+  "tenant_uuid": "<uuid>",
+  "synthetic_fields": {
+    "cpu_count": 64,
+    "memory_gb": 128,
+    "os_family": "rhel"
+  },
+  "synthetic_actor": {
+    "roles": ["developer"],
+    "group_memberships": ["payments-team"]
+  },
+  "include_policy_types": ["gatekeeper", "transformation", "governance_matrix"]
+}
+
+Response 200:
+{
+  "simulation_uuid": "<uuid>",
+  "result": "rejected",            # allowed | rejected | degraded
+  "terminal_reason": "GateKeeper policy rejected at step request.layers_assembled",
+
+  "execution_trace": [
+    {
+      "step": 1,
+      "payload_type": "request.initiated",
+      "policies_evaluated": [],
+      "result": "pass",
+      "duration_ms": 2
+    },
+    {
+      "step": 2,
+      "payload_type": "request.intent_captured",
+      "policies_evaluated": [],
+      "result": "pass",
+      "duration_ms": 1
+    },
+    {
+      "step": 3,
+      "payload_type": "request.layers_assembled",
+      "policies_evaluated": [
+        {
+          "policy_uuid": "<uuid>",
+          "policy_handle": "tenant/payments/gatekeeper/vm-size-limits",
+          "policy_type": "gatekeeper",
+          "result": "deny",
+          "reason": "cpu_count 64 exceeds maximum 32",
+          "duration_ms": 8
+        },
+        {
+          "policy_uuid": "<uuid>",
+          "policy_handle": "org/transformation/inject-monitoring",
+          "policy_type": "transformation",
+          "result": "applied",
+          "mutations": [
+            { "field": "fields.monitoring_endpoint", "operation": "set", "value": "https://metrics..." }
+          ],
+          "duration_ms": 3
+        }
+      ],
+      "result": "rejected",
+      "terminal": true
+    }
+  ],
+
+  "assembled_payload_snapshot": {
+    "fields": {
+      "cpu_count": { "value": 64, "provenance": { "origin": { "source_type": "consumer_request" } } },
+      "monitoring_endpoint": { "value": "https://metrics...", "provenance": { "origin": { "source_type": "policy" } } }
+    }
+  },
+
+  "cost_estimate": {
+    "total_per_hour": 1.28,
+    "currency": "USD",
+    "note": "Estimated assuming request would have been allowed"
+  }
+}
+```
+
+### 5.3 Simulation vs Shadow Mode
+
+| | Simulation | Shadow Mode |
+|-|-----------|------------|
+| Trigger | Manual, synthetic payload | Automatic on real traffic |
+| Audit record | Never written | Written to Validation Store |
+| Policy status | Evaluates active policies | Evaluates proposed policies |
+| Use case | "What if?" exploration | Pre-activation validation |
+| Real data | No | Yes |
+
+---
+
+## 6. Shadow Mode Dashboard
+
+### 6.1 What It Shows
+
+Shows all proposed policies currently in shadow mode and their evaluation results against real traffic.
+
+### 6.2 API — List Shadow Policies
+
+```
+GET /flow/api/v1/shadow
+
+Response 200:
+{
+  "shadow_policies": [
+    {
+      "policy_uuid": "<uuid>",
+      "handle": "tenant/payments/gatekeeper/new-cost-check",
+      "policy_type": "gatekeeper",
+      "status": "proposed",
+      "shadow_since": "<ISO 8601>",
+      "pr_url": "https://git.corp.example.com/dcm-policies/pulls/143",
+      "pr_status": "open",
+
+      "shadow_results_24h": {
+        "total_evaluations": 156,
+        "would_have_denied": 4,
+        "would_have_allowed": 152,
+        "divergence_from_active": 4,
+        "divergence_rate": 0.026
+      }
+    }
+  ]
+}
+```
+
+### 6.3 API — Shadow Policy Detail with Divergence Cases
+
+```
+GET /flow/api/v1/shadow/{policy_uuid}
+
+Response 200:
+{
+  "policy_uuid": "<uuid>",
+  "shadow_results_24h": {
+    "total_evaluations": 156,
+    "divergence_cases": [
+      {
+        "request_uuid": "<uuid>",
+        "timestamp": "<ISO 8601>",
+        "active_result": "allow",
+        "shadow_result": "deny",
+        "shadow_reason": "Estimated cost $480/month exceeds budget ceiling $300/month",
+        "requester": "Bob Smith",
+        "resource_type": "Compute.VirtualMachine"
+      }
+    ]
+  }
+}
+```
+
+### 6.4 API — Promote Shadow Policy to Active
+
+```
+POST /flow/api/v1/shadow/{policy_uuid}:promote
+{
+  "reason": "Shadow results reviewed — divergence rate acceptable; promoting to active"
+}
+
+Response 202 Accepted:
+{
+  "policy_uuid": "<uuid>",
+  "status": "active",
+  "pr_action": "approved_and_merged",
+  "promoted_at": "<ISO 8601>"
+}
+
+Response 403 Forbidden:
+{
+  "error": "insufficient_role",
+  "reason": "Policy promotion requires platform_admin role"
+}
+```
+
+---
+
+## 7. Profile and Governance Management
+
+### 7.1 Active Profile View
+
+```
+GET /flow/api/v1/profile
+
+Response 200:
+{
+  "deployment_posture": {
+    "name": "prod",
+    "description": "Production — full zero trust, dual approval for high-trust providers, human review for all registrations",
+    "active_policy_groups": 12,
+    "hard_constraints": [
+      "sovereign/classified data never crosses any boundary",
+      "All providers require at least self_declared accreditation"
+    ]
+  },
+  "compliance_domains": [
+    {
+      "domain": "hipaa",
+      "description": "HIPAA/HITECH compliance — PHI classification, BAA requirements, minimum necessary principle",
+      "active_policy_groups": 4,
+      "key_requirements": ["PHI requires BAA accreditation", "All PHI interactions audited", "No PHI export without regulatory cert"]
+    }
+  ],
+  "recovery_posture": "notify-and-wait",
+  "zero_trust_posture": "full",
+  "total_active_policies": 47
+}
+```
+
+### 7.2 Payload Type Browser
+
+```
+GET /flow/api/v1/payload-types
+
+Response 200:
+{
+  "payload_types": [
+    {
+      "payload_type": "request.layers_assembled",
+      "description": "Layer assembly complete — payload enriched with all layer fields",
+      "volume_24h": 789,
+      "active_policy_count": 4,
+      "sample_payload": {
+        "type": "request.layers_assembled",
+        "fields": {
+          "cpu_count": { "value": 4 },
+          "memory_gb": { "value": 8 }
+        }
+      },
+      "downstream_payload_types": ["request.policies_evaluated", "recovery.gatekeeper_denied"]
+    }
+  ]
+}
+```
+
+---
+
+### 7.3 API — Update Scoring Thresholds
+
+```
+PATCH /flow/api/v1/profile/scoring
+
+Authorization: Bearer <platform_admin_token>
+
+Request body:
+{
+  "thresholds": [
+    { "tier": "auto",       "max_score": 24 },
+    { "tier": "reviewed",   "max_score": 59 },
+    { "tier": "verified",   "max_score": 79 },
+    { "tier": "authorized", "max_score": 100 }
+  ],
+  "policy_overrides": [
+    {
+      "policy_uuid": "<uuid>",
+      "enforcement_class_override": "compliance",
+      "reason": "Regulatory requirement"
+    }
+  ]
+}
+
+Response 200:
+{
+  "active_profile": "standard",
+  "thresholds": [ ... ],
+  "preview": {
+    "last_7d_auto_approve_pct": 61.2,
+    "last_7d_reviewed_pct": 31.5,
+    "last_7d_verified_pct": 7.3
+  }
+}
+```
+
+**Constraint:** `auto` tier `max_score` cannot exceed 50 (SMX-008 hard cap). The API
+returns `422 Unprocessable Entity` if this constraint is violated.
+
+### 7.4 API — Payload Type Browser
+
+```
+GET /flow/api/v1/payload-types
+
+Response 200:
+{
+  "payload_types": [
+    {
+      "type": "request.initiated",
+      "description": "A new service request has been received",
+      "fields": [
+        { "path": "catalog_item_uuid", "type": "uuid", "required": true },
+        { "path": "tenant_uuid",       "type": "uuid", "required": true },
+        { "path": "fields",            "type": "object", "required": true }
+      ],
+      "policy_types_applicable": ["gatekeeper", "validation", "transformation",
+                                   "recovery", "orchestration_flow"]
+    }
+  ]
+}
+```
+
+
+## 8. Notification Flow View
+
+### 8.1 API — Notification Flow for an Entity
+
+```
+GET /flow/api/v1/notifications/flow/{entity_uuid}
+
+Response 200:
+{
+  "entity_uuid": "<uuid>",
+  "entity_display_name": "VLAN-100",
+  "relationship_graph_depth": 2,
+
+  "notification_audiences": [
+    {
+      "actor_uuid": "<uuid>",
+      "display_name": "NetworkOps Team",
+      "audience_role": "owner",
+      "stakeholder_reason": null,
+      "service_providers": ["slack-corp", "pagerduty-prod"]
+    },
+    {
+      "actor_uuid": "<uuid>",
+      "display_name": "AppTeam Admin",
+      "audience_role": "stakeholder",
+      "stakeholder_reason": {
+        "via_entity": "VM-A",
+        "via_relationship": "attached_to",
+        "stake_strength": "required"
+      },
+      "service_providers": ["slack-corp"]
+    }
+  ],
+
+  "active_service_providers": [
+    {
+      "provider_uuid": "<uuid>",
+      "display_name": "slack-corp",
+      "status": "healthy",
+      "delivery_success_rate_24h": 0.998
+    }
+  ]
+}
+```
+
+---
+
+## 9. Error Model
+
+All Flow GUI API errors follow the standard DCM error format:
+
+```json
+{
+  "error": "<error_code>",
+  "message": "<human-readable description>",
+  "request_id": "<uuid>",
+  "timestamp": "<ISO 8601>"
+}
+```
+
+| HTTP Status | Error Code | Meaning |
+|-------------|-----------|---------|
+| 403 | `insufficient_role` | Operation requires platform_admin or policy_author role |
+| 404 | `policy_not_found` | Policy UUID not found in active policy store |
+| 409 | `pr_already_open` | A PR already exists for this policy handle |
+| 422 | `invalid_canvas` | Canvas definition is invalid (disconnected steps, unknown payload types) |
+| 422 | `rego_invalid` | Rego syntax error or output schema mismatch |
+| 422 | `simulation_failed` | Simulation could not be executed (missing fields, invalid tenant) |
+| 503 | `policy_engine_unavailable` | Policy Engine unreachable — graph data may be stale |
+| 503 | `git_unavailable` | GitOps store unreachable — PR creation unavailable |
+
+---
+
+## 10. Conformance Levels
+
+| Level | Name | Capabilities | Intended Use |
+|-------|------|-------------|-------------|
+| 1 | Read-Only | Execution Graph View (read), Profile View, Payload Type Browser, Notification Flow View, Scoring Overlay | Dashboards, observability integrations, read-only monitoring tools |
+| 2 | Standard | All Level 1 + Flow Simulation, Shadow Mode Dashboard (view only), Policy Node Detail, Scoring Simulation | Platform engineer tooling, policy review workflows |
+| 3 | Full | All Level 2 + Policy Canvas (save as PR), Policy Authoring Interface, Test Case Management, Shadow Mode Promotion | Full policy lifecycle management, policy authoring tooling |
+
+### 10.1 Conformance Implementation Checklist
+
+**Level 1 — minimum required endpoints:**
+- `GET /flow/api/v1/graph`
+- `GET /flow/api/v1/graph/nodes/{policy_uuid}`
+- `GET /flow/api/v1/profile`
+- `GET /flow/api/v1/payload-types`
+- `GET /flow/api/v1/notifications/flow/{entity_uuid}`
+- `GET /flow/api/v1/graph/scoring-overlay`
+
+**Level 2 — adds:**
+- `POST /flow/api/v1/simulate`
+- `POST /flow/api/v1/simulate/score`
+- `GET /flow/api/v1/shadow`
+- `GET /flow/api/v1/shadow/{policy_uuid}`
+
+**Level 3 — adds:**
+- `GET /flow/api/v1/canvas/preview`
+- `POST /flow/api/v1/canvas/save`
+- `GET /flow/api/v1/policies/{policy_uuid}/canvas`
+- `POST /flow/api/v1/policies/generate`
+- `POST /flow/api/v1/policies/validate-rego`
+- `GET /flow/api/v1/policies/{policy_uuid}/tests`
+- `POST /flow/api/v1/policies/{policy_uuid}/tests/from-request`
+- `POST /flow/api/v1/policies/{policy_uuid}/tests:run`
+- `POST /flow/api/v1/shadow/{policy_uuid}:promote`
+- `PATCH /flow/api/v1/profile/scoring`
+
+---
+
+*Document maintained by the DCM Project. For questions or contributions see [GitHub](https://github.com/dcm-project).*
+
+
+---
+
+## 11. Scoring Model Views
+
+### 11.1 Risk Score Overlay on Execution Graph
+
+The Execution Graph View has a **Score Mode** toggle that overlays risk scoring information:
+
+- Each operational-class GateKeeper node displays its `scoring_weight`
+- Node background color shifts from green (weight 1–20) through amber (21–50) to red (51–100)
+- A running score accumulator shows the current aggregate as the user traces a path through the graph
+- Compliance-class GateKeeper nodes display a lock icon — they are always boolean
+
+### 11.2 API — Get Score Configuration for Graph Overlay
+
+```
+GET /flow/api/v1/graph/scoring-overlay
+
+Response 200:
+{
+  "active_profile": "standard",
+  "thresholds": [
+    { "tier": "auto",       "max_score": 24 },
+    { "tier": "reviewed",   "max_score": 59 },
+    { "tier": "verified",   "max_score": 79 },
+    { "tier": "authorized", "max_score": 100 }
+  ],
+  "nodes": [
+    {
+      "node_id": "<policy_uuid>",
+      "enforcement_class": "operational",
+      "scoring_weight": 35,
+      "avg_contribution_24h": 28.5
+    }
+  ]
+}
+```
+
+### 11.3 Threshold Configuration UI (Profile Management)
+
+The Profile and Governance Management view (Section 7) is extended with a **Scoring Thresholds** panel:
+
+- Visual slider showing auto_approve / reviewed / verified / authorized bands on a 0–100 scale
+- Signal weight configuration (pie chart showing proportional contribution of each signal)
+- Policy enforcement override management (which policies are promoted/demoted in this profile)
+- Live preview: "At the current thresholds, X% of last week's requests would have been auto-approved"
+
+### 11.4 Score Breakdown in Simulation
+
+The Flow Simulation output (Section 5) is extended with a score breakdown panel:
+
+```
+Simulation result: risk_score=47, routing=reviewed
+
+Score breakdown:
+  Operational GateKeepers:  50 × 0.45 = 22.5
+    ├── cost-ceiling:        +35 ("Cost $620/month exceeds $500")
+    └── off-hours:           +15 ("Request outside business hours")
+  Completeness:             20 × 0.15 = 3.0
+    └── cost_center_absent:  +10
+  Actor risk history:       30 × 0.20 = 6.0
+    └── (2 recent events)
+  Quota pressure:           48 × 0.10 = 4.8
+    └── (87% utilized)
+  Provider risk:            15 × 0.10 = 1.5
+    └── (richness score: 85/100 → contribution: 1.5)
+  ─────────────────────────────────────────────
+  Total:                              37.8 → 47 (normalized)
+  Threshold (reviewed):           25
+  Routing decision:                   HUMAN_REVIEW ✓
+```
+
+### 11.5 API — Get Score Simulation
+
+```
+POST /flow/api/v1/simulate/score
+
+Request body:
+{
+  "synthetic_fields": { ... },
+  "synthetic_actor": { "roles": ["developer"], "risk_history_score_override": 30 },
+  "profile_override": "prod"   # optional — simulate with different profile thresholds
+}
+
+Response 200:
+{
+  "risk_score": 47,
+  "routing_decision": "reviewed",
+  "signal_breakdown": { ... },
+  "threshold_applied": 25,
+  "profile": "standard",
+  "advisory_warnings": [...]
+}
+```
+
diff --git a/docs/specifications/dcm-provider-gui-spec.md b/docs/specifications/dcm-provider-gui-spec.md
new file mode 100644
index 0000000..7912b92
--- /dev/null
+++ b/docs/specifications/dcm-provider-gui-spec.md
@@ -0,0 +1,327 @@
+# DCM Provider Management GUI Specification
+
+> **AEP Alignment:** Provider API endpoints referenced in this spec follow [AEP](https://aep.dev) conventions — custom methods use colon syntax. See `schemas/openapi/dcm-admin-api.yaml` for the normative specification.
+
+
+**Document Status:** 🔄 In Progress
+**Document Type:** Specification — Provider Management Interface
+**Related Documents:** [Unified Provider Contract](https://github.com/croadfeldt/udlm/blob/main/contracts/provider-contract.md) | [OIS Specification](dcm-operator-interface-spec.md) | [Registration Specification](dcm-registration-spec.md) | [Admin GUI Specification](dcm-admin-gui-spec.md) | [credential management service Model](https://github.com/croadfeldt/udlm/blob/main/governance/credentials.md)
+
+> **Status:** Draft — Ready for implementation feedback
+>
+> The Provider Management GUI is the interface for teams responsible for operating and maintaining DCM providers. It surfaces in the DCM web application for actors holding provider owner roles. Each of the eleven DCM provider types has a common management shell plus type-specific extension panels.
+
+---
+
+## 1. Architecture
+
+### 1.1 Surface in Unified Shell
+
+Provider management is a **third surface in the unified DCM web application**. An actor who owns a provider (registered in a provider's `owner_team_uuid` or holds the `provider_owner` role scoped to a provider) sees a "Providers" section in their navigation alongside the Consumer Portal.
+
+```
+DCM Web Application
+├── Consumer Portal
+├── Admin Panel                    ← platform_admin role
+└── Provider Management            ← provider_owner role
+      ├── My Providers (list)
+      └── [Provider Type] → [type-specific management]
+```
+
+### 1.2 Provider Owner Identity
+
+Provider ownership is declared at registration time and may include:
+- A tenant UUID (the team that owns this provider)
+- A group UUID (the specific group within that tenant)
+- Named contacts (from Business Data)
+
+The `provider_owner` role is scoped to specific provider UUIDs — a team may own multiple providers and sees all of them. Platform Admins see all registered providers across all owners.
+
+### 1.3 Common Management Shell
+
+Every provider type (all eleven) renders within the same management shell. The shell provides:
+- Provider name, type badge, health status indicator
+- Registration status (pending / active / suspended / deregistered)
+- Navigation tabs that vary by provider type
+- Health check response viewer
+- Audit trail for all admin actions on this provider
+
+---
+
+## 2. Common Provider Tabs (All Types)
+
+### 2.1 Overview
+
+- Provider UUID, handle, type, registration date, owner team/group
+- Health status: current `pass | warn | fail` with last check timestamp
+- Health response detail (from OIS `/health` endpoint — live refresh every 30s)
+- Connection details: endpoint URL, OIS version declared
+- Registration token status (active / expiry date)
+
+### 2.2 Configuration
+
+- Provider capability declaration YAML viewer (read-only; changes require re-registration or update submission)
+- Editable fields: display name, description, owner contact, notification preferences
+- Profile compatibility indicator: which DCM profiles this provider is certified to operate under
+
+### 2.3 Health History
+
+- 30-day health check history: pass / warn / fail timeline
+- Degraded periods highlighted; duration of each incident
+- Correlation with entity realization failures during degraded periods
+
+### 2.4 Audit Trail
+
+- All admin actions on this provider: approval, suspension, config changes, capacity updates
+- Actor who performed each action, timestamp, comment
+- Filterable by action type
+
+### 2.5 Notifications
+
+- Notification endpoint configuration for this provider
+- Which DCM events this provider subscribes to (webhook subscriptions for provider.* events)
+- Test webhook delivery
+
+---
+
+## 3. Service Provider — Extended Tabs
+
+Service Providers (the most common type — realize infrastructure resources) have the richest management surface.
+
+### 3.1 Capacity Management
+
+**API:** `POST /api/v1/providers/{uuid}/capacity`
+
+- Current capacity report: available units per resource type per location
+- Historical capacity charts: capacity utilization over time
+- **Manual capacity update form**: override reported capacity for emergency situations
+- Capacity denial history: requests denied due to insufficient capacity
+- Alert configuration: notify when capacity below threshold
+
+### 3.2 Managed Entities
+
+- All DCM entities realized by this provider: type, tenant, state, TTL, drift status
+- Filterable by tenant (for Platform Admin), resource type, state
+- Entity count by state (pie chart)
+- Entities with open drift records: grouped by drift severity
+- Entities approaching TTL expiry in next P7D
+- Click-through to entity detail (read-only view for provider owner; editable for Platform Admin)
+
+### 3.3 Naturalization Mapping
+
+- Resource type → provider-native mapping declarations
+- View the Naturalization configuration for each supported resource type
+- Denaturalization mapping: what provider-native fields map back to DCM fields
+- **Test naturalization**: submit a DCM payload and see the naturalized version without dispatching
+
+### 3.4 Interim Status Configuration
+
+- Enable / disable interim status reporting per resource type
+- Reporting frequency configuration (minimum interval, max steps)
+- View recent interim status payloads for debugging
+
+### 3.5 Realization History
+
+- Recent realization requests: accepted / failed / in-progress
+- Mean realization time by resource type (last 30 days)
+- Failure analysis: top failure reasons with counts
+- In-flight realizations with live status
+
+---
+
+## 4. credential management service — Extended Tabs
+
+### 4.1 Credential Inventory
+
+- All credentials managed by this provider: type, entity scope, issued date, expiry, last retrieved
+- Never shows credential values — only metadata
+- Filter by credential type (api_key, x509_certificate, ssh_key, etc.)
+- Credentials approaching expiry: highlighted red within renewal trigger window
+
+### 4.2 Rotation Management
+
+- Credentials currently in rotation (transition window open): old UUID → new UUID pairs
+- Manual rotation trigger for specific credentials
+- Rotation history with trigger reason
+
+### 4.3 Revocation Registry
+
+- Summary: total revoked, still-in-TTL (in registry), post-TTL (pruned from registry)
+- Search by credential UUID to check revocation status
+- Emergency revocation form: revoke by credential UUID or entity UUID with required reason
+
+### 4.4 External CA Configuration (if ca_type: external)
+
+- CA protocol in use (ACME / EST / SCEP / CMP / Vault PKI / etc.)
+- CA endpoint connectivity status
+- Certificate chain view: root CA → intermediate → issued certs
+- Pending certificate requests
+- CRL / OCSP endpoint status
+
+### 4.5 Algorithm Compliance View
+
+- Algorithms in use across managed credentials
+- Forbidden algorithm violations (should be zero — highlighted red if any found)
+- Algorithm distribution chart: ECDSA P-384 vs P-256 vs RSA vs other
+- Upcoming algorithm deprecations from doc 40 forbidden list
+
+---
+
+## 5. Auth Provider — Extended Tabs
+
+### 5.1 Connection Status
+
+- Auth Provider endpoint connectivity: pass / warn / fail
+- Failover chain: current primary, configured fallbacks, activation status
+- Token validation latency (p50, p99) — last 1 hour
+
+### 5.2 Actor and Group Sync
+
+- SCIM sync status (if SCIM 2.0 enabled): last sync timestamp, records synced, errors
+- Group → DCM role mapping table (read-only; changes via configuration update)
+- Actor provisioning audit: recent SCIM-triggered creates, updates, deactivations
+
+### 5.3 Session Statistics
+
+- Active session count from this Auth Provider
+- Session distribution by auth method (OIDC / LDAP / API key / mTLS)
+- MFA verification rates: mfa_verified: true vs false breakdown
+- Step-up MFA events in last 24h
+
+### 5.4 Configuration
+
+- Auth Provider YAML viewer
+- Editable: display name, session TTL, concurrent session limit, role mapping (changes go through standard artifact lifecycle — proposed → reviewed → active)
+- Shadow mode toggle for configuration changes
+
+---
+
+## 6. External Policy Evaluator — Extended Tabs
+
+### 6.1 Policy Inventory
+
+- Policies managed by this provider: handle, type, enforcement class, status (active / shadow / deprecated)
+- Policy evaluation counts and outcomes (last 24h)
+- Shadow divergence alerts: policies with >5% divergence rate from expected
+
+### 6.2 Trust Level Management
+
+- Current trust level: local / community / verified / authoritative
+- Trust elevation request form (requires Platform Admin approval)
+- Trust history
+
+### 6.3 Policy Contribution Pipeline
+
+- Policies submitted for contribution to the DCM Policy Registry
+- Lifecycle status: shadow validation period, community review, approval
+- Withdraw pending contributions
+
+---
+
+## 7. Information Provider — Extended Tabs
+
+### 7.1 Data Source Status
+
+- Connection status to upstream data source
+- Last successful sync and record count
+- Data freshness indicator (stale threshold from provider registration)
+
+### 7.2 Confidence Score Management
+
+- Declared confidence scores per data field
+- Confidence override history (when DCM overrode provider confidence based on corroboration)
+
+### 7.3 Query Performance
+
+- Response time distribution for DCM queries to this provider
+- Cache hit rate (if DCM caches this provider's data)
+- Top queried fields
+
+---
+
+## 8. data store — Extended Tabs
+
+### 8.1 Store Health
+
+- Store-specific health: write latency, read latency, replication lag (if replicated), disk utilization
+- Consistency guarantee compliance: declared vs observed consistency level
+
+### 8.2 Capacity and Retention
+
+- Storage utilization by store type (Intent, Requested, Realized, Audit)
+- Retention policy status: records approaching retention deadline
+- Partition / shard status (for GitOps stores using partitioning strategies from doc 41)
+
+---
+
+## 9. Notification and event routing services — Extended Tabs
+
+### 9.1 notification service
+
+- Delivery channel status: email, Slack, PagerDuty, etc.
+- Delivery success rate (last 24h)
+- Failed deliveries with retry status
+- Audience routing test: send a test notification to a specific audience
+
+### 9.2 event routing service
+
+- Broker connectivity status
+- Topic / stream inventory: DCM topics and consumer group lag
+- Message throughput (messages/minute by topic)
+- Dead letter queue: messages that failed delivery after retry
+
+---
+
+## 10. composite service definition — Extended Tabs
+
+### 10.1 Composite Service Status
+
+- Active composite service instances: all constituent statuses
+- Constituents in PENDING_DEPENDENCY state across all active instances
+- Failed compensation attempts (COMPENSATION_FAILED state)
+
+### 10.2 Constituent Provider Health
+
+- Health of each provider this composite service definition depends on
+- Impact analysis: if Provider X degrades, which composite services are affected
+
+---
+
+## 11. Resource Type Registry and Peer DCM — Extended Tabs
+
+### 11.1 Resource Type Registry
+
+- Resource type registry sync status: last sync, version, record count
+- Type registration submissions pending review
+- Registry health: response time, availability
+
+### 11.2 Peer DCM (Federation)
+
+- Federation tunnel status: connected / degraded / disconnected
+- Peer DCM version and deployment profile
+- Cross-instance request routing: requests forwarded to / from this peer (last 24h)
+- Sovereignty boundary status: which data classifications are permitted across this tunnel
+
+---
+
+## 12. Provider-Scoped Security
+
+### 12.1 Provider Interaction Credentials
+
+- Interaction credentials issued to this provider: count, last issued, rotation status
+- Emergency credential revocation capability
+- Audit of all credential retrievals by this provider (CPX-005: first retrieval always audited)
+
+### 12.2 mTLS Certificate Status
+
+- Provider's mTLS certificate: issuer, expiry, OCSP status
+- Certificate renewal tracking (for external CA managed certs)
+
+### 12.3 Provider Audit Trail Contribution
+
+- Provenance records emitted by this provider: count, last emitted
+- Audit forwarding status: is the provider successfully forwarding audit events?
+
+---
+
+*Document maintained by the DCM Project. For questions or contributions see [GitHub](https://github.com/dcm-project).*