docs: restructure README and docs into an entry point and a reference set #96

Context

Documentation audit on 2026-11-09 (latest release v0.18.1). README is 800 lines mixing operator guide, reference and contributor material, and has drifted from the code.

• verified: profile table omits rocky and misstates minimal/dgx/gpu-server (README:91-97 vs internal/config/profiles/*.yaml); detection also suggests rocky and gpu-server (detector.go:59-69).
• inferred (agent cross-check, re-verify while editing): env table claims every flag has an env variable (false for --module, --config, --dry-run, --force) and omits ROOTFILES_VLAN_INTERFACE, ROOTFILES_DATA_DIR; architecture tree omits internal/fleet/ (AGENTS.md too); doctor check list omits exporter checks; CI table omits exporter-firewall-scenario; Rocky section duplicates docs/rocky-support.md without linking it, and that file still says Rocky CI "remains required" although the job exists; about 25 config keys are documented nowhere (modules.system.*, ssh.*, users.fleet_sudo_users, modules.tenant.sshpiper.*, ...); docs/releases/v0.9.0.md is the only missing release note.
• verified: PLAN.md (Korean, 2026-03) and docs/IMPROVEMENT_PLAN.md (Korean, 2026-09-26) describe shipped work; docs/architecture/ (1.4 MB rendered HTML/PNG/JSON) says 13 modules and 12 commands and has no fleet/tenant/monitoring hub (code: 14 and 14).
• Long single paragraphs (README:342 ~900 words on home-base rules, README:252 ~300 words on config resolution) are hard for people and agents to use.

Implementation starts only on the owner's go-ahead.

Decisions

• README is the operator entry point (≤ ~200 lines): what it does, supported OS, install, quick start (single host, fleet), safety model, profiles, doc index.

• One topic per file under docs/, stable ## headings, each fact in one place; README and AGENTS.md link instead of repeating.

• AGENTS.md keeps only agent rules (build/test, invariants, conventions, release notes); the architecture list moves to docs/architecture.md.

• Docs are English. The Korean planning files are removed (git keeps history); open items from them move to specs or issues.

• docs/architecture/ rendered artifacts are deleted and replaced by text docs/architecture.md.

• docs/commands.md is hand-written; a Go test walks the cobra tree and fails when a command or flag is missing from it (cheap drift guard without a doc generator dependency).

• 2026-11-09: replace every example that uses the former DGX VLAN address in README and docs (README self-update/unattended and tunnel examples, docs/tenant.md failtoban_ignore example) with TEST-NET addresses (203.0.113.0/24), as fix(profiles): remove site-specific and no-op values from embedded profiles #90 did in code paths it touched; delete PLAN.md as planned. Use the README profile table from the PR fix(profiles)!: keep site-specific and no-op values out of the embedded profiles #101 body. Basis: review of PR fix(profiles)!: keep site-specific and no-op values out of the embedded profiles #101.

• 2026-11-10: open items of the deleted planning files are disposed of in the specs: the common disk/network preflight is retired (docs/specs/engine.md; doctor covers disk use, and a refusal would break contract chore(release): staged fleet rollout of the epic #98 release without disruption #115), the default native-command timeout is deferred (docs/specs/exec-packages.md), declarative MIG is not planned (docs/specs/gpu-allocation.md). Basis: review of PR docs: restructure README and docs into an entry point and a reference set #116.

Design

Target layout:

Changes

• README.md, AGENTS.md (architecture list → link; note the gpu module toggle and that module lists must agree), new files above, git rm PLAN.md docs/IMPROVEMENT_PLAN.md docs/architecture/, REVIEW.md (drop the architecture exclusion), docs/releases/v0.9.0.md, internal/cli/docs_test.go (cobra tree vs docs/commands.md), internal/config test that every YAML key appears in docs/configuration.md.

Acceptance criteria

• AC1: README ≤ 220 lines and links every docs file.
• AC2: go test ./internal/cli -run Docs fails when a command or flag is added without a docs/commands.md entry.
• AC3: a config test fails when a struct YAML key is missing from docs/configuration.md.
• AC4: every mismatch listed in Context is fixed (checklist in the PR).
• AC5: no Korean planning files or rendered architecture artifacts remain; no broken relative links (grep-based link check in the test).
• AC6: bash scripts/check-release-notes.sh passes, v0.9.0 note present.

Tasks

• T1: docs/commands.md + cobra drift test (AC2)
• T2: docs/configuration.md + key drift test (AC3)
• T3: topic files moved out of README, README rewrite (AC1, AC4)
• T4: AGENTS.md trim, archive removals, link check (AC5)
• T5: v0.9.0 release note (AC6)

Out of scope

• Per-feature specs (docs(specs): per-feature design specs covering every source file #97). Code changes from the other audit issues update these docs in their own PRs.