docs: bootstrap quick guide + wide findability pass

docs/content/docs/0.2.2/get-started/bootstrap.md

@@ -0,0 +1,9 @@
+---
+title: "Bootstrap until ready (custom setup)"
+description: "Guest readiness / bootstrap wait is documented for grain v0.4.0+."
+section: get-started
+---
+
+The **readiness protocol** and `--wait bootstrap` flow shipped in **grain v0.4.0**.
+
+Switch the docs version to **[v0.4.0](/docs/0.4.0/get-started/bootstrap/)** or **[main](/docs/main/get-started/bootstrap/)** for the walkthrough (cloud-init sample, `grain status` progress, and what “ready” means).

docs/content/docs/0.3.0/get-started/bootstrap.md

@@ -0,0 +1,9 @@
+---
+title: "Bootstrap until ready (custom setup)"
+description: "Guest readiness / bootstrap wait is documented for grain v0.4.0+."
+section: get-started
+---
+
+The **readiness protocol** and `--wait bootstrap` flow shipped in **grain v0.4.0**.
+
+Switch the docs version to **[v0.4.0](/docs/0.4.0/get-started/bootstrap/)** or **[main](/docs/main/get-started/bootstrap/)** for the walkthrough (cloud-init sample, `grain status` progress, and what “ready” means).

docs/content/docs/0.4.0/explain/agent-vs-ssh.md

@@ -1,9 +1,20 @@
 ---
-title: Agent vs SSH
+title: "Agent vs SSH (when each path is used)"
 description: When grain uses the guest agent, when it falls back to SSH, and why both exist.
 section: explain
+keywords:
+  - agent
+  - SSH
+  - grain-agent
+  - wait modes
+  - transport
+  - vsock
 ---
 
+{{< only-need href="guides/agent/" >}}
+Practical agent CLI/API how-to — this page is the decision model.
+{{< /only-need >}}
+
 ## Roles
 
 | Path | Strengths | Weaknesses |
@@ -42,4 +53,4 @@ Host → agent:
 - **Day-to-day automation:** agent (`x`, `cp`, `fs`, API exec)  
 - **Debugging a broken agent:** `grain sh --ssh` and `grain logs`  
 - **Images:** prefer `grain-ubuntu` so agent is already present  
-- **Security-sensitive tokens:** prefer [egress proxy](/docs/0.4.0/guides/proxy/) over writing secrets into the guest when possible  
+- **Security-sensitive tokens:** prefer [egress proxy](../guides/proxy/) over writing secrets into the guest when possible  

docs/content/docs/0.4.0/explain/architecture.md

@@ -1,9 +1,18 @@
 ---
-title: Architecture
+title: "Architecture (daemon, hypervisor, guest agent)"
 description: How the grain daemon, hypervisor, guest agent, and CLI fit together.
 section: explain
+keywords:
+  - architecture
+  - daemon
+  - hypervisor
+  - qemu
 ---
 
+{{< only-need href="get-started/concepts/" >}}
+Names and mental model without the full system diagram.
+{{< /only-need >}}
+
 ## Big picture
 
 ```text
@@ -58,4 +67,4 @@ SSH is excellent for interactive login and bootstrap. The agent is better for:
 - File and filesystem operations without scp edge cases  
 - Readiness probes (`/health`) independent of shell profiles  
 
-See [Agent vs SSH](/docs/0.4.0/explain/agent-vs-ssh/).
+See [Agent vs SSH](../agent-vs-ssh/).

docs/content/docs/0.4.0/explain/images-and-boot.md

@@ -1,9 +1,21 @@
 ---
-title: Images and boot
+title: "Images and boot (golden vs cloud)"
 description: Why base images matter, how golden boots differ from cloud images, and how to think about speed.
 section: explain
+keywords:
+  - images
+  - boot
+  - golden
+  - grain-ubuntu
+  - cloud-init
+  - bench
+  - bake
 ---
 
+{{< only-need href="guides/images/" >}}
+Pull, import, bake, and day-to-day image commands live in the Images guide.
+{{< /only-need >}}
+
 ## Catalog at a glance
 
 | ID | Role |
@@ -44,4 +56,4 @@ just build && just agent-linux
 # or CI: ./scripts/ci-bake-golden.sh
 ```
 
-See [Images guide](/docs/0.4.0/guides/images/).
+See [Images guide](../guides/images/).

docs/content/docs/0.4.0/explain/parity.md

@@ -1,9 +1,20 @@
 ---
-title: "Product surface"
+title: "Product surface (what’s done / experimental)"
 description: "What grain implements for local Linux microVM sandboxes."
 section: explain
+keywords:
+  - parity
+  - product surface
+  - status
+  - roadmap
+  - features
+  - experimental
 ---
 
+{{< only-need href="get-started/quickstart/" >}}
+Use the product first — this page is a capability checklist.
+{{< /only-need >}}
+
 grain’s local microVM product surface as of the v0.2 line.
 
 ## Complete for local sandboxes

docs/content/docs/0.4.0/explain/readiness.md

@@ -1,12 +1,24 @@
 ---
-title: Readiness protocol
-description: Contract for custom images and bootstrap authors so grain can report progress and only mark a sandbox ready when you say so.
+title: "Readiness protocol (custom images & bootstrap)"
+description: "Full contract: guest readiness files, agent health fields, wait=bootstrap, and when a sandbox is considered ready."
 section: explain
+keywords:
+  - readiness
+  - bootstrap
+  - wait bootstrap
+  - userdata_ran
+  - custom image
 ---
 
+{{< only-need href="get-started/bootstrap/" >}}
+Paste cloud-init, run `grain new --wait bootstrap`, and watch `grain status` — without reading the full contract first.
+{{< /only-need >}}
+
 Custom images and long first-boot setup need a **shared contract** with grain: how to report *what is happening*, when the sandbox is **done**, and when it **failed**—so `grain new`, create streams, `grain health`, and `grain status` stay accurate.
 
-This page is that contract. **Sandbox recipe files** (declarative create + bootstrap steps) are a later layer that *implements* this protocol; stock goldens already satisfy a compatible subset without changes.
+**Ready means:** the VM is up, the guest agent is healthy, and bootstrap completed with **zero failures** (`state=ready`). Failure or timeout does **not** report ready.
+
+This page is the full contract. Stock goldens already satisfy a compatible subset without custom files. **Sandbox recipe files** (declarative create + bootstrap steps) are a later layer that *implements* this protocol.
 
 ## Goals
 
@@ -179,7 +191,7 @@ Use **`--wait bootstrap`** only when your image or userdata implements this prot
 
 ## See also
 
-- [Guest agent](/docs/0.4.0/guides/agent/)
-- [Profiles and presets](/docs/0.4.0/guides/profiles/)
-- [Images and golden boots](/docs/0.4.0/guides/images/)
-- [CLI](/docs/0.4.0/reference/cli/)
+- [Guest agent](../guides/agent/)
+- [Profiles and presets](../guides/profiles/)
+- [Images and golden boots](../guides/images/)
+- [CLI](../reference/cli/)

docs/content/docs/0.4.0/explain/security.md

@@ -1,9 +1,21 @@
 ---
-title: Security model
+title: "Security model (trust, proxy, secrets)"
 description: What grain isolates, what it trusts, and how proxy and secrets fit.
 section: explain
+keywords:
+  - security
+  - isolation
+  - trust
+  - API token
+  - secrets
+  - proxy
+  - multi-tenant
 ---
 
+{{< only-need href="guides/remote-host/" >}}
+Team/shared host setup (token, bind, firewall) is covered in Remote sandbox host.
+{{< /only-need >}}
+
 ## What grain gives you
 
 - **Hardware virtualization boundary** between host and guest (QEMU/HVF or Firecracker/KVM)  
@@ -49,7 +61,7 @@ Running grain on a team machine so developers create sandboxes remotely is a sup
 - Remote CLI: `GRAIN_API` / `--api` + `GRAIN_TOKEN`  
 - Resource caps; published ports stay on host loopback  
 
-Full guide: [Remote sandbox host](/docs/0.4.0/guides/remote-host/).
+Full guide: [Remote sandbox host](../guides/remote-host/).
 
 ## Images
 

docs/content/docs/0.4.0/get-started/_index.md

@@ -1,4 +1,15 @@
 ---
-title: Get Started
+title: Get started
+description: "Install grain, open a first sandbox, or run custom bootstrap until ready."
 section: get-started
 ---
+
+Short paths into grain:
+
+| Guide | When to use it |
+|-------|----------------|
+| [Quick start](quickstart/) | Install → config → shell in a few minutes |
+| [Install](install/) | Platforms, install options, QEMU |
+| [First sandbox](first-sandbox/) | Interactive demo + guided real create |
+| [Bootstrap until ready](bootstrap/) | Custom apt/scripts before create reports ready |
+| [Core concepts](concepts/) | Daemon, images, agent, ephemeral vs persistent |

docs/content/docs/0.4.0/get-started/bootstrap.md

@@ -0,0 +1,119 @@
+---
+title: "Bootstrap until ready (custom setup)"
+description: "Run packages or a setup script before grain says the sandbox is ready — with status you can watch."
+section: get-started
+keywords:
+  - bootstrap
+  - readiness
+  - userdata
+  - apt
+  - setup script
+  - wait bootstrap
+  - custom image
+---
+
+**Goal:** create a VM, run your install/setup steps, and only get a shell (or next command) when those steps finished **with zero failures**.
+
+Stock `grain-ubuntu` is already “ready” when the agent is up. This page is for **custom** first-boot work (apt, scripts, image authors).
+
+Deep reference: [Readiness protocol](../explain/readiness/).
+
+---
+
+## 1. What “ready” means here
+
+A sandbox is ready when:
+
+1. The **VM is up** and the **guest agent** is healthy, and  
+2. Your **bootstrap** finished successfully (`state=ready`), with **no failed steps**.
+
+If bootstrap fails, create errors and the VM is **left running** so you can inspect logs and fix.
+
+---
+
+## 2. Minimal path (cloud-init)
+
+Save this as `bootstrap.yaml` on the **host**:
+
+```yaml
+#cloud-config
+runcmd:
+  - |
+    set -euo pipefail
+    dir=/var/lib/grain/readiness
+    mkdir -p "$dir" /var/lib/grain
+
+    echo running >"$dir/state"
+    echo packages >"$dir/phase"
+    echo "installing git" >"$dir/message"
+
+    export DEBIAN_FRONTEND=noninteractive
+    apt-get update -qq
+    apt-get install -y -qq git
+
+    echo ready >"$dir/state"
+    echo my-stack >"$dir/ready_name"
+    date -u +"%Y-%m-%dT%H:%M:%SZ" >"$dir/updated_at"
+    touch /var/lib/grain/userdata-ran
+```
+
+Create and **wait for bootstrap**:
+
+```bash
+grain up
+grain image pull grain-ubuntu   # or your custom image
+grain new --userdata-file ./bootstrap.yaml --wait bootstrap -n lab
+```
+
+While it runs you should see create progress mention bootstrap / your `message`. When it returns successfully, bootstrap completed with no failures.
+
+```bash
+grain status lab
+grain health lab
+grain sh lab
+```
+
+---
+
+## 3. Report progress from a script
+
+Inside the guest (or in runcmd), use the same files — or copy [scripts/grain-ready-report.sh](https://github.com/cxdy/grain/blob/main/scripts/grain-ready-report.sh) into the image:
+
+```bash
+grain-ready-report running packages "apt-get install …"
+# … work …
+grain-ready-report ready
+# on error:
+# grain-ready-report failed "" "setup.sh exit 1"
+```
+
+Files live under `/var/lib/grain/readiness/` (`state`, `phase`, `message`, `error`, …).
+
+---
+
+## 4. Watch status
+
+```bash
+grain status lab
+# lab  status=running  …  readiness=running  phase=packages  "installing git"
+
+grain health lab   # full JSON including readiness
+```
+
+---
+
+## 5. Common failures
+
+| Symptom | Check |
+|---------|--------|
+| Create hangs on bootstrap | Guest never wrote `state=ready` — look at `grain logs -f lab` |
+| Create errors, VM still there | Bootstrap wrote `state=failed` or timed out — `grain status` / logs, then `grain rm lab` |
+| Stock image, no custom setup | Use default wait (`agent` for goldens); you don’t need this guide |
+
+---
+
+## Next
+
+- Full contract (states, wait modes, agent API): [Readiness protocol](../explain/readiness/)  
+- Named create defaults: [Profiles & presets](../guides/profiles/)  
+- Baking faster images later: [Images](../guides/images/)  

docs/content/docs/0.4.0/get-started/concepts.md

@@ -1,9 +1,22 @@
 ---
-title: Core concepts
+title: "Core concepts (daemon, images, agent)"
 description: A short glossary of daemon, images, sandboxes, the guest agent, and how they fit together.
 section: get-started
+keywords:
+  - daemon
+  - images
+  - sandbox
+  - guest agent
+  - ephemeral
+  - persistent
+  - hypervisor
+  - API
 ---
 
+{{< only-need href="get-started/quickstart/" >}}
+Hands-on install → create → shell without the glossary first.
+{{< /only-need >}}
+
 ## Daemon
 
 `grain up` starts a local control plane that owns VM metadata, disks, and the API (unix socket and optional TCP). CLI commands talk to this process — not directly to QEMU.
@@ -40,12 +53,11 @@ Automation can use:
 - Unix socket: `~/.grain/grain.sock`  
 - TCP: `http://127.0.0.1:7474` (default config)  
 - OpenAPI: `GET /openapi.yaml`  
-- SDKs: [Go](/docs/0.4.0/reference/go-sdk/) · [TypeScript](/docs/0.4.0/reference/typescript-sdk/) · [Python](/docs/0.4.0/reference/python-sdk/)  
-
+- SDKs: [Go](../../reference/go-sdk/) · [TypeScript](../../reference/typescript-sdk/) · [Python](../../reference/python-sdk/)  
 
 Optional Bearer auth: set `api_token` in config and `GRAIN_TOKEN` in the environment.
 
-For a **shared remote machine** (daemon as a service, teammates over SSH or SDKs), see [Remote sandbox host](/docs/0.4.0/guides/remote-host/). The CLI uses the **local unix socket** on the machine where it runs; remote automation uses the TCP API or an SSH session on the host.
+For a **shared remote machine** (daemon as a service, teammates over SSH or SDKs), see [Remote sandbox host](../../guides/remote-host/). The CLI uses the **local unix socket** on the machine where it runs; remote automation uses the TCP API or an SSH session on the host.
 
 ## Hypervisors