Conversational Documentation Migration Map

This inventory records the baseline for issue #1937. It is intentionally classification-based: command blocks are moved or rewritten according to their reader and task, not deleted by raw count.

Surface	Baseline classification	Destination/action
`docs/agents/CLI_USAGE.md`	Agent/operator reference	Moved to `docs/agents/CLI_USAGE.md`
`docs/agents/cli-reference.md`	Agent/operator reference	Moved to `docs/agents/cli-reference.md`
Discovery and kernel procedures	Agent-internal	Indexed agent reference; public pages describe the conversational result
Welcome/homepage	End-user orientation	Lead with conversation, expected behavior, approval, and result
Start-here and quickstart	End-user tutorial	Lead with asks; retain bootstrap escape hatch
Provider handoff	End-user how-to plus operator details	Conversational primary path; operational flags in agent corpus
Onboarding validation	End-user verification	Agent runs probe and translates evidence
Framework entry points	End-user how-to	Ask/outcome/verification pattern
Install pages	User-required direct touch	Retain justified bootstrap commands
Troubleshooting	Recovery escape hatch	Commands allowed when clearly labeled
Development/contributing	Maintainer	Retain commands with explicit audience
Blog and release notes	Historical	Preserve wording and command history
Tests and fixtures	Example fixture	Excluded from prose migration

Audit baseline

At issue intake, `docs/_manifest.json` exposed both CLI references and `docs/config.json` used three command-first checklist items plus a CLI quick link. Core onboarding pages directly instructed users to run wizard, probe, discover, and show operations. The post-migration audit is generated by `npm run docs:audience:audit`.

The generated audit enumerates every path under `docs/getting-started/` and every Markdown filename containing `quickstart`, `how-to`, or `howto`. Each is classified as the canonical onboarding page, linked to canonical onboarding, contributor/maintainer, historical, or specialized-needs-review. The audit also records whether the page contains the preferred `use all --provider` and `aiwg-regenerate` hookup signals; this makes remaining migrations explicit without treating every specialized tutorial as a duplicate install guide.

The inventory also records every Markdown page containing an `aiwg` command, the number of direct-touch mentions, and the number of agent/operator mentions. During public-source staging, any non-historical public page that retains a command outside the direct-touch allowlist receives a visible execution notice: those commands are agent/operator detail, and conversational users should state the outcome they want. This makes retained exceptions explicit instead of relying on readers to infer the audience. Historical release notes, contributor documentation, and the source files themselves are not mechanically rewritten.

Before and after

The audit baseline is stored in `docs/public-docs.json` and was calculated from the repository HEAD at issue intake. The same audit reports current values:

Signal	Before	Current target
Command mentions across the seven core public journeys	51	substantially reduced; retained commands are bootstrap or recovery
Command-first homepage checklist items	3	0
CLI/agent-reference entries in public navigation	2	0

Operational coverage is retained in `docs/agents/`, the npm `docs/` payload, and the signed release pipeline's `reference` bundle.