[Docs]: Retire QUICKSTART.md — fold its unique content into USAGE_GUIDE and CONFIGURATION #239

Location

• QUICKSTART.md (root)
• USAGE_GUIDE.md, CONFIGURATION.md
• ~20 inbound links across OVERVIEW.md, TROUBLESHOOTING.md, USAGE_GUIDE.md, FAQ.md, MCPs.md, PLUGINS.md, DEVELOPER_GUIDE.md, INSTALLATION.md, docs/CODEMAP.md, docs/CONTEXT.md, docs/mcp/DEPLOYMENT_GUIDE.md
• src/rosetta-mcp-server/rosetta_mcp/constants.py:98

What's Wrong or Missing

After #238 restructured the README around the user journey, the README carries the same happy path that QUICKSTART.md does — install, initialize, commit, run a first workflow. The two documents now overlap almost completely, and a reader has no way to tell which one is current.

A line-by-line comparison of QUICKSTART.md against README, USAGE_GUIDE, CONFIGURATION, OVERVIEW, FAQ and the install docs shows almost nothing is unique to it:

Already duplicated elsewhere

Genuinely unique — needs a home before deletion

1. /requirements-authoring-flow update variant (update existing requirements for <component>…) — USAGE_GUIDE has only create-from-scratch examples, no extract and no update.
2. The using subagents + Once done, spawn a subagent to validate and repeat until no issues remain idiom — the most reusable pattern in the file, absent from USAGE_GUIDE entirely.
3. Phase-numbered modernization invocations (phase 1 / 2 / 8, and Must use coding-flow as the main flow) — USAGE_GUIDE already lists all 8 phases by number, so these have a referent there.

One line that must not be carried over

QUICKSTART.md:124 states "Phase 3: Pre-Modernization Test Coverage is a must". The executable flow says the opposite — instructions/r3/core/workflows/modernization-flow.md:55 marks the phase (OPTIONAL) and gates it behind explicit user approval.

History says (OPTIONAL) is authoritative: phase 3 was documented as (Optional) from its first appearance (f4303631, 2026-05-08), the is a must wording landed four days later in a single-file commit to QUICKSTART.md (2bfa0d97, 2026-05-12), and (OPTIONAL) was then written into the executable instruction (cc81f620, 2026-05-13) and never reverted since. All three commits are by the same author.

A stale copy of the is a must wording still lives in instructions/r3/core/workflows/init-workspace-flow.md:149 and its seven plugin copies. That is out of scope here but worth a separate look.

Suggested Change

Retire QUICKSTART.md. Concretely:

1. USAGE_GUIDE.md — add the requirements extract and update examples, the phase-numbered modernization examples with a pointer to Modernization Additional Setup, and a Best Practices entry for the using subagents + self-validation idiom.
2. CONFIGURATION.md — add a closing "Next steps" section linking to USAGE_GUIDE Workflows and Best Practices. The page currently ends with no onward link, which is why QUICKSTART was acting as the bridge.
3. Delete QUICKSTART.md and repoint every inbound link — most to README.md#quick-start, MCP-transport ones to MCPs.md, bootstrap/IDE-path ones to INSTALLATION.md.
4. src/rosetta-mcp-server/rosetta_mcp/constants.py:98 — COMPATIBILITY_MODE_UPGRADE_URL points at the GitHub blob URL for QUICKSTART.md. This is not documentation: the MCP server hands this URL to users in legacy compatibility mode, so it would start returning 404. The notice says "upgrade to HTTP mode", so MCPs.md is the right target.

Notes

• DEVELOPER_GUIDE.md:227,396 link to QUICKSTART.md#step-2-add-bootstrap-rule — an anchor that already does not exist, since step 2 is "Initialize". Deletion turns a broken anchor into a broken file, so these need repointing either way.
• docs/web/docs/quickstart.md and the website links to /rosetta/docs/quickstart/ are deliberately left alone here — website mirrors are tracked in Refresh Rosetta website for Release 3 #168.
• docs/reviews/DOC-STRUCTURE-PLAN.md still lists QUICKSTART.md as an owned document with its own contract (§ lines 18, 88) and leaves §5.1/§5.4 open on exactly this overlap. That contract needs updating alongside.
• docs/requirements/rosetta-cli/functional-requirements.md:215 cites <source>QUICKSTART.md Step 3</source>. That is a provenance record on an approved-status requirement, so it should stay as a historical citation rather than be silently repointed.
• src/rosetta-cli/README.md:28,51,614 point to docs/QUICKSTART.md, a path that has never existed. Pre-existing breakage, unrelated — belongs with [ROSETTA] rosetta-cli README Tag-in-Title docs stale vs code #206.

Kept separate from #238 on purpose so that PR stays scoped to the README rewrite.

🤖 Rosetta Plan

Objective

Retire the duplicate root QUICKSTART.md, preserving its three unique workflow patterns in their canonical owners and leaving no live repository or legacy-MCP link to the deleted document.

Selected design

Migrate only the requirements extract/update examples, phase-focused modernization examples, and focused-subagent validation practice into USAGE_GUIDE.md; add the configuration-to-usage bridge in CONFIGURATION.md; make README the concise, usable quick-start route; then repair semantic links and delete the old file. This keeps one owner per fact: README routes, INSTALLATION installs/bootstraps/initializes, CONFIGURATION configures, and USAGE_GUIDE explains workflows and practices.

Rejected: global redirect-only replacement (loses unique guidance) and a QUICKSTART stub (GitHub Markdown cannot redirect and preserves duplicate ownership).

Implementation plan

1. Repair README.md first: replace its link-only Quick Start section with a plain ## Quick Start route for install → initialize → configure → use, linking to its canonical owners. Keep README.md#quick-start as the general happy-path destination.
2. Extend USAGE_GUIDE.md: add requirements extract and update examples after existing create examples; add modernization phase 1, 2, and 8 examples under Modernization; link setup to CONFIGURATION.md#4-modernization-additional-setup; retain the authoritative rule that Phase 3 is optional and needs explicit approval; add one focused-subagent plus independent-validation-loop Best Practice.
3. Update CONFIGURATION.md: replace its Quick Start references with the appropriate installation targets and append ## Next Steps linking to USAGE_GUIDE.md#workflows and USAGE_GUIDE.md#best-practices.
4. Apply the link matrix below, update the documentation map/contract, change the compatibility-notice URL, add focused notice-contract coverage, then delete QUICKSTART.md only after all migrations are complete.

Inbound-reference matrix

Files

• Modify: README.md, USAGE_GUIDE.md, CONFIGURATION.md, INSTALLATION.md, PLUGINS.md, MCPs.md, FAQ.md, TROUBLESHOOTING.md, OVERVIEW.md, DEVELOPER_GUIDE.md, docs/CONTEXT.md, docs/CODEMAP.md, docs/mcp/DEPLOYMENT_GUIDE.md, docs/reviews/DOC-STRUCTURE-PLAN.md, src/rosetta-mcp-server/rosetta_mcp/constants.py, and the focused existing/new MCP-server test module that owns compatibility-notice behavior.
• Delete: QUICKSTART.md.

Technical specifications

• No API, model, data, plugin, or website behavior change. The one runtime contract change is the legacy compatibility notice URL; it must resolve to the MCP guide after deletion.
• docs/CODEMAP.md removes QUICKSTART from the root inventory and changes its documented file count from 519 to 518, unless another tracked-file count change occurs in this scope.
• docs/reviews/DOC-STRUCTURE-PLAN.md removes the QUICKSTART inventory row, contract, Mermaid QS node/edges/class, stale exclusions, and resolved-overlap notes. Its user path becomes README → install route (PLUGINS/MCPs/INSTALLATION) → CONFIGURATION → USAGE_GUIDE.
• Preserve the historical requirement source citation in docs/requirements/rosetta-cli/functional-requirements.md, historical/statistical references, docs/web/** and scripts/sync_user_guide_web.py (Refresh Rosetta website for Release 3 #168), src/rosetta-cli/README.md ([ROSETTA] rosetta-cli README Tag-in-Title docs stale vs code #206), and the separate stale instruction wording. Do not modify generated plugin files.

Validation and acceptance criteria

• QUICKSTART.md is absent only after all unique content is available from USAGE_GUIDE and CONFIGURATION.
• A focused test asserts that the rendered compatibility notice contains the MCPs upgrade URL; a live request to that public URL returns success after deletion.
• An exhaustive rg sweep finds no live, non-excluded QUICKSTART.md link; retained historical/provenance/website/CLI/instruction-vocabulary occurrences are documented as exclusions.
• Every changed fragment resolves to a live heading: README Quick Start, INSTALLATION bootstrap and initialization, MCPs connection, CONFIGURATION modernization setup, and USAGE_GUIDE Workflows/Best Practices.
• README quick-start is usable on its own; CONFIGURATION ends with the two onward links; USAGE_GUIDE has extract, update, phase 1/2/8, and validation-loop guidance; Phase 3 remains optional and approval-gated.
• Documentation-contract ownership and Mermaid route match the final user journey; no excluded path changes.

Risks and scope controls

The main risk is a semantic or fragment-level dead link in a cross-document sweep, plus the legacy notice URL becoming a 404. Mitigate by completing the matrix before deletion and validating links/anchors after it. No blocking questions.