docs: document .awf-home prerequisite for Cloud Hypervisor allowWrite (#7670)

The allowWrite guidance told readers to add `/workspace/.awf-home` to
`filesystem.allowWrite` when a narrowed policy makes the guest home
read-only, but that remedy fails as written.

The Cloud Hypervisor workspace export is backed by the host workspace
directory itself, and nothing in the Cloud Hypervisor path creates
`.awf-home` on the host before planning. Without a policy this is
invisible: the export is writable and the directory is created at
runtime. Under a narrowing policy the export root is staged read-only,
so runtime creation is no longer possible, and because the planner only
accepts paths that already exist, naming it in `allowWrite` throws:

  filesystem.allowWrite path is not an existing path within a writable
  Cloud Hypervisor export: /workspace/.awf-home

Document the missing prerequisite in both the Cloud Hypervisor
foundation doc and the config spec: create the host directory
`$GITHUB_WORKSPACE/.awf-home` before AWF starts, then list the guest
path. Include a short setup example and state plainly that AWF does not
auto-create or exempt the guest home, since either would widen the
boundary implicitly or reintroduce an always-writable internal mount.

Documentation only; no behaviour, existing-path, or narrowing semantics
change.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 248b577f-2e6f-4e03-90bc-96c75c0d395e

Author: lpcox

docs/awf-config-spec.md

@@ -106,8 +106,14 @@ where it is enforced by the host mount tree that backs each virtio-fs export
 Cloud Hypervisor has no always-writable internal mounts, so every export it
 publishes is subject to the policy, including `/tmp/gh-aw` and the guest home
 directory at `/workspace/.awf-home`; paths not covered by `allowWrite` become
-read-only. AWF rejects `filesystem.allowWrite` with the sbx
-runtime and with Docker-in-Docker agent execution.
+read-only. Because every listed path MUST already exist, and because AWF MUST
+NOT auto-create or exempt the guest home, a Cloud Hypervisor workload that needs
+a writable home MUST have the backing host directory
+`$GITHUB_WORKSPACE/.awf-home` created before AWF starts and MUST then list the
+guest path `/workspace/.awf-home` in `allowWrite`; otherwise planning fails
+because the path does not exist within a writable export. AWF rejects
+`filesystem.allowWrite` with the sbx runtime and with Docker-in-Docker agent
+execution.
 
 ### 4.2 Cloud Hypervisor microVM preview
 

docs/cloud-hypervisor-foundation.md

@@ -357,6 +357,39 @@ One consequence is worth stating plainly: the guest `HOME` is
 directory read-only. That is the policy working as specified, not an oversight;
 add the home path to `allowWrite` if the workload needs it.
 
+Doing so has a prerequisite. The workspace export is backed by the host
+workspace directory itself (`$GITHUB_WORKSPACE`, falling back to the current
+working directory), and nothing in the Cloud Hypervisor path creates
+`.awf-home` on the host before planning. That is harmless without a policy,
+because the export is writable and the directory is simply created at runtime.
+Under a narrowing policy the export root is staged read-only, so it can no
+longer be created at runtime — and the planner only accepts paths that already
+exist, so naming it in `allowWrite` fails too, with a single-line error:
+
+```text
+filesystem.allowWrite path is not an existing path within a writable
+Cloud Hypervisor export: /workspace/.awf-home
+```
+
+AWF deliberately does not auto-create or exempt the guest home: doing either
+would either widen the boundary implicitly or reintroduce an always-writable
+internal mount, both of which contradict the narrowing semantics above. Create
+the host directory before AWF starts, then list the guest path:
+
+```bash
+mkdir -p "$GITHUB_WORKSPACE/.awf-home"
+```
+
+```yaml
+filesystem:
+  allowWrite:
+    - /workspace/.awf-home
+```
+
+That yields a `selective` workspace plan — host root staged `ro`, guest mount
+`rw`, one directory overlay at `.awf-home` — leaving the rest of the workspace
+read-only.
+
 ## Limitations
 
 The preview rejects configurations that weaken or conflict with its boundary,