# 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.
