docs: add platform roadmap and governance docs

.gitignore

@@ -190,6 +190,7 @@ publish/
 # but database connection strings (with potential passwords) will be unencrypted
 *.pubxml
 *.publishproj
+.worktrees/
 
 # Microsoft Azure Web App publish settings. Comment the next line if you want to
 # checkin your Azure Web App publish settings, but sensitive information contained
@@ -391,4 +392,4 @@ coverage-report/
 
 # DocFX generated outputs (do not commit generated artifacts)
 docs/_site/
-docs/api/
+docs/api/

docs/architecture-layering.md

@@ -0,0 +1,36 @@
+# Architecture Layering
+
+## Allowed Dependencies
+
+- `Kernel` depends only on BCL and internal kernel contracts.
+- `Platform Services` may depend on `Kernel` but never on `Experience Extensions`.
+- `Experience Extensions` may depend on `Kernel` and `Platform Services`.
+- `Product Surface` may depend on all public APIs but cannot introduce reverse dependencies into lower layers.
+
+## Allowed Public API Categories
+
+- `Kernel API` — core lifecycle, scheduling, bridge contracts, and invariant enforcement.
+- `Platform API` — host-neutral service abstractions (storage, shell, diagnostics, security policy).
+- `Extension API` — framework adapters and plugin contracts with explicit support tier labels.
+- `Product API` — template-facing composition APIs and app bootstrap surfaces.
+
+## Classification Decision Tree
+
+1. Does the API define runtime invariants used across hosts/frameworks?
+   - Yes: classify as `Kernel API`.
+2. Does the API expose host-neutral platform service behavior?
+   - Yes: classify as `Platform API`.
+3. Does the API bind to framework/host/plugin-specific behavior?
+   - Yes: classify as `Extension API`.
+4. Is the API only for app composition/template setup?
+   - Yes: classify as `Product API`.
+5. If none apply, keep internal and do not publish.
+
+## Kernel API Architectural Approval Rule
+
+- Any new public `Kernel API`, breaking `Kernel API` change, or semantic behavior change requires architecture approval before merge.
+- Approval must include:
+  - dependency-boundary impact statement,
+  - compatibility plan,
+  - rollback/fallback plan,
+  - linked governance evidence for release gates.

docs/docfx.json

@@ -37,6 +37,7 @@
           "articles/**/toc.yml",
           "demo/**.md",
           "demo/**/toc.yml",
+          "framework-capabilities.json",
           "toc.yml",
           "*.md"
         ]

docs/framework-capabilities.json

@@ -0,0 +1,66 @@
+{
+  "schemaVersion": "1.0",
+  "updatedAtUtc": "2026-03-26T00:00:00Z",
+  "capabilities": [
+    {
+      "id": "kernel.bridge.contracts",
+      "name": "Kernel Bridge Contracts",
+      "layer": "Kernel",
+      "status": "stable",
+      "supportTier": "LTS",
+      "owner": "runtime-core",
+      "breakingChangePolicy": "architecture-approval-required",
+      "compatibilityScope": "all-supported-hosts-and-framework-bindings",
+      "rollbackStrategy": "revert-kernel-contract-change-and-restore-previous-bridge-schema",
+      "observability": {
+        "traces": true,
+        "metrics": true,
+        "structuredErrors": true
+      },
+      "security": {
+        "boundaryValidated": true,
+        "defaultDeny": true
+      }
+    },
+    {
+      "id": "platform.shell.integration",
+      "name": "Platform Shell Integration",
+      "layer": "Platform Services",
+      "status": "stable",
+      "supportTier": "standard",
+      "owner": "platform-services",
+      "breakingChangePolicy": "release-gate-required",
+      "compatibilityScope": "all-supported-desktop-hosts",
+      "rollbackStrategy": "disable-shell-feature-flag-and-fallback-to-previous-platform-adapter",
+      "observability": {
+        "traces": true,
+        "metrics": true,
+        "structuredErrors": true
+      },
+      "security": {
+        "boundaryValidated": true,
+        "defaultDeny": true
+      }
+    },
+    {
+      "id": "extension.framework.adapter.react",
+      "name": "React Framework Adapter",
+      "layer": "Experience Extensions",
+      "status": "provisional",
+      "supportTier": "best-effort",
+      "owner": "framework-extensions",
+      "breakingChangePolicy": "compatibility-note-required",
+      "compatibilityScope": "react-adapter-consumers-on-supported-runtime-version",
+      "rollbackStrategy": "pin-previous-adapter-version-and-disable-new-extension-binding",
+      "observability": {
+        "traces": true,
+        "metrics": false,
+        "structuredErrors": true
+      },
+      "security": {
+        "boundaryValidated": true,
+        "defaultDeny": true
+      }
+    }
+  ]
+}

docs/index.md

@@ -29,6 +29,16 @@ All of this is type-checked at compile time, AOT-safe, and works the same on Win
 | Build an AI chat app with streaming | [AI Integration Guide](ai-integration-guide.md) |
 | Understand how the runtime works | [Architecture](articles/architecture.md) |
 
+## Platform Documents
+
+| Platform document | Purpose |
+|---|---|
+| [Product Platform Roadmap](product-platform-roadmap.md) | Positioning, strategy, layering model, capability contract, and P0-P5 roadmap |
+| [Architecture Layering](architecture-layering.md) | Dependency boundaries, API category rules, and kernel approval policy |
+| [Platform Status](platform-status.md) | Current governed platform snapshot |
+| [Release Governance](release-governance.md) | Stable release rules, gates, and promotion flow |
+| [Framework Capabilities](framework-capabilities.json) | Machine-readable capability registry baseline |
+
 ## Developer Resources
 
 | Resource | Description |

docs/platform-status.md

@@ -0,0 +1,18 @@
+# Platform Status
+
+## Current Snapshot
+
+This page is a controlled snapshot placeholder for platform status reporting.
+
+- Snapshot date: `TBD`
+- Channel status: `TBD`
+- Kernel stability: `TBD`
+- Extension readiness: `TBD`
+- Security gate status: `TBD`
+- Observability gate status: `TBD`
+- Release gate status: `TBD`
+
+## Notes
+
+- Replace `TBD` values through the release governance process.
+- Keep this document aligned with `release-governance.md` and capability registry updates.

docs/product-platform-roadmap.md

@@ -0,0 +1,74 @@
+# Product Platform Roadmap
+
+## Positioning
+
+Fulora is a product platform for shipping web-first applications as native desktop products with governed runtime contracts.
+
+## Strategic Direction
+
+- Keep the runtime core host-neutral and stable.
+- Push host, framework, and ecosystem change into explicit extension lanes.
+- Scale releases through machine-checkable governance artifacts.
+
+## Stable Core vs Extensions
+
+- Stable core: runtime kernel, bridge contracts, lifecycle invariants, security primitives, and diagnostics contracts.
+- Extensions: framework adapters, host-specific integration layers, optional plugins, and ecosystem templates.
+- Rule: extension velocity must not break stable core compatibility guarantees.
+
+## Layering Model
+
+- `Kernel` — cross-platform runtime contracts and execution invariants.
+- `Platform Services` — persistence, networking, shell integration, and policy enforcement abstractions.
+- `Experience Extensions` — framework adapters, plugins, and host-specific implementations.
+- `Product Surface` — templates, samples, and product applications consuming public contracts.
+
+## Capability Support Contract
+
+- Capabilities are registered in `framework-capabilities.json` with explicit lifecycle states.
+- Each capability declares owner, support tier, compatibility scope, and rollback strategy.
+- Breaking capability changes must follow each capability's `breakingChangePolicy`.
+- Architecture approval is mandatory for kernel-level changes and capability policies that explicitly require it.
+- release-gate evidence is required for all breaking capability changes.
+
+## Security Model
+
+- Validate all external inputs at the boundary.
+- Default-deny privileged operations; require explicit capability enablement.
+- Enforce secret isolation through environment/runtime providers only.
+- Apply security review gates before stable release promotion.
+
+## Observability Model
+
+- Every capability exposes baseline traces, metrics, and structured error events.
+- Release candidates must include machine-readable evidence for health, regression, and fallback readiness.
+- Observability artifacts are part of release governance, not optional diagnostics.
+
+## Release Governance
+
+- Stable channel changes require passing release gates defined in `release-governance.md`.
+- Kernel API and support-tier changes require architecture review sign-off.
+- Regression or policy gate failures block promotion until evidence is updated.
+
+## Developer Defaults
+
+- Safe-by-default templates and policy presets.
+- Stable APIs first; extension APIs are opt-in and explicitly marked.
+- New capabilities start as provisional until governance evidence is complete.
+
+## P0-P5 Roadmap
+
+| Phase | Focus | Outcome |
+|---|---|---|
+| P0 | Baseline platform contracts | Kernel and governance envelope established |
+| P1 | Layering enforcement | Dependency rules and API categories formalized |
+| P2 | Capability registry | Machine-readable capability metadata and support tiers |
+| P3 | Security + observability hardening | Required gates and evidence pipelines active |
+| P4 | Release automation | Stable release gates fully automated in CI |
+| P5 | Ecosystem scale-out | Extension lanes expand without core contract drift |
+
+## Documentation Governance
+
+- Platform docs are first-class governance artifacts and must stay DocFX-discoverable.
+- `docs/index.md` and `docs/toc.yml` must expose platform documents as top-level navigation.
+- Governance tests enforce presence and linkage for required platform pages.

docs/release-governance.md

@@ -0,0 +1,27 @@
+# Release Governance
+
+## Stable Release Rules
+
+1. Stable releases must preserve kernel compatibility contracts unless architecture approval is recorded.
+2. Capability lifecycle changes (`provisional` -> `stable`, deprecations, removals) require evidence updates in `framework-capabilities.json`.
+3. Security and observability controls are mandatory gates for promotion.
+4. Breaking capability changes must satisfy each capability's `breakingChangePolicy`, and release-gate evidence is mandatory.
+5. Any failed gate blocks release promotion until remediation evidence is published.
+
+## Release Gates
+
+| Gate | Required Evidence | Block Condition |
+|---|---|---|
+| Compatibility | Kernel/API diff review + approval record | Unapproved breaking change |
+| Capability Registry | Updated `framework-capabilities.json` entries | Missing or stale capability metadata |
+| Security | Security review report + boundary validation checks | Unresolved critical/high security findings |
+| Observability | Trace/metric/error baseline report | Missing baseline or regression beyond threshold |
+| Documentation | Top-level docs presence and link governance tests | Required platform docs not discoverable |
+| Quality | Targeted unit/integration/e2e governance test pass | Any required governance suite failing |
+
+## Promotion Flow
+
+1. Prepare candidate and refresh capability + status snapshots.
+2. Run governance and release gate checks.
+3. Approve or reject promotion with machine-readable evidence.
+4. Publish stable release only when all gates pass.