griddynamics · isolomatov-gd · Sep 14, 2026
diff --git a/CONFIGURATION.md b/CONFIGURATION.md
@@ -2,7 +2,7 @@
 
 **Who is this for?** Engineers setting up a workspace (in the VS Code sense) for the first time, so AI coding agents work well in it.
 
-**When should I read this?** After you connect Rosetta (see [Quick Start](QUICKSTART.md)), and before you start real coding or modernization work.
+**When should I read this?** After you connect Rosetta (see [Quick Start](README.md#quick-start)), and before you start real coding or modernization work.
 
 ---
 
@@ -16,8 +16,8 @@ If you are migrating or modernizing a codebase, do the steps below first, then r
 
 ## 1. Install and Onboard
 
-1. Connect Rosetta to your IDE — follow the [Quick Start](QUICKSTART.md).
-2. Onboard the repository to Rosetta (Quick Start, Step 2). This is required before the steps below.
+1. Connect Rosetta to your IDE — follow [PLUGINS.md](PLUGINS.md), [MCPs.md](MCPs.md), or [INSTALLATION.md](INSTALLATION.md).
+2. Onboard the repository to Rosetta — follow [Installation — Initialize Repository](INSTALLATION.md#step-4-initialize-repository). This is required before the steps below.
 
 ---
 
@@ -189,7 +189,7 @@ Setup actions:
 
 - Open the repository in your IDE.
 - Clone any read-only reference codebases into `refsrc/` as subfolders.
-- Initialize Rosetta (see [Quick Start](QUICKSTART.md)).
+- Initialize Rosetta (see [Installation — Initialize Repository](INSTALLATION.md#step-4-initialize-repository)).
 
 <details>
 <summary><b>Detailed examples what should be in RefSrc folder</b></summary>
@@ -328,7 +328,7 @@ Setup actions:
 
 - Create a new empty git repository to serve as the composite workspace envelope.
 - Request AI to add each sub-repository (code, infra, QA, frontend, shared libraries, etc.) as a git submodule and clone them into the envelope.
-- Initialize Rosetta in the envelope workspace, telling it this is a composite workspace and that `ARCHITECTURE.md` must record that submodules are used for dynamic and optionally sparse-checkout (see [Quick Start](QUICKSTART.md)).
+- Initialize Rosetta in the envelope workspace, telling it this is a composite workspace and that `ARCHITECTURE.md` must record that submodules are used for dynamic and optionally sparse-checkout (see [Installation — Initialize Repository](INSTALLATION.md#step-4-initialize-repository)).
 - Development teams can then use sparse-checkout on modules and/or they can select submodules they need.
 - AI can dynamically check out a missing submodule at any point: `git submodule update --init <name>`.
 
@@ -369,7 +369,7 @@ Setup actions:
 - Create a new empty git repository to serve as the composite workspace envelope.
 - Clone each sub-repository (code, infra, QA, frontend, shared libraries, etc.) into the envelope as a plain folder.
 - Add each cloned folder to `.gitignore` so it is excluded from the envelope's git tracking.
-- Initialize Rosetta in the envelope workspace, telling it this is a composite workspace (see [Quick Start](QUICKSTART.md)).
+- Initialize Rosetta in the envelope workspace, telling it this is a composite workspace (see [Installation — Initialize Repository](INSTALLATION.md#step-4-initialize-repository)).
 
 ---
 
@@ -402,3 +402,8 @@ The old code in `refsrc/` keeps its own `docs/CONTEXT.md` and `docs/ARCHITECTURE
 
 - Use `/requirements-authoring-flow` or `Allium` to generate specs from the existing old code.
 - Use `/coding-flow` for unit tests and `/ui-aqa-flow` for e2e tests to cover the old code before you change it.
+
+## Next Steps
+
+- [Workflows](USAGE_GUIDE.md#workflows) — choose and run the right Rosetta workflow.
+- [Best Practices](USAGE_GUIDE.md#best-practices) — use the practices that improve workflow results.
diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md
@@ -70,7 +70,7 @@ fork/clone → branch → edit → validate → push → PR
 5. **Test on DEV environment.**
    - Uninstall `local-files-mode.md` from target repository
    - [Publish to dev](#dev-environment-integration-testing)
-   - Enable Rosetta MCP or follow [Quick Start Guide](QUICKSTART.md) to install it
+   - Enable Rosetta MCP or follow [Installation](INSTALLATION.md) to install it
    - Use dev server URL `<rosetta MCP development server URL>`
    - Test end-to-end through the HTTP MCP
 
@@ -224,7 +224,7 @@ codex mcp add Rosetta \
 
 **Pre-release builds:** Version suffixes like `b00` trigger automatic pre-release publishing. Use `--prerelease=allow` with uvx to pull these builds.
 
-Add the bootstrap rule to your IDE as defined in [Quick Start — Add Bootstrap Rule](QUICKSTART.md#step-2-add-bootstrap-rule).
+Add the bootstrap rule to your IDE as defined in [Installation — Add Bootstrap Rule](INSTALLATION.md#step-2-add-bootstrap-rule-http-and-stdio-modes-only).
 
 ---
 
@@ -393,7 +393,7 @@ codex mcp add Rosetta --url <rosetta MCP development server URL>
 
 Authenticate via OAuth as required.
 
-Add the bootstrap rule to your IDE as defined in [Quick Start — Add Bootstrap Rule](QUICKSTART.md#step-2-add-bootstrap-rule).
+Add the bootstrap rule to your IDE as defined in [Installation — Add Bootstrap Rule](INSTALLATION.md#step-2-add-bootstrap-rule-http-and-stdio-modes-only).
 
 ### 4. Test CLI changes
 
@@ -439,7 +439,6 @@ Always publish the **entire** `/instructions` folder. Never subfolders or single
 The short version:
 
 - **README** — orientation, what and why
-- **QUICKSTART** — zero to working setup
 - **PLUGINS** — install as a plugin (recommended)
 - **MCPs** — install via MCP (optional, secondary)
 - **OVERVIEW** — mental model, terminology
@@ -620,7 +619,7 @@ Upgrading a workspace from R2 to R3 requires no structural migration — the fol
 
 - [Contributing](CONTRIBUTING.md) — fastest path to a merged PR
 - [Architecture](docs/ARCHITECTURE.md) — system structure, components, data flow
-- [Quickstart](QUICKSTART.md) — zero to working setup
+- [Quick Start](README.md#quick-start) — zero to working setup
 - [Overview](OVERVIEW.md) — mental model, key concepts
 - [Review Standards](REVIEW.md) — what reviewers verify
 - [Usage Guide](USAGE_GUIDE.md) — how to use Rosetta flows

diff --git a/FAQ.md b/FAQ.md
@@ -17,7 +17,7 @@ If none of these are true, Rosetta is not active for this session. See [INSTALLA
 
 **How do I install Rosetta for the first time?**
 
-See the [Quick Start Guide](QUICKSTART.md) for the fastest path, or [INSTALLATION.md](INSTALLATION.md) for the full setup including the fallback bootstrap rule. Once installed, [QUICKSTART.md](QUICKSTART.md) walks you through your first session.
+See the [Quick Start](README.md#quick-start) for the fastest path, or [INSTALLATION.md](INSTALLATION.md) for the full setup including the fallback bootstrap rule. Once installed, follow [Installation — Initialize Repository](INSTALLATION.md#step-4-initialize-repository) for your first session.
 
 **Which Rosetta release should I use?**
 
@@ -77,7 +77,7 @@ Pick a **medium** model — **Sonnet 5**, **GPT-5.6-terra-medium**, or **gemini-
 - **Running everything on a high-reasoning/Opus model.** Opus-class models spend heavily on reasoning and can exhaust a daily balance in one sitting. Rosetta already assigns an appropriate model per subagent and switches automatically, so you do not need to force the most expensive model for the whole session.
 - **Letting Auto pick the model.** Auto often downgrades to a weaker model mid-task, producing low-quality results. Choose the model explicitly.
 
-See the model guidance in [QUICKSTART.md](QUICKSTART.md).
+Use the model guidance in the [Model Selection](#model-selection) section above.
 
 **How do I reduce token cost?**
 

diff --git a/INSTALLATION.md b/INSTALLATION.md
@@ -1,7 +1,7 @@
 # Installation
 
 **Who is this for?** Complete setup reference for all installation modes.
-**When should I read this?** When you need the full picture: plugins, offline, or the optional MCP modes (HTTP, STDIO) and their environment variables. For the fastest path, see [QUICKSTART.md](QUICKSTART.md).
+**When should I read this?** When you need the full picture: plugins, offline, or the optional MCP modes (HTTP, STDIO) and their environment variables. For the fastest path, see the [Quick Start](README.md#quick-start).
 
 > [!CAUTION]
 > You must receive prior approval from your manager and company to use Rosetta.
@@ -719,7 +719,7 @@ After initialization, Rosetta maintains these files in your repository. Read mor
 ## Related Docs
 
 - [PLUGINS.md](PLUGINS.md) - plugin contents and capabilities
-- [QUICKSTART.md](QUICKSTART.md) - fastest path to a working setup
+- [Quick Start](README.md#quick-start) - fastest path to a working setup
 - [MCPs.md](MCPs.md) - when and how to use the optional MCP path
 - [OVERVIEW.md](OVERVIEW.md) - mental model and terminology
 - [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - common issues and fixes

diff --git a/MCPs.md b/MCPs.md
@@ -204,7 +204,7 @@ It should use Rosetta MCP to retrieve agents, guardrails, and instructions:
 
 Once the MCP is verified:
 
-- **Run your first session and initialize the repo** — see [QUICKSTART.md](QUICKSTART.md).
+- **Run your first session and initialize the repo** — see [Installation — Initialize Repository](INSTALLATION.md#step-4-initialize-repository).
 - **Explore the workflows** (coding, requirements authoring, modernization, and more) — see [USAGE_GUIDE.md — Workflows](USAGE_GUIDE.md#workflows).
 
 ## Links

diff --git a/OVERVIEW.md b/OVERVIEW.md
@@ -111,7 +111,7 @@ Layers at the same resource path get merged: in Plugin mode, the generator merge
 ## Related Docs
 
 - [User Guide](user-guide/README.md) — using Rosetta day to day
-- [Quick Start](QUICKSTART.md) — zero to working setup
+- [Quick Start](README.md#quick-start) — zero to working setup
 - [Usage Guide](USAGE_GUIDE.md) — how to use Rosetta flows
 - [Contributing](CONTRIBUTING.md) — fastest path to a merged PR
 - [Architecture](docs/ARCHITECTURE.md) — system structure, components, data flow

diff --git a/PLUGINS.md b/PLUGINS.md
@@ -160,5 +160,5 @@ See [INSTALLATION.md#upgrading](INSTALLATION.md#upgrading) for upgrade instructi
 Once the plugin is verified:
 
 - **Use Rosetta day to day** — see the [User Guide](user-guide/README.md).
-- **Run your first session and initialize the repo** — see [QUICKSTART.md](QUICKSTART.md).
+- **Run your first session and initialize the repo** — see [Installation — Initialize Repository](INSTALLATION.md#step-4-initialize-repository).
 - **Explore the workflows** (coding, requirements authoring, modernization, and more) — see [USAGE_GUIDE.md — Workflows](USAGE_GUIDE.md#workflows).
diff --git a/QUICKSTART.md b/QUICKSTART.md
diff --git a/README.md b/README.md
@@ -36,13 +36,13 @@ Rosetta-guided work follows five phases — **Prepare → Research → Plan →
 
 Read more in the [User Guide](user-guide/README.md).
 
-## [Quick Start](QUICKSTART.md)
+## Quick Start
 
-Overall Process: **Install** (plugin preferred) → **Initialize** workspace → **Configure** workspace ecosystem (tools, MCPs) → **Proceed** with Coding, Modernization, Analysis, etc.
+**Install** Rosetta: use [PLUGINS.md](PLUGINS.md) when your IDE supports a plugin, or [MCPs.md](MCPs.md) when you need MCP. For every mode and the bootstrap fallback, see [INSTALLATION.md](INSTALLATION.md).
 
-Please follow **[Quick Start Guide](QUICKSTART.md)** which will walk you through the process.
+**Initialize** the repository once: follow [Installation — Initialize Repository](INSTALLATION.md#step-4-initialize-repository).
 
-Very detailed information on installation and configuration in all available modes is in [Installation Guide](INSTALLATION.md).
+**Configure** its context and tooling: use [CONFIGURATION.md](CONFIGURATION.md). Then use the [Usage Guide](USAGE_GUIDE.md) for coding, modernization, analysis, and other workflows.
 
 ## [Top Workflows](USAGE_GUIDE.md#workflows)
 
@@ -217,7 +217,7 @@ Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for workflow and e
 | I want to...                                         | Read                                       |
 | ---------------------------------------------------- | ------------------------------------------ |
 | Use Rosetta day to day                               | [User Guide](user-guide/README.md)         |
-| Set up Rosetta                                       | [QUICKSTART.md](QUICKSTART.md)             |
+| Set up Rosetta                                       | [Quick Start](#quick-start)                |
 | Install as a plugin (recommended)                    | [PLUGINS.md](PLUGINS.md)                   |
 | Connect over MCP (optional, secondary)               | [MCPs.md](MCPs.md)                         |
 | Configure your coding-agent workspace                | [CONFIGURATION.md](CONFIGURATION.md)       |