docs: consolidate experimental tracks into docs/experimental.md

README.md

@@ -276,13 +276,11 @@ Implemented:
   and unsupported program types.
 - Multi-artifact suite support for collections of BPF objects/programs.
 - JSON, Markdown, GitHub Action summary, and static compatibility-site output.
-- Experimental `virtme-ng` upstream-kernel lane.
-- Experimental Firecracker generated-initramfs backend.
-- Experimental runtime probe/select/fetch/agent flow for verified artifact
-  decisioning.
 
-Keep the runtime track framed as decisioning/proof unless you are running it in
-a controlled environment. Host loading stays disabled/gated by default.
+Experimental tracks (virtme-ng upstream lane, Firecracker backend, Web UI/API,
+runtime decisioning) are consolidated in
+[docs/experimental.md](docs/experimental.md) — kept as controlled proofs, not
+the project's focus.
 
 ## Install
 
@@ -508,27 +506,12 @@ make oss-evidence
 
 ## Backend Lanes
 
-QEMU/KVM distro profiles:
+QEMU/KVM distro profiles (the default and supported lane):
 
 ```bash
 make acceptance-dev-one
 ```
 
-Upstream-mainline smoke through `virtme-ng`:
-
-```bash
-make doctor-virtme
-make upstream-kernel-runnable
-make acceptance-upstream-kernel
-```
-
-Firecracker generated-initramfs proof:
-
-```bash
-make firecracker-preflight
-make acceptance-firecracker-dev-one
-```
-
 ARM64 smoke:
 
 ```bash
@@ -539,6 +522,10 @@ make acceptance-arm64-smoke
 The ARM64 workflow is wired, but real ARM64 VM compatibility proof requires a
 native ARM64 KVM runner.
 
+The experimental backends — upstream-mainline via `virtme-ng` and the
+Firecracker generated-initramfs proof — live in
+[docs/experimental.md](docs/experimental.md).
+
 ## GitHub Action
 
 This repository includes a composite action that runs `bpfcompat` and appends
@@ -583,59 +570,13 @@ Marketplace quick start:
 3. Use the action in CI to produce JSON, Markdown, and job-summary evidence.
 4. Treat exit code `2` as a compatibility gate failure.
 
-## Web UI / API
-
-The embedded UI is useful for demos and local inspection:
-
-```bash
-make serve
-```
-
-Open:
-
-- `http://127.0.0.1:8080/`
-- `http://127.0.0.1:8080/results`
-
-The API has `/api/v1/...` routes with legacy `/api/...` compatibility. For
-route details, see:
-
-- [`docs/openapi.yaml`](docs/openapi.yaml)
-- [`docs/api-web-ui.md`](docs/api-web-ui.md)
-- [`docs/env-reference.md`](docs/env-reference.md)
-
-Public demo mode can allow anonymous validation/read/runtime-select/fetch
-without enabling host execution. Runtime execute remains separately gated by
-`BPFCOMPAT_API_ENABLE_RUNTIME_EXECUTE` and an approval token.
-
-## Runtime Decisioning
-
-> **Status:** experimental, and not the project's current focus. Active
-> development centers on the CI compatibility workflow: suites, kernel
-> matrices, and reports. This track is kept as a controlled proof and may
-> change or be removed.
-
-The runtime path is experimental and should be treated as a controlled proof:
-
-```bash
-make runtime-selector-proof
-make runtime-delivery-proof
-```
-
-The safer product boundary is:
-
-1. validate artifact variants in CI/VMs;
-2. store signed compatibility metadata;
-3. probe a target host;
-4. select and fetch the best verified artifact;
-5. leave host loading to an explicitly approved local agent path.
-
-Relevant docs:
+## Web UI / API and Runtime Decisioning (experimental)
 
-- [`docs/runtime-selector-simulation.md`](docs/runtime-selector-simulation.md)
-- [`docs/production-runtime-agent-alpha.md`](docs/production-runtime-agent-alpha.md)
-- [`docs/runtime-execute-policy.md`](docs/runtime-execute-policy.md)
-- [`docs/security-model.md`](docs/security-model.md)
-- [`docs/threat-model.md`](docs/threat-model.md)
+Both tracks are kept as controlled proofs, not the product surface — the
+supported product is the **CLI + GitHub Action in CI**. The embedded demo UI
+(`make serve`), the HTTP API, and the frozen runtime probe/select/fetch/agent
+flow (host loading disabled/gated by default) are documented together in
+[docs/experimental.md](docs/experimental.md).
 
 ## Documentation Map
 
@@ -648,10 +589,8 @@ User guide — start here:
 - [`docs/kernel-quirk-library.md`](docs/kernel-quirk-library.md) — curated library of known-tricky vendor kernels (version ≠ feature support)
 - [`docs/profile-catalog.md`](docs/profile-catalog.md) — kernel/distro profiles and image maintenance
 - [`docs/image-pipeline.md`](docs/image-pipeline.md) — where images come from, integrity, adding profiles
-- [`docs/upstream-kernel-virtme-ng.md`](docs/upstream-kernel-virtme-ng.md)
-- [`docs/firecracker-backend.md`](docs/firecracker-backend.md)
 - [`docs/rhcos-openshift.md`](docs/rhcos-openshift.md) — RHCOS/OpenShift (Ignition boot, operator-supplied image)
-- [`docs/api-web-ui.md`](docs/api-web-ui.md)
+- [`docs/experimental.md`](docs/experimental.md) — virtme-ng lane, Firecracker backend, Web UI/API, runtime decisioning
 
 Reference matrices (real, reproducible artifacts):
 

docs/experimental.md

@@ -0,0 +1,80 @@
+# Experimental tracks
+
+Everything on this page works and has evidence behind it, but it is **not the
+project's focus**. Active development centers on the CI compatibility
+workflow: `.bpf.o` and command-mode validation, kernel matrices (including the
+[quirk library](kernel-quirk-library.md)), suites, and reports. The tracks
+below are kept as controlled proofs; interfaces may change or be removed.
+
+## virtme-ng upstream-kernel lane
+
+Boots **upstream mainline kernels** (kernel.org builds, not vendor images)
+through `virtme-ng` for boundary sweeps — useful to bisect exactly which
+upstream release introduced a feature, before checking which vendors backport
+it.
+
+```bash
+make doctor-virtme
+make upstream-kernel-runnable
+make acceptance-upstream-kernel
+```
+
+Details: [upstream-kernel-virtme-ng.md](upstream-kernel-virtme-ng.md).
+Note: command mode supports the default `vm` runner only.
+
+## Firecracker generated-initramfs backend
+
+An alternative microVM backend that builds a minimal initramfs instead of
+booting a cloud image. Faster per-boot, but it does not run *vendor* kernels —
+which is the product's differentiator — so it stays a proof.
+
+```bash
+make firecracker-preflight
+make acceptance-firecracker-dev-one
+```
+
+Details: [firecracker-backend.md](firecracker-backend.md).
+
+## Web UI / API
+
+An embedded UI and HTTP API for demos and local inspection of results. The
+supported product surface is the **CLI + GitHub Action in CI**; the UI is a
+convenience, not a SaaS.
+
+```bash
+make serve   # http://127.0.0.1:8080/ and /results
+```
+
+The API has `/api/v1/...` routes with legacy `/api/...` compatibility. Public
+demo mode can allow anonymous validation/read/runtime-select/fetch without
+enabling host execution; runtime execute remains separately gated by
+`BPFCOMPAT_API_ENABLE_RUNTIME_EXECUTE` and an approval token.
+
+Details: [api-web-ui.md](api-web-ui.md), [openapi.yaml](openapi.yaml),
+[env-reference.md](env-reference.md).
+
+## Runtime decisioning (probe / select / fetch / agent)
+
+A frozen proof-of-concept for *using* compatibility evidence at deploy time:
+probe a target host, select the best verified artifact variant, fetch it, and
+leave host loading to an explicitly approved local agent path. Host loading
+stays disabled/gated by default; treat the whole track as decisioning/proof
+unless you run it in a controlled environment.
+
+```bash
+make runtime-selector-proof
+make runtime-delivery-proof
+```
+
+The safer product boundary this track demonstrates:
+
+1. validate artifact variants in CI/VMs;
+2. store signed compatibility metadata;
+3. probe a target host;
+4. select and fetch the best verified artifact;
+5. leave host loading to an explicitly approved local agent path.
+
+Details: [runtime-selector-simulation.md](runtime-selector-simulation.md),
+[production-runtime-agent-alpha.md](production-runtime-agent-alpha.md),
+[runtime-execute-policy.md](runtime-execute-policy.md),
+[security-model.md](security-model.md), [threat-model.md](threat-model.md).