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

[omaiesh]

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

QUICKSTART	Also in
Install-mode table, model recommendation, conflicting-plugin warning	README.md (model list is fresher there)
Greenfield/brownfield init prompts, generated-docs list	README.md
Composite-workspace and dead-code init variants	USAGE_GUIDE.md
Coding-flow examples	README.md, USAGE_GUIDE.md
/ui-aqa-flow Fix the failing automated test	USAGE_GUIDE.md
"Save Tokens" line	CONFIGURATION.md, README.md, USAGE_GUIDE.md — a 4th copy
Modernization prerequisites (goals in CONTEXT.md, target in ARCHITECTURE.md, refsrc/)	CONFIGURATION.md §3, in far more detail
Manager-approval notice, inversion-of-control note	PLUGINS.md, MCPs.md, INSTALLATION.md, OVERVIEW.md
Four Vimeo tutorials	USAGE_GUIDE.md (has all four plus two more), MCPs.md

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

Source	Replacement
General happy-path references in README.md, USAGE_GUIDE.md, FAQ.md, OVERVIEW.md, docs/CONTEXT.md, docs/mcp/DEPLOYMENT_GUIDE.md, and INSTALLATION.md	Repaired README.md#quick-start; rewrite same-page README prose so it does not self-link.
Bootstrap-rule references in TROUBLESHOOTING.md and DEVELOPER_GUIDE.md	INSTALLATION.md#step-2-add-bootstrap-rule-http-and-stdio-modes-only.
Initialization references in CONFIGURATION.md, PLUGINS.md, and MCPs.md	INSTALLATION.md#step-4-initialize-repository.
Hosted-MCP setup/support references in TROUBLESHOOTING.md	MCPs.md#step-1-connect-rosetta-mcp; reword the untested-IDE statement rather than falsely attributing an IDE list to QUICKSTART.
Model guidance in FAQ.md	Its existing local #model-selection content or plain prose; do not point it at an unrelated quick-start page.
COMPATIBILITY_MODE_UPGRADE_URL	https://github.com/griddynamics/rosetta/blob/main/MCPs.md (legacy notice directs users to HTTP MCP guidance).

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.

[github-actions]

Rosetta Triage

Classification: task, documentation — a docs-consolidation/dead-doc-removal request, not a code bug or feature.
Priority assessment: Low-Medium. No live breakage yet, but constants.py:98 (COMPATIBILITY_MODE_UPGRADE_URL) will 404 the moment QUICKSTART.md is deleted unless repointed in the same change, and there's a documented factual conflict (Phase 3 "must" vs "OPTIONAL") that should be corrected regardless of the broader retirement.

Findings:

• Verified src/rosetta-mcp-server/rosetta_mcp/constants.py:98 — COMPATIBILITY_MODE_UPGRADE_URL does point at the QUICKSTART.md GitHub blob URL; this is a functional dependency (served to users in legacy compatibility mode), not just a doc link.
• Verified the Phase 3 conflict: instructions/r3/core/workflows/modernization-flow.md:55 marks Phase 3 (OPTIONAL) with NOTE: Execute this phase if user explicitly approves it, while QUICKSTART.md:124 says Phase 3: Pre-Modernization Test Coverage is a must. The instruction file is authoritative (it's what the agent actually executes), so the QUICKSTART wording is stale/wrong.
• Confirmed the same stale is a must phrasing also exists at instructions/r3/core/workflows/init-workspace-flow.md:149, correctly flagged as out of scope for this issue.
• Issue correctly separates in-scope work (retire QUICKSTART, migrate unique content, repoint links) from adjacent-but-distinct issues (Refresh Rosetta website for Release 3 #168 website mirror, [ROSETTA] rosetta-cli README Tag-in-Title docs stale vs code #206 broken src/rosetta-cli/README.md links, the init-workspace-flow.md stale line) — good scoping discipline, avoids scope creep.

Caveats:

• This is a multi-file, cross-cutting change (README/USAGE_GUIDE/CONFIGURATION content moves, ~20 inbound link repoints across docs, a plugin-served URL, a doc-structure contract file, and 8 plugin copies of init-workspace-flow.md for the separately-flagged line). Sizing it as a single PR risks a large, hard-to-review diff; consider whether the constants.py URL fix should land as its own small, low-risk PR ahead of the bulk content migration.
• No repo label exists for "priority" tiers (Urgent/High/Medium/Low) or a generic "task" type — only documentation, which is already applied and is the best fit available.

Suggestions:

• Land the constants.py:98 URL repoint (→ MCPs.md) as a prerequisite/first step so the legacy-mode upgrade link never dangles between the content migration and the file deletion.
• When migrating content into USAGE_GUIDE.md/CONFIGURATION.md, drop the is a must phrasing (adopt (OPTIONAL) language) rather than carrying the conflict forward.

No blocking questions — the issue is well-researched and actionable as written.

Automated triage by Rosetta agent

[isolomatov-gd]

🤖 Planning started by AI agent.

[isolomatov-gd]

🤖 Implementation started by AI agent.

[isolomatov-gd]

Implemented in PR #360. The PR retires QUICKSTART.md, migrates its unique guidance, repairs active links, and updates the legacy MCP compatibility-notice URL.