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`	Compatibility pointer	Canonical guide moved to `docs/cli/agent-usage.md`
`docs/agents/cli-reference.md`	Compatibility pointer	Canonical reference moved to `docs/cli/reference.md`
`docs/discovery-and-kernel-skills.md`	Compatibility pointer	Canonical routing guide moved to `docs/cli/capability-routing.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 pasteable asks; link terminal users to the CLI reference
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	End-user setup	Agent-install prompt, expected evidence, and CLI-reference link only
Troubleshooting	End-user recovery	Recovery prompts; exact diagnostics stay in the CLI reference
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, every AIWG executable block and inline command on non-historical user pages is replaced with a contextual natural-language prompt and a visible prompt-first notice. Exact syntax remains in the dedicated, published `docs/cli/` area and the installed agent corpus. Historical release notes and contributor documentation 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 core published user journeys	51	0
Command-first homepage checklist items	3	0
Canonical CLI-reference entries in public navigation	0	1

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