Make forge adoption docs crystal-clear and modular (install layers in isolation)

[misnaej]

Goal

Make adopting forge super transparent and modular — a reader should be able to install exactly the layer(s) they want and understand every step, without cross-reading source to fill gaps.

Forge is already three separable layers in code; the docs don't make that separation obvious on the main critical path:

Layer	Components	Claude-independent	Standalone install
1 — pip CLIs	forge-scripts (20+ CLIs)	yes	pip install
2 — git hooks	.githooks/* + install-forge-githooks	yes	install-forge-githooks
3 — Claude Code plugin	agents / skills / hooks	no	/plugin install

install-forge-bootstrap runs all three in order, but each is independently callable. The README happy path doesn't visually separate "install just the CLIs" vs "add git hooks" vs "add the plugin".

Concrete gaps found in an inventory pass

1. Layer separation not visual in README Quickstart; "optional" status of layer 3 under-emphasized in the At-a-glance summary.
2. Drift detection underspecified — README says bootstrap is idempotent / re-sync but never explains how drift is detected (managed-block markers, body-sha hook wrappers, version tags). A consumer upgrading doesn't know whether to re-run bootstrap or trust auto-refresh hooks.
3. Hook-wrapper staleness preamble (.githooks/pre-commit head) is opaque — no doc explains why install-forge-githooks --refresh is recommended or what the body-sha / .forge-hook-version sidecar do.
4. Audit-pack extras buried — [audit] / [audit-tach] CLIs aren't surfaced in At-a-glance; easy to miss they exist.
5. Generated-artifact lifecycle not documented — which forge-gen-* / audit outputs (docs/api-digest.md, docs/cli-reference.md, code_health/audit_deps_tree.log) should be committed vs gitignored.
6. CI self-skip mechanism — README states doctor/audit-deps self-skip in CI but doesn't point at run_context.is_non_interactive() (FOUNDATION §15) so readers trust it.
7. Upgrade path decision matrix fuzzy — @main vs @dev vs tag pin, and which of forge-upgrade --apply / two-phase / manual to use for each.
8. Pre-commit customization vs upgrades — customizing-precommit.md says "edit .githooks/pre-commit directly" but doesn't explain what forge-upgrade does to a consumer-edited hook (body-sha skip behavior).
9. .claude/hooks/ path convention (${CLAUDE_PROJECT_DIR}, not relative) lives only in claude-code-plugin.md, not the main flow.

Proposed direction (for the implementing PR, not this issue)

• A single "Adopt forge" page with three explicit, independently-followable tracks (CLIs only / + git hooks / + plugin), each ending in a verification step.
• A short "what lands on disk" table (artifact → committed or gitignored).
• A drift / refresh / upgrade explainer that names the actual mechanisms.
• Keep install_bootstrap.py STEPS as the single source of truth; docs render from it.

Source inventory: README.md (25–44, 100–260, 321–394), src/forge/install_bootstrap.py (114–127 STEPS), docs/standalone-installers.md, docs/claude-code-plugin.md, docs/ci-recipe.md.

[misnaej]

[issue-triage] tier-3-standard applied: substantial docs overhaul (9 concrete gaps listed) covering layer separation, drift detection, hook-wrapper mechanics, and upgrade-path clarity. High consumer value but not blocking any in-flight work; architectural scope means it is not a quick-win.

[misnaej]

[issue-triage] FOUNDATION §14 (PR #37, merged 2026-06-12) now requires every issue to open with a Requires: line. This issue predates the rule. Dependency scan: standalone docs improvement — no open issue or PR must land first. Please prepend Requires: nothing to the issue body.