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.

[jjziets]

Host Docs QA evidence

I completed a reproducible QA pass for the Host Docs at source commit 5088d76. The reports and verification scripts are published in evidence commit 1566df6.

Start here: Host Docs QA summary

Supporting evidence:

• Full command, error, threshold, and behavior-claim inventory
• CLI registry verification
• Inventory generator
• CLI verifier

Current results:

• 72 Host pages plus 33 imported Host snippets examined.
• 474 unique verification targets across 529 occurrences.
• 123/123 fenced Bash snippets passed non-executing syntax checks.
• All 181 documented CLI occurrences are accepted by the current clean Vast CLI registry; zero actionable CLI defects remain.
• The confirmed vast/vastai, Host notification-link, and payout-image-alt findings were corrected in 5088d76.

Still requires paid/live host access

• Runtime verification of GPU, Docker, networking, and the paid vastai self-test machine path needs either an approved HydraHost rental with a spending cap or access to an authorized Vast dev host.
• No paid rental, credential-bearing operation, privileged host mutation, destructive command, or production/account-state change was performed during this local QA pass.

Backend/product-only behavior claims still need confirmation from their named source owners. Separately, PR #185 currently has conflicts with main that must be resolved before merge.

[jjziets]

Host Docs V&V evidence update

I added an independently reviewable evidence package using the Oxiom V&V Evidence procedure. It retains the pre-execution plan, exact targets/environment, raw outputs, the original failed attempt, corrections, and fresh retests.

Current result at ad2c808a3bc11c570c82a83e9949f03c7ac6642a:

• 8 PASS local-safe items: 72 Host pages / 474 inventory targets, 181 CLI occurrences at clean current CLI ecf32efa..., 39 persona pages, review-context tests 9/9, review-server syntax, OpenAPI, zero Host broken links, and whitespace.
• 1 FAIL: accessibility still reports 97 Host named-anchor findings plus the shared dark-theme contrast failure. The corrected Payment image now has zero missing-alt findings.
• 2 BLOCKED: paid/privileged/runtime Host validation and private product-policy confirmation still need approved host access/budget and authoritative owners or fixtures.

Start with the V&V summary. The issue/retest ledger preserves what failed and how it was rechecked; attempt 03 is the current clean-tree replay.

To reproduce the local-safe evidence with Node 24:

gh repo clone vast-ai/docs vast-docs-pr185
cd vast-docs-pr185
gh pr checkout 185
npm ci
gh repo clone vast-ai/vast-cli ../vast-cli-clean
NODE24_BIN="$(command -v node)" ./verification/run-local-safe-checks.sh \
  reviewer-$(date -u +%Y%m%dT%H%M%SZ) \
  ../vast-cli-clean

Please cite the V&V item ID and source line when leaving review feedback. This package supports the stated checks; it deliberately does not self-approve the work or present static checks as paid-host runtime proof.

[jjziets]

Command execution-access inventory added and verified at 09d729e.

All 176 Host Docs command targets now reconcile into mutually exclusive groups:

• 0 paid + Host root/privileged
• 6 paid resource, no Host root
• 52 Host root/privileged, no paid resource
• 14 Host context/artifact, no root in the documented command
• 104 neither paid spend nor Host root

“Neither” is not blanket-safe: each command retains separate authentication, credential, mutation, matching-environment, and external-client gates.

Review artifacts:

• Readable command-access report
• Machine-readable JSON
• Current V&V summary
• Attempt 04 retained evidence

Reproduce from an upstream clone:

git fetch origin pull/185/head:review-pr185
git switch review-pr185
python3 -B scripts/inventory_host_docs.py --check

Current status remains 8 local-safe PASS, 1 accessibility FAIL, 2 BLOCKED. Completing runtime validation still requires approved paid-machine budget for the six Self-Test forms and an approved disposable/dev Host for the 52 privileged and 14 Host-context forms. No paid or privileged documented command was run for this update.