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

.github/workflows/self-test-reference.yml

@@ -0,0 +1,108 @@
+name: Self-test reference check
+
+on:
+  schedule:
+    - cron: '17 7 * * 1'
+  repository_dispatch:
+    types:
+      - self-test-reference-source-updated
+  pull_request:
+    paths:
+      - 'host/self-test-reference.mdx'
+      - 'host/common-errors-diagnostics.mdx'
+      - 'host/how-to-self-test.mdx'
+      - 'host/verification-stages.mdx'
+      - 'scripts/generate_self_test_reference.py'
+      - 'docs.json'
+      - 'package.json'
+      - '.github/workflows/self-test-reference.yml'
+  workflow_dispatch:
+    inputs:
+      vast_cli_ref:
+        description: 'vast-ai/vast-cli ref to generate from'
+        required: false
+        default: 'master'
+      self_test_ref:
+        description: 'vast-ai/self-test ref to generate from'
+        required: false
+        default: 'main'
+
+jobs:
+  verify-self-test-reference:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout docs
+        uses: actions/checkout@v4
+        with:
+          path: docs
+
+      - name: Decide whether private source repos can be checked out
+        id: source-access
+        env:
+          SOURCE_TOKEN: ${{ secrets.VAST_DOCS_SOURCE_TOKEN }}
+          HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name || github.repository }}
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ] && [ "$HEAD_REPO" != "${{ github.repository }}" ] && [ -z "$SOURCE_TOKEN" ]; then
+            echo "can_verify=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::Skipping self-test reference sync check for fork PR because VAST_DOCS_SOURCE_TOKEN is unavailable. Run workflow_dispatch or use an upstream branch to verify private source repos."
+          else
+            echo "can_verify=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Checkout vast-cli source
+        if: steps.source-access.outputs.can_verify == 'true'
+        uses: actions/checkout@v4
+        with:
+          repository: vast-ai/vast-cli
+          ref: ${{ github.event.client_payload.vast_cli_ref || github.event.inputs.vast_cli_ref || 'master' }}
+          path: vast-cli-source
+          token: ${{ secrets.VAST_DOCS_SOURCE_TOKEN || github.token }}
+
+      - name: Checkout self-test source
+        if: steps.source-access.outputs.can_verify == 'true'
+        uses: actions/checkout@v4
+        with:
+          repository: vast-ai/self-test
+          ref: ${{ github.event.client_payload.self_test_ref || github.event.inputs.self_test_ref || 'main' }}
+          path: self-test-source
+          token: ${{ secrets.VAST_DOCS_SOURCE_TOKEN || github.token }}
+
+      - uses: actions/setup-python@v5
+        if: steps.source-access.outputs.can_verify == 'true'
+        with:
+          python-version: '3.11'
+
+      - name: Regenerate self-test reference
+        if: steps.source-access.outputs.can_verify == 'true'
+        working-directory: docs
+        run: |
+          PYTHONDONTWRITEBYTECODE=1 npm run generate-self-test-reference -- \
+            --vast-cli ../vast-cli-source \
+            --self-test ../self-test-source
+
+      - name: Fail if generated page is out of sync
+        if: steps.source-access.outputs.can_verify == 'true'
+        working-directory: docs
+        run: |
+          if ! git diff --quiet host/self-test-reference.mdx; then
+            echo "::error::host/self-test-reference.mdx is out of sync with vast-ai/vast-cli or vast-ai/self-test."
+            echo "::error::Run 'npm run generate-self-test-reference -- --vast-cli PATH_TO_VAST_CLI --self-test PATH_TO_SELF_TEST' and commit the result."
+            git diff --stat host/self-test-reference.mdx
+            git diff -- host/self-test-reference.mdx
+            exit 1
+          fi
+
+      - name: Fail if Python bytecode was generated
+        if: steps.source-access.outputs.can_verify == 'true'
+        working-directory: docs
+        run: |
+          if find scripts -name '__pycache__' -o -name '*.pyc' | grep -q .; then
+            echo "::error::Generated Python bytecode should not be committed or produced by the docs generation check."
+            find scripts -name '__pycache__' -o -name '*.pyc'
+            exit 1
+          fi
+
+      - name: Report skipped private-source validation
+        if: steps.source-access.outputs.can_verify != 'true'
+        run: |
+          echo "Self-test reference sync check skipped because this fork PR cannot access private source repositories."

README.md

@@ -12,6 +12,36 @@ API endpoint specs live in `api-reference/openapi/yaml/` (one file per endpoint)
 4. Preview locally: `mint dev`.
 5. Commit both your YAML edit AND the regenerated `api-reference/openapi.yaml`, then open a PR. CI re-runs the build and fails if `openapi.yaml` is out of sync with the sources.
 
+## Updating the self-test reference
+
+The host self-test reference page is generated from the Vast CLI diagnostics and the self-test image metadata.
+
+1. Update the relevant self-test source in `vast-ai/vast-cli` or `vast-ai/self-test`.
+2. Regenerate the docs page:
+
+```bash
+npm run generate-self-test-reference -- --vast-cli ../vast-cli --self-test ../self-test
+```
+
+3. Review and commit `host/self-test-reference.mdx` with the source change or in the matching docs PR.
+4. CI re-runs the generator against `vast-ai/vast-cli` and `vast-ai/self-test` and fails if the committed page is out of sync. A weekly scheduled run catches source drift even when a source repository does not send a dispatch event.
+
+For cross-repo private checkouts, configure the docs repository secret `VAST_DOCS_SOURCE_TOKEN` with read access to `vast-ai/vast-cli` and `vast-ai/self-test`. The workflow can also be run manually with custom `vast_cli_ref` and `self_test_ref` inputs while a source PR is under review.
+
+Source repositories can trigger an immediate docs check after self-test metadata changes by sending a repository dispatch event to `vast-ai/docs`:
+
+```json
+{
+  "event_type": "self-test-reference-source-updated",
+  "client_payload": {
+    "vast_cli_ref": "master",
+    "self_test_ref": "main"
+  }
+}
+```
+
+Use the exact branch or SHA being validated when triggering this from a source PR workflow. Source-side dispatch is optional because the scheduled docs check provides a fallback; dispatch shortens the time before drift is reported.
+
 ## Mintlify Information
 
 **[Follow the full quickstart guide](https://starter.mintlify.com/quickstart)**

REVIEW-QUESTIONS.md

@@ -0,0 +1,135 @@
+# Reviewer inputs and Jira gates
+
+> Temporary review aid — removed before merge, like `review-server.mjs`.
+>
+> Start with the [Host docs review traceability audit](./REVIEW-TRACEABILITY.md)
+> to see what is implemented, what still needs sign-off, and the CON-1519
+> bundle-ownership decisions for the meeting.
+>
+> The eight cross-cutting decisions below gate the Host Docs review. A current
+> Jira audit also found page-specific questions for account setup, Network &
+> Ports, Self-Test, and Host Diagnostics. Those appear beside the comments on
+> the affected page in the port 4000 review panel, with direct Jira links.
+> The first two decisions below unblock the review sequence.
+>
+> **Three ways to answer — pick whichever is easiest:**
+> 1. Comment inline on this file in the [PR #185 diff](https://github.com/vast-ai/docs/pull/185/files).
+> 2. In the local review kit, open `http://localhost:4000/review-questions`, select a question, and comment — it lands in the same feedback export as your page comments.
+> 3. Reply on the linked Jira ticket.
+
+## Input 1. IA approval
+
+**Owner: Michele + docs owners · Round 0 · unblocks everything**
+
+Approve or modify the information architecture (CON-1518 decision points a–d):
+
+- (a) **Lifecycle sidebar** — Before You Host → Set Up → Verify & List → Operate → Reference, vs. some other top-level grouping.
+- (b) **P0/P1/P2 priority order** — the ticket-volume-driven ordering of new docs.
+- (c) **Supported Hardware as the #1 prevention doc** — even though it isn't the largest ticket bucket.
+- (d) **Persona tags** — keep the visible chips (top-right of each page), restyle them, or drop to frontmatter-only convention.
+
+Blocks: every other review round. Detail: CON-1518.
+
+## Input 2. Review mechanics
+
+**Owner: Michele + docs owners**
+
+How do you want to review the content: one small PR per sidebar group (round), or staged review of [PR #185](https://github.com/vast-ai/docs/pull/185) with per-round checklists? PR #185 now contains all the work (former #153 is an ancestor of it). Either way, **#152 and #153 should be closed as superseded**.
+
+Blocks: scheduling of every content round. Detail: CON-1518, CON-1584.
+
+## Input 3. Pricing content review
+
+**Owner: Gobind / Solutions Engineering · Round 3 · CON-1256**
+
+Review the business/pricing positioning: [Pricing Your Listing](https://github.com/jjziets/docs/blob/CON-1584-host-cli-api-sdk/host/pricing-your-listing.mdx), [Market Metrics](https://github.com/jjziets/docs/blob/CON-1584-host-cli-api-sdk/host/market-metrics.mdx), [Optimize Your Earnings](https://github.com/jjziets/docs/blob/CON-1584-host-cli-api-sdk/host/optimization-guide.mdx) — in the preview: `/host/pricing-your-listing`, `/host/market-metrics`, `/host/optimization-guide`.
+
+Blocks: CON-1256 sign-off. Detail: CON-1256.
+
+## Input 4. Machine-error platform behavior
+
+**Owner: Backend source owner (Hanran) · CON-1531**
+
+Seven confirmations that set the "how long it persists" copy on [Machine Error Reference](https://github.com/jjziets/docs/blob/CON-1584-host-cli-api-sdk/host/machine-errors.mdx) (`/host/machine-errors` in the preview):
+
+1. Is the 2026-06-24 error catalog complete for host-visible machine errors?
+2. For each error, which field displays it to hosts (`error_msg`, `error_note`, `error_description`, `vm_error_msg`, `vm_error_level`, other)?
+3. Which errors appear on the Machines page vs. only in a failed rental/instance detail?
+4. For machine-deverifying errors, what clears the error — next clean heartbeat, successful self-test, admin action, time decay?
+5. For VM-offer-only errors, what is the approximate clean-report/TTL before VM offers return?
+6. Should logged-only rental-attempt messages be public host docs, or internal/support-only?
+7. Should the console deep-link docs by raw error string, normalized category, or both?
+
+Blocks: final wording on Machine Error Reference. Detail: CON-1531.
+
+## Input 5. Installer Wizard screenshot
+
+**Owner: Product · Rounds 0/2**
+
+Approve the Host Installer Wizard (TUI) screenshot in [Installing Host Software](https://github.com/jjziets/docs/blob/CON-1584-host-cli-api-sdk/host/installing-host-software.mdx) (`/host/installing-host-software#host-installer-wizard` in the preview) — or supply a replacement asset.
+
+Blocks: production merge (flagged since 2026-06-17). Detail: CON-1518 Jira attachment `image-20260617-135801.png`.
+
+## Input 6. Supported Hardware sign-off
+
+**Owner: Product · Round 1**
+
+Confirm [Supported Hardware](https://github.com/jjziets/docs/blob/CON-1584-host-cli-api-sdk/host/supported-hardware.mdx) (`/host/supported-hardware` in the preview): exact GPU-family coverage, OS/cgroup guidance, and alignment of the CPU rule between docs, self-test #6, and vast-cli #413. Related product asks on the radar: payment/tax edge cases (incl. W-8 for non-US hosts) and datacenter requirements wording.
+
+Blocks: CON-1516 sign-off; the highest-prevention doc going live. Detail: CON-1516.
+
+## Input 7. Host Teams engineering answers
+
+**Owner: Engineering · Round 6 · CON-1581**
+
+Five answers that gate publishing [Host Teams](https://github.com/jjziets/docs/blob/CON-1584-host-cli-api-sdk/host/host-teams.mdx) (`/host/host-teams` in the preview):
+
+1. Individual→team migration: what happens to existing machines and accrued earnings?
+2. Install-command `undefined` bug in team context — status?
+3. What is the exact flow for granting machine-registration rights to a team API key? (Flagged inside the draft page itself.)
+4. Are `billing_read`-only roles viable for host teams?
+5. Who owns billing/payouts when machines move into a team?
+
+Blocks: Host Teams page publication. Detail: CON-1581.
+
+## Input 8. Persona scope ruling
+
+**Owner: Docs team · Round 5**
+
+Do the generated `host/cli/*` and `host/sdk/*` reference pages need persona chips, or are generated reference pages exempt? All 39 authored pages are tagged and chip-synced (now lint-enforced via `npm run check-persona-chips`); the 33 generated pages are currently exempt by convention.
+
+Blocks: the literal reading of CON-1518's "tag every page"; the only remaining implementation wrinkle. Detail: CON-1518 (2026-06-29 comment).
+
+## Additional page-specific Jira gates
+
+These are intentionally shown on the affected page instead of expanding every
+reviewer's checklist. Open the review panel on that page to see the questions,
+owner, status, and direct Jira links.
+
+- **Account and installation:** setup-page machine installation key wording,
+  dedicated host account guidance, team registration permissions, and the
+  installer screenshot — [CON-1584](https://vastai.atlassian.net/browse/CON-1584),
+  [CON-1581](https://vastai.atlassian.net/browse/CON-1581), and
+  [CON-1518](https://vastai.atlassian.net/browse/CON-1518).
+- **Network & Ports:** per-GPU versus per-instance port wording, TCP/UDP
+  behavior, port release timing, and exact failed-port evidence —
+  [CON-1514](https://vastai.atlassian.net/browse/CON-1514).
+- **Verification / Self-Test:** confirm the authoritative verification queue
+  and wait-time facts. The generated actual-versus-required/stable-code
+  reference, source drift workflow, B300 RAM-cap wording, and older-GPU image
+  selection are now present in PR #185 —
+  [CON-1515](https://vastai.atlassian.net/browse/CON-1515),
+  [CON-1513](https://vastai.atlassian.net/browse/CON-1513),
+  [CON-1583](https://vastai.atlassian.net/browse/CON-1583), and
+  [CON-1419](https://vastai.atlassian.net/browse/CON-1419).
+- **Host Diagnostics:** decide diagnostic-bundle intake, retention, first
+  triage, diagnostic ownership, and safe host-local artifact policy. The merged
+  `vastai dump-logs` workflow is documented; backend-only daemon/Docker/port
+  evidence remains a platform question —
+  [CON-1510](https://vastai.atlassian.net/browse/CON-1510),
+  [CON-1519](https://vastai.atlassian.net/browse/CON-1519), and
+  [CON-1514](https://vastai.atlassian.net/browse/CON-1514).
+
+---
+
+*Non-blocking follow-ups already ticketed elsewhere: `vastai verify-status` / queue-position-by-GPU-tier (product/CLI feature), CLI error-string deep-linking (docs anchors are ready).*