docs(gpu): explain CDI upgrade requirements

Signed-off-by: Evan Lezar <elezar@nvidia.com>

Author: elezar

docs/how-it-works/sandboxes/runtimes.mdx

@@ -136,6 +136,14 @@ requirements from CDI specs before launching agent processes. Non-GPU Docker
 sandboxes do not receive the CDI context, spec mounts, or CDI-derived policy
 changes.
 
+When upgrading from a version that created Docker GPU sandboxes without CDI spec
+projections, recreate those sandboxes. Starting an older container with resource
+admission enabled fails because its required projections are missing. Before
+creating a replacement, configure Docker to report only existing CDI spec
+directories. If a selected spec has ordinary writable mounts, list each regular
+file destination exactly in `filesystem_policy.read_write`; an ancestor grant
+does not satisfy this check, and writable directory mounts are rejected.
+
 ### Docker Corporate Proxy Egress
 
 For proxy-required networks, the Docker driver accepts `https_proxy`,

skills/debug-openshell-cluster/SKILL.md

@@ -321,6 +321,8 @@ Common findings:
 
 - A CDI-enabled Docker workload fails during filesystem validation: inspect the destination paths in the selected CDI specs and their targets inside the workload image. Shared-library parent directories must not alias broad roots such as `/`, `/usr`, or `/dev`; device destinations must resolve to character or block devices, and ordinary writable mounts must be single files explicitly listed in policy `read_write`. Check both initial launch and later exec failures. CDI target validation, ruleset construction, and enforcement failures are fatal even with best-effort Landlock compatibility; unrelated authored paths retain their configured opening behavior; correct the spec or image paths rather than relaxing the policy.
 
+- An existing Docker GPU sandbox fails restart with `CDI spec projection is missing`: recreate the sandbox so the driver can add the protected CDI spec projections. Containers created before CDI projection support do not have the required mounts.
+
 - Docker rejects a CDI spec-directory bind: every directory reported in `docker info --format '{{json .CDISpecDirs}}'` must exist on the daemon host. OpenShell uses structured binds that reject missing sources and do not create directories or relabel existing ones. Configure Docker to report only existing CDI spec directories. On SELinux hosts, ensure the host policy permits containers to read them without automatic relabeling. The projections are private to the trusted runtime under `/.openshell/cdi-specs`; the mandatory baseline prevents agent access even with broad authored grants.
 - CDI spec projection admission fails: inspect the workload container's `HostConfig.DeviceRequests` and `Mounts`. Each daemon-discovered CDI spec directory must appear at its assigned `/.openshell/cdi-specs/<index>` destination as a read-only bind with private propagation and the expected host source. Missing, changed, duplicate, and additional unrelated bind mounts are rejected with admission enabled. Correct the projection or runtime configuration; do not disable resource admission for GPU workloads.
 - CDI writable mount validation fails despite omitted options or `ro` in the spec: OpenShell checks effective mount flags inside the workload. Original directory destinations are also checked for writable submounts. Ordinary writable destinations must be single regular files with exact entries in policy `read_write`; expanded shared-library parents are not treated as original directory mounts.