Reorganize documentation around complete operator workflows

[Nickfost]

Problem

The repository contains substantial standards and architecture documentation, but an operator still has to assemble a complete workflow from multiple files. The first VM pilot exposed ambiguity about what to run, what was already decided, which step was blocked, and which component owns each action.

Documentation should let a new operator, intern, or automation agent complete common work without reconstructing the architecture from conversation history.

Goal

Create a clear documentation structure organized around outcomes and roles:

• CI worker host;
• test/staging environment host;
• production deployment host;
• application project onboarding;
• new physical location/VPS onboarding;
• credentials and GitHub-side prerequisites;
• installation, upgrade, repair, verification, rollback, and removal.

Required improvements

• Add a concise documentation landing page with a role and task index.
• Explain CI worker, tester, and deployer boundaries in plain language.
• Provide separate quickstarts for each host role.
• Make prerequisites, required credentials, stopping conditions, and expected results explicit.
• Link each manual runbook to its eventual one-command Bash installer.
• Provide copyable configuration examples containing fictional values only.
• Add end-to-end checklists and final-report templates.
• Identify which steps occur in GitHub, on Proxmox, on the Linux host, in private configuration, and in an application repository.
• Mark prototype-only, current, planned, and production-ready material clearly.
• Remove duplicated or contradictory instructions.
• Ensure every command states where it runs and whether it changes state.
• Include troubleshooting for the failures encountered during the first live pilot.
• Add a glossary for runner, worker, controller, scale set, tester, deployer, environment, artifact, and project contract.
• Keep public examples free of internal infrastructure details and credentials.
• Add link validation and documentation checks to CI.

Acceptance

A person unfamiliar with the project can select a goal from the documentation landing page and complete or safely stop the workflow without needing chat history.

The documentation must answer:

1. What am I installing?
2. Where does it run?
3. Which configuration and credentials are required?
4. What single command performs the operation?
5. How do I verify success?
6. How do I upgrade, repair, roll back, or remove it?
7. What must never be combined or exposed?

[Nickfost]

Current-main audit evidence changes the documentation remainder for this issue:

• Core main b76aefe668f07904e1a782fa5b779b606d6a44c9 now has a beginner quickstart, glossary, role boundaries, idempotent CI worker/controller installer, Git-authored reconciliation, health/status docs, and schema-v3 reference material. The remaining Reorganize documentation around complete operator workflows #24 work is no longer a blank-site reorganization; it is completion and truthfulness across unfinished operator roles (Add an idempotent Bash installer for CI fleet hosts #21/Add an idempotent Bash installer for deployment hosts #22/Add an idempotent Bash installer for test environment hosts #23/Automate GitHub App and runner-group bootstrap with Bash #27) plus stale project-status/consumer-migration claims.
• Standalone-template main e483998b34595e51426c3b14589a74ca09ae78a9 validates internally, but its documented tagged-release/update path has no tag/release to consume, and its deployment approval language is not capability-aware for GitHub Free private repositories.

Template tracking, searched against open and closed issue/PR history before creation:

1. Make deployment policy capability-aware and isolate privileged roles ci-fleet-config-template#11 — capability-aware deployment policy and isolated privileged roles.
2. Publish a real template release and exact core compatibility signal ci-fleet-config-template#12 — real immutable template release and exact core compatibility signal.
3. Track the 2026-08-08 core/template compatibility audit gaps ci-fleet-config-template#13 — dependency-ordered audit tracker.

For #24 closure, link the eventual template release/update path and keep worker CI, persistent tester, deployer, and optional ref-writer workflows distinct. No rename decision is implied; #25 remains owner-controlled.

[Nickfost]

[lane-a:phase2:issue-24-outcome]

Repository-owned documentation work is current through #70 and #77. The outcome index now distinguishes default-branch commands from the deployer (#69), automated bootstrap (#75), and tester-host (#76) implementations under review; local link validation and exact-head CI passed for the final status refresh.

This issue remains open at a precise external/dependency gate: the role-specific quickstarts cannot truthfully become current until those draft implementation PRs obtain their separately authorized host/organization acceptance evidence and merge. No default-branch command or production-ready claim was invented.