CON-1584: Surface host account and CLI/API/SDK docs

[jjziets]

Important

Reviewer focus: use the eight shared decisions in REVIEW-QUESTIONS.md plus the page-specific Jira gates shown by the local port 4000 review panel. Start with CON-1187 and CON-1509.

1 · IA approval · 2 · Review mechanics · 3 · Pricing · 4 · Machine errors · 5 · Installer screenshot · 6 · Supported Hardware · 7 · Host Teams · 8 · Persona scope

Summary

• Reworks the Host documentation into a lifecycle-oriented IA with account/security, installation, verification, operations, business, CLI/API/SDK, and troubleshooting guidance.
• Adds a local review tool on port 4000 with selection-anchored comments, page notes, Jira provenance, and page-scoped blocker questions. Save JSON is the default restorable backup for every page/reviewer; Import JSON merges it without overwriting newer items, while CSV (Jira) and Markdown remain secondary exports. Port 3000 remains the plain documentation preview.
• Adds Host account/agreement and security guidance plus a Host CLI/API/SDK bridge to the canonical references.
• Reconciles the generated Verification / Self-test reference from docs PR CON-1513/CON-1515: Auto-generate Host Self-Test Reference docs #145 into this PR without replacing the later Host IA, persona metadata, and human-reviewed troubleshooting guidance.
• Adds a source-driven generator and CI workflow for the Self-test reference. It checks relevant PRs, runs weekly, supports manual source refs and optional repository dispatch, and fails when the committed MDX drifts from Vast CLI or Self-Test metadata.
• Documents merged Self-Test behavior: actual-versus-required checks, stable failure codes, runtime stages, diagnostic bundles, vastai dump-logs, the B300/very-high-VRAM cap, and older-GPU CUDA image selection.

Corrected Jira traceability

Full evidence matrix and the CON-1519 bundle-ownership decisions: REVIEW-TRACEABILITY.md.

• CON-1517 is already implemented in this branch. Commit 0cb28ff is in PR 185 and distributed the human-reviewed common-host answers across 33 canonical Host pages. /host/common-host-questions is intentionally a routing index, not the full source-review artifact.
• CON-1510 is implemented in merged runtime code and represented here. Vast CLI PR [Preview] OpenAPI spec from vast PR #5002 #408 and Self-Test PR Fix redirect #2 provide extractable actual/required diagnostics, explanations, stable errors, remediation, and structured events; this PR now renders them from source.
• CON-1513 is implemented here. scripts/generate_self_test_reference.py and .github/workflows/self-test-reference.yml provide generation and drift detection. The passing verify-self-test-reference check proves the repository can read the private vast-ai/self-test source.
• CON-1515 is now integrated here. Draft docs PR CON-1513/CON-1515: Auto-generate Host Self-Test Reference docs #145 is no longer a dependency for its generator, workflow, or complete reference.
• CON-1583, CON-1519, CON-1502, and CON-1419 docs gaps are represented here. The page explicitly covers the ~2 TB B300 cap, dump-logs and opt-in host-local artifacts, the rebuilt image/platform matrix, and pre-Volta/Volta image-selection rules.

Remaining Jira gates

The port 4000 panel is the page-by-page source of truth. The highest-impact remaining questions are:

• Product-approved setup-page machine-installation-key wording, dedicated-host-account guidance, and stale/wrong-account escalation (CON-1584).
• Host Teams migration, registration permission, undefined install-command, earnings/payout, and billing_read behavior (CON-1581).
• Machine-error catalog completeness, UI/field mapping, clearing/TTL behavior, and public-vs-internal scope (CON-1531).
• Exact failed-port/protocol evidence and authoritative offline-vs-hidden state, which still require backend/API support (CON-1514).
• Authoritative verification queue and wait-time wording (CON-1515).
• Diagnostic-bundle intake location, accountable owner, retention/access policy, first-line triage, and subsystem escalation (CON-1519).

Stack context

This PR includes the stacked work from:

• CON-1518/CON-1077: Host docs IA + headless handover #153 — CON-1518/CON-1077 Host docs IA + headless handover
• CON-1581: Draft Host Teams page #156 — CON-1581 Host Teams draft

Because the upstream repository does not expose PR #156's head as an available upstream base branch, this PR targets main. The narrow CON-1584-only comparison remains available in the fork stack at jjziets#2.

Validation

• npm run test-review-context — 9/9 passing, including multi-reviewer JSON round-trip, newest-item-wins, anchor preservation, and atomic invalid-import rejection
• npm run check-persona-chips — 39 authored Host pages in sync
• Self-test generator rerun twice from clean vast-ai/vast-cli@d4316fb and vast-ai/self-test@6f93fc4 sources — byte-for-byte idempotent
• actionlint .github/workflows/self-test-reference.yml
• node --check review-server.mjs
• git diff --check
• Browser dogfood at localhost:3000/host/self-test-reference: generated content and legacy anchors render; no review overlay
• Browser dogfood at localhost:4000/host/self-test-reference: Jira issues render and only the authoritative queue/wait-time question remains
• mint broken-links still reports the branch's existing 100 API-reference/notification links; none are introduced by the changed files

Review locally with inline commenting

These steps work on macOS, Linux, and Windows. Install Git, the GitHub CLI, and Node.js 18+ first.

1. Clone and prepare the PR

Use Terminal on macOS/Linux or PowerShell/Windows Terminal on Windows:

gh repo clone vast-ai/docs vast-docs-pr185
cd vast-docs-pr185
gh pr checkout 185
npm ci

2. Start the plain docs preview — terminal 1

Open a terminal in the parent folder:

cd vast-docs-pr185
npm run dev -- --no-open

Leave it running. It serves the plain docs preview on port 3000.

3. Start the review overlay — terminal 2

Open a second terminal in the same parent folder:

cd vast-docs-pr185
node review-server.mjs

Leave it running. It serves the review tool on port 4000.

Open http://localhost:4000/host/hosting-overview.

• Select exact page text and choose Comment on selection, or use + Page note for page-level feedback.
• Open the review panel to see the relevant Jira epics/issues and unresolved questions for the current page.
• Feedback stays in review-feedback/ inside the checkout.
• At http://localhost:4000/__review__/, use Save JSON for the complete restorable backup and Import JSON to rebuild feedback. Imports cover all pages/reviewers and keep the newer timestamp for duplicate item IDs. CSV (Jira) and Markdown remain secondary exports.

If Mintlify selects port 3001 because port 3000 is occupied, start the review server with node review-server.mjs --target http://localhost:3001.

[jjziets]

Branch updated (4bd24b5 merge + 86bfa16 fixes) — closed the gaps found by the CON-1518 IA intent audit:

• Deep-link anchors: every error family in Self-Test Reference now has its own anchor (#reliability, #auth-error, #direct-ports, #bandwidth, #insufficient-resources, #system-requirements) — ready for the CLI error-string deep-linking follow-up.
• Threshold single-sourcing: fixed the 7 GiB→7 GB drift in How to Self-Test (CLI gate is decimal GB) and pointed it at Verification Stages as the canonical gate list.
• Canonical entries: nccl_failed and machine not rentable now name Self-Test Reference as canonical from Machine Errors, removing duplicate retrieval targets.
• Install failures: new anchored identify-4xx section in Installing Host Software with concrete root causes (fresh-key guidance per Hanran's corrections).
• Journey seams: Hosting Overview ↔ Quickstart now cross-link; Quickstart gained step 8 (Start earning); sidebar disambiguation: "Account & Agreement" vs "Hosting Agreement".
• Rebase: merged main — Host Notifications is slotted into Operate with persona chips; Verify & List reordered so Optimize Your Earnings follows the listing tasks.

Zero new broken links (mint broken-links count unchanged); all edited pages smoke-tested in the local preview. Full audit: CON-1518 Jira.