CON-1518: Host docs IA mockup updates

[jjziets]

Summary

• updates the CON-1518 Host Docs IA mockup after live human review of all 33 Common Host Questions
• also covers the CON-1256 business/pricing/listing-optimization workstream by adding focused host pages for pricing, earnings, market metrics, contracts, listing controls, Secure Cloud/datacenter status, and help paths
• removes public-facing machine ID/internal daemon recovery guidance that should not be documented
• aligns verification, reliability, physical CPU core, Ubuntu, port forwarding, CGNAT/double NAT, XFS quota, self-test, logs, search visibility, earnings, and payout wording with reviewed sources
• adds Host Market GPU Overview guidance so hosts can use % Rented (30D Avg) plus $/HR MED as a rough compute-income estimate
• removes the temporary Host-docs review artifact route and keeps the review ledger outside the public docs tree

CON-1256 Business / Pricing / Listing Optimization Coverage

This PR also addresses the major CON-1256 topics inside the broader host-docs IA update:

• Business-owner and operator paths are represented across Is Vast for Me?, Earnings & Pricing Model, Pricing Your Listing, Optimize Your Earnings, GPU Market Metrics, Datacenter Status, and Host Payouts.
• Marketplace and contract basics are documented in Hosting Overview, including offers, accepted rental contracts, active contract behavior, offer end dates, and why edits affect future rentals only.
• Contract expectations and risk are covered through Hosting Overview, Workload Policy, Maintenance Windows, and Reliability & Uptime.
• Contract length / offer end-date guidance is covered in Hosting Overview, Pricing Your Listing, and Optimize Your Earnings.
• Pricing guidance now distinguishes gross compute, storage, bandwidth, and volume revenue, and points hosts to market data instead of only recommending a high hourly price.
• Reserved pricing and interruptible pricing are covered in Pricing Your Listing through discount_rate and price_min_bid / minimum-bid guidance.
• Minimum GPU slicing is covered as min_gpu / min_chunk in Pricing Your Listing, Optimize Your Earnings, and the glossary.
• Verification and Secure Cloud / datacenter tier context are covered in Verification Stages, Understanding Verification, and Datacenter Status.
• Options for getting help are covered in Discord & Community, Common Errors & Diagnostics, and setup/overview pages that distinguish community help from account/platform escalation.

Remaining review item for CON-1256: add Gobind as reviewer / content reviewer and confirm whether any exact wording from the attached vast_optimization_guide_for_hosts.html should be preserved or credited before production merge.

Human Review

All 33 Common Host Questions were reviewed with a human reviewer on 2026-06-19. For each question, the review compared the current public answer, source evidence, and recommended rewrite before accepting or changing the public wording.

The docs were updated to avoid AI-style filler and unsupported claims. Stale wiki/internal details were excluded unless supported by current docs, current CLI/self-test behavior, or explicit product/dev feedback. Remaining uncertain areas are left as owner-review topics instead of being guessed into public docs.

Reviewed changes include:

• production port guidance now recommends about 100 TCP/UDP ports per listed GPU while keeping the self-test minimum at 3 ports per GPU
• CGNAT and double NAT without a real public forwarding path are documented as unsupported hosting network setups
• Ubuntu 24.04 remains the preferred install path; old Ubuntu 22.04 cgroup-v1 workaround text is not copied into 24.04 guidance
• installer, daemon, self-test bundle, Xid/NVRM/PCIe/AER, and outside-LAN port-check guidance now include practical commands
• marketplace search docs explain ranking/grouping/result limits and include machine-ID CLI filters
• earnings docs distinguish compute, storage, bandwidth, and volume revenue instead of reducing earnings to occupancy times GPU price
• market metrics/pricing docs now explain the Host Market GPU Overview tab and show how % Rented (30D Avg) multiplied by $/HR MED gives a better starting estimate than price alone
• payout docs cover Earnings Chart exports, Payout History CSV/PDF downloads, and Payout Account switching behavior

CON-1531 Machine Error Reference Update

This PR now also includes the current CON-1531 Machine Error Reference draft work:

• Adds host/machine-errors.mdx as a host-facing reference for Machines-page errors, direct-port failures, Docker/NVIDIA runtime errors, GPU/PCIe/ECC symptoms, storage quota errors, VM-offer errors, and rental-attempt messages.
• Adds a Listing Impact matrix that distinguishes whole-machine deverify errors, VM-offer-only errors, and logged-only rental-attempt messages based on Hanran Yang's source-owner feedback.
• Adds exact VM-offer-only messages for IOMMU/NVIDIA DRM modeset changes, GDM holding a GPU, unsupported VM configuration, unexpected passthrough changes, after-host-change incompatibility, VM memory preflight failure, machine-authentication 401 while fetching secrets, and repeated GPU VM startup failures.
• Adds an <admin-set> entry framed as a manual Vast admin investigation flag, not an automatic self-test result.
• Adds a concise Quick Error Lookup table to host/self-test-reference.mdx so hosts can map common self-test messages/stages to immediate next actions.
• Keeps unsupported/internal guidance out of public docs, including send_mach_info.py --speedtest, --reset-machine, machine-ID recovery workflows, missing API-key/keepalive internals, and manual verification claims.

Related source PRs for the paired self-test work:

• CLI: vast-ai/vast-cli#413
• Self-test image/runtime: vast-ai/self-test#6
• Generated self-test reference pipeline context: vast-ai/docs#145

Remaining CON-1531 review caveats:

• Need platform/source-owner confirmation that Hanran's current catalog is complete.
• Need exact field mapping for error_msg, error_note, error_description, vm_error_msg, vm_error_level, and UI display surfaces.
• Need exact clearing/TTL/heartbeat behavior.
• Need product/docs decision on whether logged-only rental-attempt messages should remain public or move to internal/support docs.

Host Market GPU Overview Update

Added a new GPU Overview Income Estimate section under host/market-metrics.mdx, with cross-links from host/earning.mdx and host/pricing-your-listing.mdx. The new wording explains that hosts can estimate rough gross compute revenue by combining 30-day average rental utilization with median hourly price.

Example included from the Host Market view:

RTX 5090: 65.0% rented 30-day average x $0.361/hr median
0.361 x 0.65 = $0.23465 average gross compute revenue per hour per GPU
0.361 x 720 x 0.65 = $168.95 gross compute revenue per month per GPU

The docs explicitly frame this as a rough compute-only planning estimate. It does not include storage, bandwidth, volume revenue, power, cooling, hardware cost, taxes, payout timing, downtime, or the fact that earnings are not guaranteed.

Notes

This remains a draft/demo PR for review of the proposed host docs structure and content direction. The Host Installer Wizard screenshot should be replaced with an approved product screenshot before production merge if marketing/product wants canonical assets.

Owner-review topics still called out in the review ledger: exact GPU-family coverage, installer owner wording/assets, OS-specific cgroup guidance, payment/tax edge cases, datacenter requirements, any future full vericode table expansion, and final business/listing review by Gobind for CON-1256.

Validation

• git diff --check
• npx mint validate

[hanran-y]

What is this personas list for?

[jjziets]

it was one of the required tasks on jira to add personas

[jjziets]

Keeping this. The personas: frontmatter is the source-of-truth metadata for the CON-1518 persona overlay: Pro Operator, Headless/DC, Business, and Hobbyist. The sidebar stays lifecycle-based, but this metadata lets docs/search/support/LLM retrieval identify which host audience a page primarily serves without duplicating the IA into separate persona sidebars.

[hanran-y]

What would be the purpose of having the persona tag on all pages?

[jjziets]

it was one of the required tasks on jira to add personas

[jjziets]

The visible chips are intentional for the same reason: they give hosts a quick lane marker while they scan the lifecycle sidebar. A Hobbyist can follow the Quickstart/Supported Hardware path, a Headless/DC operator can spot SSH/fleet/maintenance pages, and a Business owner can identify pricing/earnings/payout docs. It is a lightweight overlay on the lifecycle IA, not a separate navigation system.

[hanran-y]

Using a more positive tone, I would suggest simply directing users to sign up for a dedicated hosting account and pointing them to the setup page. Once they sign up, we can provide the full documentation and onboarding details.

The goal is to make it as easy as possible for new hosts to find the hosting account sign-up link and get started quickly. Most users are looking for a simple TL;DR rather than a long document upfront.

[jjziets]

CON-1531 progress update from this branch:

• Added a draft Host Machine Error Reference page at host/machine-errors.mdx.
• Linked common dashboard error strings from host/common-errors-diagnostics.mdx to the new reference page.
• Added nccl_failed guidance to the self-test reference and linked the self-test NCCL stage to it.
• Added the page to docs.json under Host > Operate.

Validation: npx mint validate passes locally.

Caveat before treating this as ready for CON-1531: the page is intentionally conservative because the backend source files named in the ticket are not accessible from this workspace/account. I found secondary support-tools evidence for error_msg, error_description, vm_error_msg, vm_error_level, and vericode, but source-owner confirmation is still needed for exact clearing/TTL/deverification behavior.

[jjziets]

CON-1531 update: I found stronger secondary evidence in support-tools/reporting for the vericode mapping. It says vericode bit 8 means a host-facing machine error_msg is present; Port Networking Issues is one possible error_msg, not the definition of all vericode=8 cases. I pushed a wording correction in a8a935c so the docs now tell hosts to use the exact visible machine error text, with Port Networking Issues treated as the port-specific case. Backend/source-owner confirmation is still needed for the complete raw-string registry, clearing/TTL behavior, and deverification semantics.

[jjziets]

CON-1531 closeout audit update: I added a local completion audit and refreshed evidence packet. Current state is: public Machine Error Reference draft is implemented and validated; paid dogfood and live CLI probes are captured; vericode=8 wording is corrected. Remaining blockers are explicitly backend/source-owner items: complete raw error registry, clearing/TTL behavior, and exact VM-only vs general deverification semantics. Live CLI probes confirm public/client-readable CLI paths do not expose raw machine error strings, so backend/source confirmation is required before this can become a source-derived/generated reference.

[jjziets]

Update from this pass:

• Stacked the useful CON-1077/CON-1518/CON-1077: Host docs IA + headless handover #153 headless-hosting guide content onto this CON-1518 branch in host/headless-install.mdx.
• Kept the CON-1518 lifecycle IA/persona treatment: personas: frontmatter plus the Headless/DC chip remain on the page.
• Standardized the headless guide examples to the 8-GPU / 40000-40799 range, matching the about-100-direct-ports-per-listed-GPU guidance instead of the 64-port example from CON-1518/CON-1077: Host docs IA + headless handover #153.
• Added missing persona metadata/chips to host/optimization-guide.mdx.
• Replied on the two open persona-tag review threads with the rationale: lifecycle IA stays primary, persona tags are a lightweight scan/retrieval overlay rather than a separate persona sidebar.

Validation:

• git diff --check
• npx --yes mint@4.2.647 validate
• localhost render check for host/headless-install
• all 68 Host nav routes return 200 on the settled local preview

Remaining owner-review gates are still real and should stay visible before production merge: Gobind/business listing review, CON-1531 source-owner confirmation for machine-error catalog/TTL/UI fields, approved installer screenshot, and product/source-owner review for GPU-family, installer, payment/tax, and datacenter edge cases.

[jjziets]

Supersession update: #153 now includes this CON-1518 IA branch and should be treated as the final handover/review target.

Merged into #153 at b81f5c2ccc76d2f069fa2aee3a3da704e43d88ac. I am leaving this draft open for reviewer/maintainer discretion, but the active handover trail is now in #153.