Skip to content

docs: bootstrap quick guide + wide findability pass - #21

Merged
cxdy merged 1 commit into
mainfrom
docs/findability-bootstrap-guides
Jul 29, 2026
Merged

docs: bootstrap quick guide + wide findability pass#21
cxdy merged 1 commit into
mainfrom
docs/findability-bootstrap-guides

Conversation

@cxdy

@cxdy cxdy commented Jul 29, 2026

Copy link
Copy Markdown
Owner

Summary

Makes grain docs easier to use for people who both author custom images/bootstrap and consume sandboxes (same person today):

  1. Quick guide under Get started — new /get-started/bootstrap/ walkthrough: ready = VM up + agent healthy + bootstrap finished with zero failures, cloud-init sample, grain-ready-report, status/health. Full contract stays on Readiness protocol.
  2. Keep Explain/Guides verbose — heavy pages get an If you only need… callout that points at the short path; body depth unchanged.
  3. Wide findability — descriptive titles, keywords for search, better ranking (title/keywords/section), search placeholder/empty-state hints, section chips in results.
  4. Link hygiene — replace hardcoded /docs/0.2.2/ paths on main with relative in-tree links so versioned trees stay correct.
  5. Publish — refreshed 0.4.0 from main; thin bootstrap stubs on 0.2.2 / 0.3.0 so the shared nav item does not 404.

Nav: Learn → Bootstrap until ready.

Test plan

  • hugo --minify in docs/ (213 pages)
  • Spot-check /docs/0.4.0/get-started/bootstrap/ and only-need boxes on agent / readiness / MCP
  • Search for bootstrap, MCP, act — expect get-started / MCP hits near top with keywords
  • Version switcher: 0.2.2/0.3.0 bootstrap stub → link to 0.4.0; 0.4.0/main full guide
  • Sidebar: single active item; Bootstrap listed under Learn

Add get-started/bootstrap for custom setup until ready (VM + agent +
bootstrap with zero failures), keep the readiness protocol as the deep
dive, and make the rest of the docs easier to land on:

- descriptive titles and search keywords across guides/explain/MCP/reference
- "If you only need…" shortcode pointing short paths at get-started
- search ranks titles/keywords higher and surfaces section chips
- relative in-tree links (no more hardcoded /docs/0.2.2/ on main)
- publish updated tree to 0.4.0; stub bootstrap pages on 0.2.2/0.3.0 so nav works
@github-actions

Copy link
Copy Markdown

Coverage (lines): 80% ✅ — minimum 75%

commit 14f99a2 · 11551/14482 lines · cmd/* excluded

Coverage report by file (80% overall — click to expand)
File Coverage Missing
All files 80%
internal/sshkey/sshkey.go 68% 33-35 38-41 46-48 50-52
internal/mcp/tools.go 69% 389-391 393-395 401-406 427-429 463-468 471-476 481-484 514-516 524-526 531-533 538 544…
internal/cli/cp.go 70% 80-82 88 136-139 141-143 145 169-171 179-181 188-190 200-202 205-207 209-211 240-242 25…
internal/update/update.go 71% 85-87 89-91 93-98 112-114 135-137 169-171 195 220-222 224-226 228-230 240-245 247-249 2…
internal/mcp/connect.go 71% 56-58 68-72 79-81 83-85
internal/daemon/daemon.go 73% 29-31 59-62 90-92 100-102 107-109 118-130
internal/cli/stats.go 73% 23-25 27-29 40-42
internal/proxy/store.go 73% 34-36 61 64-66 73-75 77-79 88-90 110-112 121-123 165 168-171 177-179 181-183 192-194 19…
internal/store/store.go 73% 21-23 39-41 43-45 47-49 61 74-78 107-109
internal/image/catalog.go 74% 69-79 119-132
internal/cli/root.go 74% 93-95 97-99 175-177 184-189 200-202 207-209 213-215 223-228 231-236 243-250 252 254-256…
internal/agent/server.go 75% 92-94 96-98 104 216-218 305-311 344-346 350-353 355-358 400-409 421-433 483-486 488-491…
internal/cli/image_doctor.go 75% 34-38 53-58 62-71 74-76 102-104 150-152 157 161-163 174-176 181-187 190-192 203-206 209…
internal/manager/manager.go 75% 88-90 185-187 203-207 209-211 217-219 240-242 254-260 265-270 358-362 389-391 439-441 4…
internal/cli/progress.go 75% 43-49 51-54 63-65 103-111 113-116 131-133 169-174 201-203
internal/mcp/http.go 75% 33-35 40-42 72-74 84-88
internal/cli/fwd.go 76% 46-48 127-129 131-133 136-138 143-145 149-151 189-192 207-209 211-213 221-226 233-235 2…
internal/cli/uninstall.go 76% 33-36 63-70 72-74 79-81 88-90 110-112 116-117 140-142
internal/presets/presets.go 76% 31-33 40-42 45-46 49-50 62-64
internal/secrets/store.go 76% 58-60 84-88 101 119-121 148-150 153-159 171-173 197-203 217-219 235 247-249 259 273-275…
internal/cli/proxy.go 76% 43-45 80-82 91-93 96-99 104-105 116 129-131 133-135 141-143 155-159 164 174-176 183-185…
internal/cli/logs.go 77% 37-39 44-46 52 55-59 84-86 104-109 113 123 127-128 141-143 158-160 182 209-211 219-221
internal/agent/client.go 77% 55-57 78-80 82-84 86-89 91-93 100-102 125-127 146-148 155-157 178-180 199-201 244-246 2…
internal/cli/mcp.go 78% 38-40 50-52 56-58 69-71 81
internal/hypervisor/qemu.go 78% 33-35 50-52 66-68 72-74 79-81 88-90 95-97 155-162 168-170 174-184 186-189 196-198 202-2…
internal/image/pull.go 78% 106-108 136 157-159 170-172 175-177 188-190 201-205 214-218 220-223 237-239 262-264 267…
internal/api/api.go 78% 112-115 215-219 228-251 273-275 398-401 412-415 427-429 437-439 500-503 512-514 519-522…
scripts/mcp-handshake.go 78% 16-20 42-44 60-62
internal/hypervisor/disk_local.go 79% 38-40 45-47 73-76 78-80 112-114 123
internal/mcp/host.go 79% 68-72 79-81 87-92 115
internal/proxy/server.go 79% 65-67 114-118 124-127 168-170 173-175 178-181 191-194 198-202 205-208 222-224 227-233 2…
internal/hypervisor/virtiofs.go 80% 28-30 32-34 64-66 104-106 111-114 119-121 126-129 170-172 190-192 199-201
internal/cli/fs.go 80% 60-62 87-89 91-93 127-129 131-133 146-148 150-152 179-181 183-185 192-194 214-216 218-2…
internal/cli/volume.go 82% 24-29
internal/guest/sshwait.go 83% 32-34 39-41 58
internal/hypervisor/fsdev.go 83% 34-40
internal/agent/stats.go 83% 62-64 71-73 80-82 116-118 125-127
internal/hypervisor/qmp.go 84% 50-52 62-69 93-95 97-99
internal/api/client.go 85% 66-68 74-76 97-99 105-107 154-156 169-171 190-192 211-213 228-230 245-247 262-264 279-2…
internal/hypervisor/firecracker.go 86% 142-144 164-166 171-173 208-213 229-231 238-239 242-246 249-250 253-254 257-259 268-277…
internal/agent/readiness.go 87% 27-29 33 57-59
internal/cli/act.go 87% 97-99 101-103 112-116 119-121 143-145 150-152 166-168 209-211 218-220 254-256 337-339
internal/guest/agentdeploy.go 87% 59-61 65-67 75-77
internal/cli/update.go 88% 42-44 131-135 140-142 177-178 185-187
internal/cloudinit/seed.go 90% 64-69 93
internal/config/config.go 91% 325-327 345-347 363-365 409 420-422 450-452 459-461 471-473
internal/hypervisor/transport.go 91% 69-71
internal/agent/binary.go 91% 58-59 65-66
internal/hostbin/hostbin.go 91% 28-30
internal/cli/preset.go 92% 36-38
client/client.go 93% 96-98 186-188 194-196 218-220 226-228 274-276 448-450 508-510 517-519 567-569 610-612 6…
internal/hypervisor/netdev.go 93% 43-45
scripts/handshake_lib.go 93% 54-56
internal/cli/agent_dial.go 95% 44-48 150 159
internal/cloudinit/merge.go 96% 124-126 180-182 238-240
internal/agent/dial.go 97% 82-83
internal/cli/secret.go 97% 56-58 225-227
internal/cli/profile.go 97% 28-30
internal/hypervisor/mock.go 97% 161-163

@cxdy
cxdy merged commit e46d1d7 into main Jul 29, 2026
3 checks passed
@cxdy
cxdy deleted the docs/findability-bootstrap-guides branch July 29, 2026 06:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant