From 72c093d95894f8ca2bdf179c0405248390e9fa80 Mon Sep 17 00:00:00 2001
From: Yuri <yuri_makaruk@apple.com>
Date: Tue, 12 May 2026 12:42:52 +0300
Subject: [PATCH 1/6] docs: rewrite Quick Start as short developer guide
 (CTORNDGAIN-1301)

- Plugin-first install; MCP demoted to labeled fallback
- Bootstrap rule promoted to mandatory step for MCP mode
- Real example regenerated against canonical coding-flow.md
- New Customize page with worked examples (CONTEXT.md, rules, MCPs)
- Sidebar + docs index updated to include Customize

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/web/_layouts/docs.html |   1 +
 docs/web/docs/customize.md  | 209 ++++++++++++++++++++++++++++
 docs/web/docs/index.md      |   5 +
 docs/web/docs/quickstart.md | 269 +++++++++++++++---------------------
 4 files changed, 329 insertions(+), 155 deletions(-)
 create mode 100644 docs/web/docs/customize.md

diff --git a/docs/web/_layouts/docs.html b/docs/web/_layouts/docs.html
index 4efe9ba7..b4524ef1 100644
--- a/docs/web/_layouts/docs.html
+++ b/docs/web/_layouts/docs.html
@@ -44,6 +44,7 @@
 
     <p class="docs-sidebar-cat">Guides</p>
     <a href="{{ '/docs/usage-guide/' | relative_url }}" class="docs-sidebar-link{% if page.url == '/docs/usage-guide/' %} active{% endif %}">Usage Guide</a>
+    <a href="{{ '/docs/customize/' | relative_url }}" class="docs-sidebar-link{% if page.url == '/docs/customize/' %} active{% endif %}">Customize</a>
     <a href="{{ '/docs/deployment/' | relative_url }}" class="docs-sidebar-link{% if page.url == '/docs/deployment/' %} active{% endif %}">Deployment</a>
     <a href="{{ '/docs/troubleshooting/' | relative_url }}" class="docs-sidebar-link{% if page.url == '/docs/troubleshooting/' %} active{% endif %}">Troubleshooting</a>
 
diff --git a/docs/web/docs/customize.md b/docs/web/docs/customize.md
new file mode 100644
index 00000000..0bd90a8c
--- /dev/null
+++ b/docs/web/docs/customize.md
@@ -0,0 +1,209 @@
+---
+layout: docs
+title: Customize
+permalink: /docs/customize/
+---
+
+# Customize Rosetta for your project
+
+Rosetta works out of the box. These three things make it work *better* — adapted to how your team actually writes code.
+
+All three are optional. They stack in impact: invest in #1 first, add #2 and #3 only when you hit the specific need.
+
+---
+
+## 1. Improve your context files
+
+**The single highest-leverage customization.** Every Rosetta workflow reads `docs/CONTEXT.md` and `docs/ARCHITECTURE.md` before doing anything. The more these files cover, the fewer questions Rosetta asks and the better the output.
+
+### What they are
+
+These files are created automatically when you run "Initialize this repository using Rosetta". After init, you edit them by hand to fill the gaps.
+
+| File                  | What goes in it                                                                                                  |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `docs/CONTEXT.md`     | **The why.** Business purpose, user types, key workflows, domain constraints, what success looks like.           |
+| `docs/ARCHITECTURE.md`| **The how.** System components, data flow, deployment topology, integration points, key design decisions.        |
+| `docs/TECHSTACK.md`   | **The what.** Languages, frameworks, libraries, tools, plus *why* each was chosen (helps Rosetta avoid wrong replacements). |
+
+### When to do it
+
+- Rosetta keeps asking the same questions across different tasks
+- Output keeps missing a convention your team takes for granted
+- A new engineer joins and you wish they could read one file to understand the project — that file should be CONTEXT.md
+- You're about to start a non-trivial feature and want to front-load the context
+
+### Example: thin vs fleshed-out CONTEXT.md
+
+**Thin (what init often produces if your repo lacks signals):**
+
+```markdown
+# Context
+
+This project is a REST API for managing customer orders.
+Built with Node.js and PostgreSQL.
+```
+
+→ Rosetta will ask about auth, payment integration, multi-tenancy, error format,
+idempotency, and 5 other things before it can plan any feature.
+
+**Fleshed out:**
+
+```markdown
+# Context
+
+## Purpose
+B2B order management API used by 40 enterprise customers. Handles
+order intake, fulfillment routing, and invoice generation. Replaces
+a legacy SAP module.
+
+## Key constraints
+- Multi-tenant: every table has `tenant_id`, every query MUST filter on it
+- Idempotency required on all POSTs — clients retry aggressively
+- Invoices are immutable once issued (audit requirement)
+- All money is stored as integer cents, never floats
+
+## Integration points
+- Auth: Okta SSO + service-to-service JWT (see ARCHITECTURE.md)
+- Payments: Stripe Connect (we never touch card data)
+- Fulfillment: outbound webhooks to 3 warehouse partners
+
+## What "done" looks like
+- Endpoint has OpenAPI spec, 80%+ test coverage, idempotency key support,
+  tenant filter, structured error response `{ error: { code, message } }`
+```
+
+→ Rosetta now plans a feature with idempotency, tenant filtering, and the
+correct error shape on the first pass. No follow-up questions.
+
+### Tip: spot when yours needs work
+
+After a few Rosetta sessions, look at the questions Rosetta asked. Every
+recurring question is a CONTEXT.md or ARCHITECTURE.md gap.
+
+---
+
+## 2. Add project-specific rules
+
+**For hard rules you want enforced every time.** Drop a markdown file alongside Rosetta — no Rosetta files modified. Rosetta loads your project rules on top of its own.
+
+### When to do it
+
+- "Always use pnpm, never npm/yarn"
+- "All new endpoints must use the standard error middleware"
+- "No `console.log` — use the structured logger from `lib/log.ts`"
+- "Tests must use Vitest, not Jest"
+- "All React components must be functional with hooks; no class components"
+
+If you find yourself correcting Rosetta the same way twice, that's a rule.
+
+### Where to put rules
+
+| IDE                              | Path (any `.md` file works)    |
+| -------------------------------- | ------------------------------ |
+| Cursor                           | `.cursor/rules/*.mdc`          |
+| Claude Code                      | `.claude/rules/*.md`           |
+| Windsurf                         | `.windsurf/rules/*.md`         |
+| JetBrains (Junie + AI Assistant) | `.aiassistant/rules/agents.md` |
+| Antigravity                      | `.agent/rules/*.md`            |
+| OpenCode                         | `.opencode/agent/*.md`         |
+| VS Code / GitHub Copilot         | `.github/copilot-instructions.md` |
+
+### Example: an API conventions rule
+
+Save as `.claude/rules/api-conventions.md` (or the equivalent path for your IDE):
+
+```markdown
+# API conventions
+
+Apply when adding, modifying, or reviewing any HTTP endpoint.
+
+## Required for every endpoint
+
+1. **Tenant filter.** Every query MUST include `WHERE tenant_id = $1`.
+   Reject if missing — no exceptions.
+2. **Idempotency.** POSTs must accept `Idempotency-Key` header and dedupe
+   via the `idempotency_keys` table.
+3. **Error shape.** Errors return `{ error: { code: string, message: string } }`.
+   Codes from `lib/errors/codes.ts`. Never leak raw DB or stack messages.
+4. **Validation.** Use Zod schemas in `schemas/`. No inline validation.
+5. **Tests.** At least one happy path + one tenant-isolation test
+   (verify cross-tenant request returns 404, not 403).
+
+## Forbidden
+
+- `console.log` — use `logger` from `lib/log.ts`
+- Raw SQL string concatenation — use parameterized queries or the query builder
+- Returning DB rows directly — always map through a DTO in `dto/`
+```
+
+→ Rosetta now applies all of this automatically. You stop catching the same
+mistakes in review.
+
+### Tips
+
+- **One file per topic.** `api-conventions.md`, `testing.md`, `logging.md` — easier to skim than one mega-file.
+- **State the trigger.** Start with "Apply when…" so Rosetta knows when the rule activates.
+- **Show, don't tell.** Bad/good code snippets beat prose explanations.
+
+---
+
+## 3. Add helper MCPs
+
+**To give Rosetta capabilities beyond your codebase.** MCPs are tools your AI agent can call — Rosetta is one of them, but you can add more.
+
+### When to do it
+
+- Rosetta hallucinates library APIs → add a docs MCP (Context7)
+- You need the agent to test a web page → add a browser MCP (Playwright / Chrome DevTools)
+- Agent needs to read your DB schema or run queries → add a database MCP
+- You want it to look up Jira tickets or Figma designs → add the matching MCP
+
+### The top 3
+
+Add these to the same IDE config file where you added Rosetta.
+
+**Context7** — up-to-date library/framework docs. Best ROI of any MCP.
+
+```json
+{
+  "mcpServers": {
+    "Rosetta": { "url": "https://mcp.rosetta.griddynamics.net/mcp" },
+    "Context7": { "url": "https://mcp.context7.com/mcp" }
+  }
+}
+```
+
+**Playwright MCP** — drive a real browser, fill forms, click elements, scrape pages.
+
+```json
+{ "playwright": { "command": "npx", "args": ["-y", "@playwright/mcp@latest"] } }
+```
+
+**Chrome DevTools MCP** — full Chrome control: console, network tab, snapshots.
+
+```json
+{ "chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp"] } }
+```
+
+Full list with use cases: [Usage Guide → Recommended MCP Servers](/rosetta/docs/usage-guide/#recommended-mcp-servers).
+
+---
+
+## How they stack
+
+| Layer            | Effort        | Impact   | Best for                                      |
+| ---------------- | ------------- | -------- | --------------------------------------------- |
+| Context files    | 30–60 min     | Huge     | Every project. Do this first.                 |
+| Project rules    | 5–10 min each | High     | Recurring corrections, team conventions.      |
+| Helper MCPs      | 1 min each    | Variable | Specific capabilities Rosetta is missing.     |
+
+Start with #1. Add a rule the first time you correct Rosetta twice. Add an MCP the first time Rosetta says "I'd need to check the docs for that."
+
+---
+
+## Going deeper
+
+- [Quick Start](/rosetta/docs/quickstart/) — installation and basics
+- [Usage Guide](/rosetta/docs/usage-guide/) — every workflow, skill, and agent
+- [Architecture](/rosetta/docs/architecture/) — how Rosetta loads and applies these layers under the hood
diff --git a/docs/web/docs/index.md b/docs/web/docs/index.md
index 98cb9450..bf4a8a5c 100644
--- a/docs/web/docs/index.md
+++ b/docs/web/docs/index.md
@@ -45,6 +45,11 @@ Rosetta is a meta-prompting, context engineering, and centralized instructions m
     <p class="docs-index-card-title">Usage Guide</p>
     <p class="docs-index-card-desc">Workflows, skills, agents, customization, and best practices.</p>
   </a>
+  <a href="/rosetta/docs/customize/" class="docs-index-card">
+    <p class="docs-index-card-cat">Guides</p>
+    <p class="docs-index-card-title">Customize</p>
+    <p class="docs-index-card-desc">Adapt Rosetta to your project: context files, project rules, helper MCPs — with examples.</p>
+  </a>
   <a href="/rosetta/docs/deployment/" class="docs-index-card">
     <p class="docs-index-card-cat">Guides</p>
     <p class="docs-index-card-title">Deployment</p>
diff --git a/docs/web/docs/quickstart.md b/docs/web/docs/quickstart.md
index 16e021be..d7423c94 100644
--- a/docs/web/docs/quickstart.md
+++ b/docs/web/docs/quickstart.md
@@ -4,235 +4,194 @@ title: Quick Start
 permalink: /docs/quickstart/
 ---
 
-# Quick Start
+# Overview
 
-**Who is this for?** New users setting up Rosetta for the first time.
+Rosetta gives your AI coding agent your team's context, standards, and guardrails — across any IDE.
 
-**When should I read this?** When you want to go from zero to a working setup.
+You install Rosetta in your IDE, ask the agent "Initialize this repository using Rosetta", and it produces a plan + code + tests with the conventions of your codebase, not generic ones.
+
+> **Use a strong model.** Sonnet 4.6, GPT-5.3-codex-medium, gemini-3.1-pro, or better. Avoid Auto. Weaker models silently skip Rosetta's tools.
 
 ---
 
-## Step 1: Connect Rosetta MCP
+## 1. Install
 
-> [!WARNING]
-> You must receive a prior approval from your manager and company to use it.
+Two options. **Pick A if your IDE supports a plugin** — it's the recommended path. Otherwise use B.
 
-> [!WARNING]
-> Use **Sonnet 4.6**, **GPT-5.3-codex-medium**, **gemini-3.1-pro** or better models. Avoid Auto model selection.
+### Option A — Plugin (recommended)
 
-> [!NOTE]
-> Rosetta is designed to never use or see data or IP.
-> Instead it uses inversion of control, by providing a "menu" to AI coding agents.
+A plugin bundles Rosetta's bootstrap rule, skills, agents, and workflows directly into your IDE. No MCP wiring, no manual bootstrap file.
 
-Rosetta uses HTTP MCP transport with OAuth. Pick your IDE and add the configuration.
+| IDE                          | Install                                                                                                                                    |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Claude Code**              | `claude plugin marketplace add griddynamics/rosetta` then `claude plugin install core@rosetta`                                              |
+| **VS Code / GitHub Copilot** | Install `core-copilot` via VS Code Copilot Plugins                                                                                          |
+| **JetBrains / Copilot**      | Zip + manual config — see [Installation](/rosetta/docs/installation/#plugin-based-installation)                                             |
+| **Codex**                    | Zip + `codex features enable codex_hooks` — see [Installation](/rosetta/docs/installation/#plugin-based-installation)                       |
 
-<details markdown="1">
-<summary><b>Cursor</b></summary>
+> Plugins are the recommended install path — clients prefer them over MCP, and the install bundles everything you need (bootstrap rule, skills, agents, workflows). If a plugin isn't available for your IDE yet, use Option B.
 
-Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
+Done with Option A → skip to **[Verify](#2-verify)**.
 
-```json
-{
-  "mcpServers": {
-    "Rosetta": {
-      "url": "https://mcp.rosetta.griddynamics.net/mcp"
-    }
-  }
-}
-```
+### Option B — MCP + bootstrap (fallback)
 
-</details>
+Use this when your IDE doesn't have a plugin yet, or your environment requires it.
 
-<details markdown="1">
+**B.1 — Connect Rosetta MCP**
+
+<details markdown="1" open>
 <summary><b>Claude Code</b></summary>
 
 ```sh
 claude mcp add --transport http Rosetta https://mcp.rosetta.griddynamics.net/mcp
 ```
 
-Authenticate inside a claude session with `/mcp`, select Rosetta, Authenticate, and complete the OAuth flow.
-
+Then start `claude` and, inside the session, type `/mcp` → select **Rosetta** → **Authenticate** to complete OAuth.
 </details>
 
 <details markdown="1">
-<summary><b>Codex</b></summary>
-
-```sh
-codex mcp add Rosetta --url https://mcp.rosetta.griddynamics.net/mcp
-codex mcp login Rosetta
-```
+<summary><b>Cursor / Windsurf</b></summary>
 
-</details>
-
-<details markdown="1">
-<summary><b>VS Code / GitHub Copilot</b></summary>
-
-Add to `.vscode/mcp.json` or `~/.mcp.json`:
+`~/.cursor/mcp.json` (or project-local `.cursor/mcp.json`):
 
 ```json
-{
-  "servers": {
-    "Rosetta": {
-      "url": "https://mcp.rosetta.griddynamics.net/mcp"
-    }
-  }
-}
+{ "mcpServers": { "Rosetta": { "url": "https://mcp.rosetta.griddynamics.net/mcp" } } }
 ```
-
 </details>
 
 <details markdown="1">
-<summary><b>GitHub Copilot (JetBrains)</b></summary>
+<summary><b>VS Code / GitHub Copilot</b></summary>
 
-`Settings` > `Tools` > `GitHub Copilot` > `MCP Settings`. Add to `~/.config/github-copilot/intellij/mcp.json`:
+`.vscode/mcp.json` or `~/.mcp.json`:
 
 ```json
-{
-  "servers": {
-    "Rosetta": {
-      "url": "https://mcp.rosetta.griddynamics.net/mcp"
-    }
-  }
-}
+{ "servers": { "Rosetta": { "url": "https://mcp.rosetta.griddynamics.net/mcp" } } }
 ```
-
-Restart IDE after changes.
-
 </details>
 
 <details markdown="1">
-<summary><b>JetBrains Junie</b></summary>
-
-`Settings` > `Tools` > `Junie` > `MCP Settings` > `+ Add` > `As JSON`:
+<summary><b>Codex / JetBrains / Antigravity / OpenCode</b></summary>
 
-```json
-{
-  "mcpServers": {
-    "Rosetta": {
-      "url": "https://mcp.rosetta.griddynamics.net/mcp"
-    }
-  }
-}
+```sh
+# Codex
+codex mcp add Rosetta --url https://mcp.rosetta.griddynamics.net/mcp && codex mcp login Rosetta
 ```
 
+JetBrains Junie: `Settings → Tools → Junie → MCP Settings → + Add → As JSON`, use the Cursor JSON above.
+GitHub Copilot (JetBrains): `Settings → Tools → GitHub Copilot → MCP Settings`, edit `~/.config/github-copilot/intellij/mcp.json` with the VS Code JSON above.
+Antigravity / OpenCode: see [Installation](/rosetta/docs/installation/).
 </details>
 
-<details markdown="1">
-<summary><b>Windsurf</b></summary>
+> For the full list of IDEs, see [Installation](/rosetta/docs/installation/).
 
-Add to your Windsurf MCP config:
+**B.2 — Add the bootstrap rule (mandatory for MCP mode)**
 
-```json
-{
-  "mcpServers": {
-    "Rosetta": {
-      "url": "https://mcp.rosetta.griddynamics.net/mcp"
-    }
-  }
-}
-```
+MCP alone doesn't reliably trigger Rosetta on every request. You must drop a small markdown file (`bootstrap.md`) into your IDE's instructions so the agent calls Rosetta before doing anything.
 
-</details>
+Download [bootstrap.md](https://github.com/griddynamics/rosetta/blob/main/instructions/r2/core/rules/bootstrap.md?plain=1) and place it at the path for your IDE:
 
-<details markdown="1">
-<summary><b>Antigravity</b></summary>
+| IDE                            | Path                              |
+| ------------------------------ | --------------------------------- |
+| Cursor                         | `.cursor/rules/bootstrap.mdc`     |
+| Claude Code                    | `.claude/claude.md`               |
+| VS Code / Copilot (any)        | `.github/copilot-instructions.md` |
+| JetBrains Junie                | `.junie/guidelines.md`            |
+| Windsurf                       | `.windsurf/rules/bootstrap.md`    |
+| Antigravity                    | `.agent/rules/bootstrap.md`       |
+| OpenCode                       | `AGENTS.md`                       |
 
-Add to your Antigravity MCP config:
+Keep the file's YAML frontmatter intact.
 
-```json
-{
-  "mcpServers": {
-    "Rosetta": {
-      "serverUrl": "https://mcp.rosetta.griddynamics.net/mcp"
-    }
-  }
-}
-```
+## 2. Verify
 
-</details>
+```
+What can you do, Rosetta?
+```
 
-<details markdown="1">
-<summary><b>OpenCode</b></summary>
+The agent should list Rosetta's workflows and capabilities. If it doesn't, jump to [Setup issues](#setup-issues).
 
-Add to `opencode.json`:
+## 3. Initialize your repo
 
-```json
-{
-  "mcp": {
-    "Rosetta": {
-      "type": "http",
-      "url": "https://mcp.rosetta.griddynamics.net/mcp",
-      "enabled": true
-    }
-  }
-}
+```
+Initialize this repository using Rosetta
 ```
 
-</details>
+Rosetta scans your stack, generates `docs/TECHSTACK.md`, `docs/CODEMAP.md`, `docs/DEPENDENCIES.md`, `docs/CONTEXT.md`, `docs/ARCHITECTURE.md`, and asks you to fill the gaps. **Restart your chat session afterward** so the new context loads.
 
-Any MCP client that supports HTTP transport can connect using the endpoint URL. Complete the OAuth flow when prompted.
+Run once per repo. For composite workspaces, init each repo first, then run init at workspace level with "This is composite workspace" appended.
 
-STDIO transport is available for air-gapped environments. See [Installation](/rosetta/docs/installation/).
+---
 
-## Step 2: Verify
+## A real example
 
-Ask the agent:
+> *A **workflow** is what Rosetta runs to do the work — coding, init, requirements, etc. Rosetta picks the workflow from your request automatically.*
 
 ```
-What can you do, Rosetta?
+You: "Add password reset functionality"
+
+Rosetta routes this to the coding workflow:
+
+  • Discovery        – discoverer subagent gathers affected code,
+                       dependencies, conventions
+  • Specs + plan     – architect writes SPECS.md (the what) and
+                       PLAN.md (the how) in plans/PASSWORD-RESET/
+  • Plan review      – reviewer inspects them against your request
+  → Your approval    – say "Yes, I reviewed the plan"
+  • Implementation   – engineer codes only the approved scope;
+                       build must pass
+  • Code review      – reviewer inspects the diff against specs
+  • Validation       – validator checks coverage & gaps
+  → Your approval    – say "Yes, I approve the implementation"
+  • Tests            – engineer writes and runs tests
+  • Tests review     – reviewer checks scenarios and coverage
+  • Final validation – end-to-end pass
 ```
 
-It should use Rosetta MCP to retrieve agents, guardrails, and instructions.
+Small tasks collapse into fewer phases and a single approval gate. You always know what's about to happen — Rosetta stops at the gates and waits for your explicit go-ahead.
 
-## Step 3: Initialize (once per repository)
+## Common requests
 
-Ask the agent:
+Plain language. Rosetta picks the workflow.
 
-```
-Initialize this repository using Rosetta
-```
+| Say this                                              | What runs              |
+| ----------------------------------------------------- | ---------------------- |
+| "Add / fix / change \<feature\>"                      | Coding workflow        |
+| "Initialize this repository"                          | Init workflow          |
+| "Explain how \<module\> works"                        | Code analysis          |
+| "Define requirements for \<feature\>"                 | Requirements authoring |
+| "Ad-hoc: \<small or weird task\>"                     | Composed flow          |
+| "What can you do, Rosetta?" / "What workflows exist?" | Self-help              |
 
-The agent will analyze your tech stack, generate documentation (TECHSTACK.md, CODEMAP.md, DEPENDENCIES.md, ARCHITECTURE.md, CONTEXT.md), and ask clarifying questions. Read more about [workspace files](/rosetta/docs/installation/#workspace-files-created) and [all workflows](/rosetta/docs/usage-guide/#workflows).
+Pro workflows (Research, Modernization, Test Generation, Automated QA, External Library, Prompting) need the enterprise edition — see [Usage Guide](/rosetta/docs/usage-guide/#workflows).
 
-> [!NOTE]
-> **Prefer medium models:** High reasoning and Opus models consume too much token on reasoning.
-> **Composite workspaces:** init each repository separately, then init at the workspace level with "This is composite workspace" appended.
-> **Dead code or existing specs:** mention their location in the prompt to save time.
+## Setup issues
 
-## Step 4: Add Bootstrap Rule (optional)
+| Symptom                          | Fix                                                                                                                                                          |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| OAuth prompt never appears       | Restart IDE. In Claude Code, run `claude`, then in-session: `/mcp` → Rosetta → Authenticate.                                                                  |
+| Agent ignores Rosetta tools      | **MCP mode:** confirm `bootstrap.md` is in place (Step B.2) and the MCP server shows connected. **Plugin mode:** confirm plugin installed via `claude plugin list`. |
+| Agent worked, then stopped       | OAuth token expired. Re-authenticate. Tools still appear but instructions stop loading.                                                                       |
+| Inconsistent / shallow output    | Wrong model. Switch off Auto and use Sonnet 4.6 / GPT-5.3-codex-medium / gemini-3.1-pro.                                                                       |
+| Slow or empty replies            | Check network reaches `mcp.rosetta.griddynamics.net`. First-time init on large repos is slow — that's expected.                                              |
 
-If something does not work.
+Full diagnostics: [Troubleshooting](/rosetta/docs/troubleshooting/).
 
-Download [bootstrap.md](https://github.com/griddynamics/rosetta/blob/main/instructions/r2/core/rules/bootstrap.md?plain=1) and add it to your IDE's instruction file (keep entire contents, including YAML frontmatter):
+## Customize (optional)
 
-| IDE                        | Destination                       |
-| -------------------------- | --------------------------------- |
-| Cursor                     | `.cursor/rules/bootstrap.mdc`     |
-| Claude Code                | `.claude/claude.md`               |
-| VS Code / GitHub Copilot   | `.github/copilot-instructions.md` |
-| GitHub Copilot (JetBrains) | `.github/copilot-instructions.md` |
-| JetBrains Junie            | `.junie/guidelines.md`            |
-| Windsurf                   | `.windsurf/rules/bootstrap.md`    |
-| Antigravity                | `.agent/rules/bootstrap.md`       |
-| OpenCode                   | `AGENTS.md`                       |
+Three ways to make Rosetta work better for your project, ordered by impact: improve your context files, add project-specific rules, and add helper MCPs. None are required — start with the first when Rosetta begins asking the same questions repeatedly.
 
-## Common Issues
+See [Customize](/rosetta/docs/customize/) for the full how-to with real example rule files and configs.
 
-- **OAuth prompt does not appear:** restart your IDE and retry the connection. Read more in [Troubleshooting — Connection & Authentication](/rosetta/docs/troubleshooting/#connection--authentication).
-- **Agent ignores Rosetta tools:** confirm the MCP server shows as connected in your IDE's MCP settings. Add a [bootstrap rule](/rosetta/docs/installation/) if the agent still skips Rosetta. Read more in [Troubleshooting — Agent Not Using Rosetta](/rosetta/docs/troubleshooting/#agent-not-using-rosetta).
-- **Slow or empty responses:** check your network can reach your Rosetta MCP host. See [Troubleshooting](/rosetta/docs/troubleshooting/#slow-or-empty-responses).
+---
 
-## Next Steps
+## Going deeper
 
-- [Usage Guide](/rosetta/docs/usage-guide/) — how to use Rosetta flows
-- [Overview](/rosetta/docs/overview/) — mental model and terminology
-- [Deployment](/rosetta/docs/deployment/) — org-wide deployment
-- [Contributing](/rosetta/docs/contributing/) — make your first contribution
-- [Architecture](/rosetta/docs/architecture/) — system internals
+- [Usage Guide](/rosetta/docs/usage-guide/) — every workflow, skill, and agent in detail
+- [Architecture](/rosetta/docs/architecture/) — how Rosetta works under the hood
+- [Installation](/rosetta/docs/installation/) — STDIO, plugins, air-gapped, env vars
+- [Deployment](/rosetta/docs/deployment/) — running Rosetta org-wide
+- [Contributing](/rosetta/docs/contributing/) — submit a PR
 
-## Video Tutorials
+Stuck? [Discord](https://discord.gg/QzZ2cWg36g) · [Issues](https://github.com/griddynamics/rosetta/issues) · rosetta-support@griddynamics.com
 
-- [Install Using MCP](https://vimeo.com/1174124251/f38e017d8d?fl=ml&fe=ec) — step-by-step setup
-- [Install without MCP](https://vimeo.com/1174124213/c50179147c?fl=ml&fe=ec) — air-gapped environments
-- [Initialize with Antigravity](https://vimeo.com/1174124165/8f5fbd7775?fl=ml&fe=ec) — project initialization
-- [Subagents and Workflows in Claude Code](https://vimeo.com/1174124272/96056d5cc5?fl=ml&fe=ec) — advanced configuration
+> Rosetta is designed to never see your data or IP — it provides a "menu" of instructions to your agent, not the other way around. Get manager/company approval before using it on real codebases.

From c351d713d936ae7da78868df3758194549e7c465 Mon Sep 17 00:00:00 2001
From: Yuri <yuri_makaruk@apple.com>
Date: Tue, 12 May 2026 13:18:26 +0300
Subject: [PATCH 2/6] docs: align Quick Start example with canonical
 coding-flow.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cross-checked against docs/web/docs/coding-flow.md per Igor's review request:

- Phase names: "Specs + plan" → "Tech plan"; "Plan review" → "Review plan";
  "Code review" → "Review code"; "Tests review" → "Review tests"
- Artifact names use <FEATURE>-SPECS.md / <FEATURE>-PLAN.md placeholder
  with plans/PASSWORD-RESET/ as the concrete example
- Prompt updated to "Add password reset support to the customer portal.
  I want to review the plan first." (matches canonical "How To Start" style)
- Added scaling footnote: small tasks handle some phases inline and
  may combine the two HITL gates; approval still always explicit
- Linked to /docs/coding-flow/ for canonical phase reference

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/web/docs/quickstart.md | 28 +++++++++++++++-------------
 1 file changed, 15 insertions(+), 13 deletions(-)

diff --git a/docs/web/docs/quickstart.md b/docs/web/docs/quickstart.md
index d7423c94..4ee47624 100644
--- a/docs/web/docs/quickstart.md
+++ b/docs/web/docs/quickstart.md
@@ -127,27 +127,29 @@ Run once per repo. For composite workspaces, init each repo first, then run init
 > *A **workflow** is what Rosetta runs to do the work — coding, init, requirements, etc. Rosetta picks the workflow from your request automatically.*
 
 ```
-You: "Add password reset functionality"
+You: "Add password reset support to the customer portal.
+      I want to review the plan first."
 
-Rosetta routes this to the coding workflow:
+Rosetta loads the coding workflow:
 
   • Discovery        – discoverer subagent gathers affected code,
-                       dependencies, conventions
-  • Specs + plan     – architect writes SPECS.md (the what) and
-                       PLAN.md (the how) in plans/PASSWORD-RESET/
-  • Plan review      – reviewer inspects them against your request
+                       dependencies, constraints
+  • Tech plan        – architect writes <FEATURE>-SPECS.md (the what)
+                       and <FEATURE>-PLAN.md (the how) in the feature
+                       plan folder (e.g. plans/PASSWORD-RESET/)
+  • Review plan      – reviewer inspects them against your request
   → Your approval    – say "Yes, I reviewed the plan"
   • Implementation   – engineer codes only the approved scope;
-                       build must pass
-  • Code review      – reviewer inspects the diff against specs
-  • Validation       – validator checks coverage & gaps
+                       build must pass (tests are separate)
+  • Review code      – reviewer inspects the diff against the specs
+  • Validation       – validator checks spec coverage and gaps
   → Your approval    – say "Yes, I approve the implementation"
-  • Tests            – engineer writes and runs tests
-  • Tests review     – reviewer checks scenarios and coverage
-  • Final validation – end-to-end pass
+  • Tests            – engineer writes and runs isolated tests
+  • Review tests     – reviewer checks coverage and scenarios
+  • Final validation – end-to-end dependency check
 ```
 
-Small tasks collapse into fewer phases and a single approval gate. You always know what's about to happen — Rosetta stops at the gates and waits for your explicit go-ahead.
+Phases scale by task size: small tasks handle discovery, reviews, and validation inline, and may combine the two approval gates into one. Approval is still always explicit. See [Coding Flow](/rosetta/docs/coding-flow/) for the full canonical phase list with scaling rules.
 
 ## Common requests
 

From c8d8a96e5759bfd6d2084cbd33449620914d09ad Mon Sep 17 00:00:00 2001
From: Yuri <yuri_makaruk@apple.com>
Date: Wed, 13 May 2026 13:37:33 +0300
Subject: [PATCH 3/6] docs: refine Coding workflow section for clarity and
 conciseness

---
 docs/web/docs/coding-flow.md | 54 ++++++++----------------------------
 1 file changed, 11 insertions(+), 43 deletions(-)

diff --git a/docs/web/docs/coding-flow.md b/docs/web/docs/coding-flow.md
index 544b888e..7b2bafd9 100644
--- a/docs/web/docs/coding-flow.md
+++ b/docs/web/docs/coding-flow.md
@@ -4,48 +4,15 @@ title: Coding Flow
 permalink: /docs/coding-flow/
 ---
 
-# Coding Flow
+# Coding workflow
 
-## Availability
+When you ask Rosetta to **add, change, or fix code**, this is the workflow it runs. It produces a spec and plan first (which you approve), then the code, then tests — with explicit gates at the two points where you decide whether to continue.
 
-OSS. This workflow lives in the core Rosetta instruction set.
+> Available in: OSS core.
 
-## TL;DR
+## When to use it
 
-Use Coding Flow for implementation work when coding is the main job, including feature work, changes, and bug fixes.
-Rosetta structures that work through specs, a plan, review gates, validation, and tests.
-It is the workflow Rosetta uses for adding, changing, or fixing code when coding is the main job.
-It produces a plan package first, then code, review findings, validation findings, tests, and final validation evidence.
-You must explicitly approve the plan before implementation starts.
-You must explicitly approve the implementation before tests continue.
-The workflow applies at all request sizes. What changes by size is phase scaling, not whether the workflow should be used.
-Medium and large tasks add separate discovery, review, and validator work where the source marks those phases as `MEDIUM,LARGE`.
-For small tasks, the source says the plan-review and implementation-review checkpoints may be combined. This page keeps that conservative: approval is still explicit and tests still do not continue without it, but the source does not define a more detailed small-task checkpoint shape than that.
-
-## When To Use This Workflow
-
-- Add, change, or fix application code.
-- Implement work that needs an explicit spec and plan before coding.
-- Use reviewer and validator gates to catch drift before you approve work.
-- Handle code changes of any size when coding is the main job.
-- Expect the workflow to scale by request size instead of switching to a different coding workflow.
-
-## When Not To Use This Workflow
-
-- Use [Requirements Documentation Authoring Flow](/rosetta/docs/requirements-authoring-flow/) when expected behavior is still unclear and you need requirements before planning code.
-- Use [Code Analysis Flow](/rosetta/docs/code-analysis-flow/) when the goal is to understand existing code, not change it.
-- Use [Ad-hoc Flow](/rosetta/docs/adhoc-flow/) when no fixed workflow fits the task and you need a lighter custom sequence.
-- Use [Research Flow](/rosetta/docs/research-flow/) when the main deliverable is grounded investigation rather than implementation.
-
-## Before You Start
-
-- Prepare a concrete change request with scope and acceptance criteria.
-- Make sure `docs/CONTEXT.md` and `docs/ARCHITECTURE.md` are current enough to guide implementation.
-- Point the agent to existing requirements, API contracts, design notes, or issue links if they define non-negotiable behavior.
-- Provide workflow-specific implementation context that materially changes the result, especially business rules, edge cases, auth behavior, schema and DDL constraints, config switches, and internal library references under `refsrc/`.
-- For shared setup and general Rosetta customization, use [Usage Guide](/rosetta/docs/usage-guide/) instead of repeating that setup here.
-
-## How To Start
+Say something like:
 
 ```text
 Add password reset support for the customer portal. I want to review the plan before implementation starts.
@@ -63,13 +30,14 @@ Implement notification delivery using the existing queue abstraction. The auth r
 Change the billing retry logic to match the approved requirements in docs/REQUIREMENTS. Stop for approval before coding.
 ```
 
-## How Rosetta Shapes This Workflow
-
-Rosetta changes the user experience before any code is touched. The coding agent must load Rosetta bootstrap rules, then read project context files, then load the coding workflow. That means the session starts with context loading, classification, and planning instead of immediate edits.
+Don't use it for:
 
-Rosetta also forces explicit approvals and role separation. The workflow stays active for all request sizes, but medium and large tasks route more phases through specialized subagents for discovery, review, validation, build, and test work, so the same agent is not trusted to invent, implement, and approve in one pass. Questions are supposed to appear early when requirements, scope, or constraints are unclear.
+- Understanding existing code without changing it → use [Code Analysis](/rosetta/docs/code-analysis-flow/)
+- Writing requirements before the behavior is settled → use [Requirements Authoring](/rosetta/docs/requirements-authoring-flow/)
+- One-off odd jobs that don't need full planning → use [Ad-hoc](/rosetta/docs/adhoc-flow/)
+- Investigation rather than implementation → use [Research](/rosetta/docs/research-flow/)
 
-Rosetta provides instructions. Coding agents act on them. Rosetta itself does not see user requests, code, or project data.
+> **Quality of output depends on `docs/CONTEXT.md` and `docs/ARCHITECTURE.md`.** Rosetta reads them before planning — stale or missing context means the plan will ask more questions or miss conventions. If the change touches auth, the database schema, or external contracts, point the agent at the relevant files in your prompt.
 
 ## Workflow At A Glance
 

From 251e1817ff62b9cd4771dce6fa2ddfa85eb81de1 Mon Sep 17 00:00:00 2001
From: Yuri <yuri_makaruk@apple.com>
Date: Thu, 14 May 2026 13:25:09 +0300
Subject: [PATCH 4/6] docs: rewrite README for developer-first reading
 (CTORNDGAIN-1301)

- What is Rosetta: cut meta-prompting/four-phase jargon; replaced
  with plain definition + concrete usage example + IDE list inline.
- Why use it: 6 slogan-led bullets to 4 benefit-led bullets; demoted
  cross-project intelligence to a small italic callout.
- How it works: cut duplicate privacy paragraphs and 3 security
  control bullets (kept in SECURITY.md); added plugin/MCP delivery
  split with plugin recommended (clients prefer plugins).
- Get Started: plugin-first install (Option A) with MCP fallback
  (Option B); added model-choice warning and mandatory bootstrap rule
  step for MCP mode; merged verify and initialize.
- Cut redundant "Supported IDEs and Agents" section; "any MCP-
  compatible tool" folded into Option B.
- Documentation table: row labels cleaned up for verb consistency
  and reordered (security before changelog).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md | 96 +++++++++++++++++++++++++++++++++++--------------------
 1 file changed, 62 insertions(+), 34 deletions(-)

diff --git a/README.md b/README.md
index 9819cdf0..f17dacb4 100644
--- a/README.md
+++ b/README.md
@@ -19,43 +19,46 @@
 
 ## What is Rosetta
 
-Rosetta is a meta-prompting, context engineering, and centralized knowledge management for AI coding agents. It provides structured context - rules, skills, workflows, and sub-agents - guiding AI systems to operate with a deep understanding of system architecture, domain constraints, and engineering standards. Rosetta also accelerates project onboarding by reverse-engineering architecture and domain context, improving the reliability and consistency of AI-generated code.
+Rosetta gives your AI coding agent your team's context — architecture, conventions, business rules — automatically, in every IDE.
 
-Every AI interaction follows four phases: **Prepare** (load guardrails and context), **Research** (search the knowledge base), **Plan** (produce a reviewable plan), **Act** (execute with full context). Read more in the [Usage Guide](USAGE_GUIDE.md#workflows).
+After installing it, you type something like *"Add password reset to the customer portal"*. Instead of a generic implementation, you get a spec + plan that already understands your codebase, with explicit approval gates before any code is written.
+
+Works with Claude Code, Cursor, VS Code Copilot, JetBrains, Codex, Windsurf, OpenCode, and any MCP-compatible tool.
 
 ## Why use it
 
-- **Context engineering, not prompt hacking.** Agents receive your conventions, architecture, and business rules automatically — structured, versioned, and ready before the first line of code. See [how it fits your workflow](OVERVIEW.md#how-rosetta-fits-into-your-workflow).
-- **Write once, run everywhere.** Agent-agnostic design adapts to any IDE and any tech stack. No per-tool maintenance.
-- **Guardrails built in.** Approval gates, risk assessment, and data protection ensure consistent AI behavior across teams. See [how Rosetta protects you](USAGE_GUIDE.md#how-rosetta-protects-you).
-- **Cross-project intelligence** *(opt-in).* Publish business and technical context from every project into a shared knowledge base. Agents see the system, not just one repo — trace flows across services, catch breaking API changes before they ship, and assess blast radius of any change across the portfolio.
-- **One-command onboarding.** New repo, new developer — productive immediately with best practices baked in.
-- **Instructions as code.** Prompts version-controlled with release management — single source of truth for all teams.
+- **Plan first, code after approval.** Before any code is written, Rosetta produces a spec + plan you explicitly approve. Same goes before tests run. No autonomous runaway.
+- **One config, every IDE.** Add one MCP endpoint (or install the plugin) — same conventions and guardrails apply in Claude Code, Cursor, Copilot, JetBrains, and the rest.
+- **Conventions enforced automatically.** Your `CONTEXT.md`, `ARCHITECTURE.md`, and project rules load into every relevant request. The agent stops fabricating patterns and starts following yours.
+- **Designed not to see your code.** Rosetta serves instructions only — source code never reaches it. See [How it works](#how-it-works) below for the architectural controls.
+
+*Need cross-repo intelligence (trace flows across services, catch breaking API changes early)? See [Cross-Project Context](USAGE_GUIDE.md#cross-project-context) — opt-in via your Rosetta server.*
 
 ## How it works
 
-Your IDE connects to the Rosetta MCP server. The server exposes guardrails and common best practices, and provides a menu of available instructions — workflows and coding conventions. The coding agent selects only what it needs for the current task; Rosetta delivers just those, keeping the agent's context lean. By design, no source code or project data reaches Rosetta.
+Rosetta provides a menu of instructions — workflows, guardrails, project conventions. Your AI agent picks only what the current task needs, loads it, and runs. Rosetta never sees your source code or project data.
+
+Two delivery paths, same content:
 
-Rosetta is designed to not see your source code. It only serves knowledge and instructions to the agent. The agent loads only what it needs per request (progressive disclosure) and follows your organization's workflows.
+- **Plugin (preferred — most clients prefer this).** Bundles instructions directly into your IDE or repo. No live connection to Rosetta needed at request time. Available for Claude Code, VS Code Copilot, JetBrains, Codex.
+- **MCP server (fallback).** Your IDE connects to Rosetta over HTTP and pulls instructions on demand. Works with any MCP-compatible IDE.
 
-Rosetta is engineered to prevent the unintentional transmission of sensitive data through the following architectural controls:
-- **Deterministic Instruction Serving**: Instructions are delivered as MCP resources in a strictly deterministic manner. By eliminating the need for semantic search, coding agents are never required to transmit source code or sensitive context to Rosetta to retrieve instructions.
-- **Read-Only Default State**: "Write" mode is disabled and hidden by default. Enabling write capabilities requires an explicit, intentional configuration at deployment, ensuring that data persistence remains entirely outside of the end-user's control.
-- **Schema-Strict Input Validation**: All MCP tool inputs undergo rigorous validation against predefined schemas. This ensures the system rejects any unexpected payloads or "over-sharing" of data that does not match the required parameters.
+For architectural controls and the threat model, see [SECURITY.md](SECURITY.md).
 
 ## Get Started
 
-**Cursor** — add to `~/.cursor/mcp.json` or `.cursor/mcp.json`:
+> **Use a strong model.** Sonnet 4.6, GPT-5.3-codex-medium, gemini-3.1-pro, or better. Avoid Auto — weaker models silently skip Rosetta's tools.
 
-```json
-{
-  "mcpServers": {
-    "Rosetta": {
-      "url": "https://mcp.rosetta.griddynamics.net/mcp"
-    }
-  }
-}
-```
+### Option A — Install the plugin (recommended)
+
+| IDE                          | Command                                                                                                            |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| **Claude Code**              | `claude plugin marketplace add griddynamics/rosetta` then `claude plugin install core@rosetta`                      |
+| **VS Code / GitHub Copilot** | Install `core-copilot` via VS Code Copilot Plugins                                                                  |
+| **JetBrains / Copilot**      | Zip + manual config — see [INSTALLATION.md](INSTALLATION.md#plugin-based-installation)                              |
+| **Codex**                    | Zip + `codex features enable codex_hooks` — see [INSTALLATION.md](INSTALLATION.md#plugin-based-installation)        |
+
+### Option B — Connect via MCP (fallback for IDEs without a plugin)
 
 **Claude Code:**
 
@@ -63,37 +66,62 @@ Rosetta is engineered to prevent the unintentional transmission of sensitive dat
 claude mcp add --transport http Rosetta https://mcp.rosetta.griddynamics.net/mcp
 ```
 
+Then run `claude`, type `/mcp` → Rosetta → **Authenticate**.
+
+**Cursor / Windsurf** — `~/.cursor/mcp.json`:
+
+```json
+{ "mcpServers": { "Rosetta": { "url": "https://mcp.rosetta.griddynamics.net/mcp" } } }
+```
+
+**VS Code / Copilot** — `.vscode/mcp.json`:
+
+```json
+{ "servers": { "Rosetta": { "url": "https://mcp.rosetta.griddynamics.net/mcp" } } }
+```
+
 **Codex:**
 
 ```sh
-codex mcp add Rosetta --url https://mcp.rosetta.griddynamics.net/mcp
-codex mcp login Rosetta
+codex mcp add Rosetta --url https://mcp.rosetta.griddynamics.net/mcp && codex mcp login Rosetta
 ```
 
-Complete the OAuth flow when prompted. Then ask: *"Initialize this repository using Rosetta"*
+Other IDEs and STDIO transport: see [INSTALLATION.md](INSTALLATION.md). Any MCP-compatible tool can connect using the same endpoint.
+
+**Then add the bootstrap rule (MCP mode only).** Some IDEs don't reliably invoke MCP tools on their own. Download [bootstrap.md](https://github.com/griddynamics/rosetta/blob/main/instructions/r2/core/rules/bootstrap.md?plain=1) and place it where your IDE looks for instructions (e.g. `.claude/claude.md`, `.cursor/rules/bootstrap.mdc`, `.github/copilot-instructions.md`). Full path table in [QUICKSTART.md](QUICKSTART.md).
 
-STDIO transport is available for air-gapped environments. [All IDEs and detailed setup](INSTALLATION.md). Read more in the [Quickstart](QUICKSTART.md).
+### Verify and initialize
 
-## Supported IDEs and Agents
+In your IDE, ask:
+
+```text
+What can you do, Rosetta?
+```
+
+You should see Rosetta's workflow list. Then, once per repo:
+
+```text
+Initialize this repository using Rosetta
+```
 
-Cursor | Claude Code | VS Code / GitHub Copilot | JetBrains (Copilot, Junie) | Windsurf | Codex | Antigravity | OpenCode
+This generates your `docs/CONTEXT.md`, `docs/ARCHITECTURE.md`, and friends. Restart the chat after init so the new context loads.
 
-Works with any MCP-compatible tool.
+For details and troubleshooting, see [QUICKSTART.md](QUICKSTART.md) and [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
 
 ## Documentation
 
 | I want to... | Read |
 |---|---|
 | Understand what Rosetta is and how to think about it | [OVERVIEW.md](OVERVIEW.md) |
-| Set up Rosetta | [QUICKSTART.md](QUICKSTART.md) |
-| Learn how to use Rosetta flows | [USAGE_GUIDE.md](USAGE_GUIDE.md) |
+| See the full setup guide (all IDEs, troubleshooting) | [QUICKSTART.md](QUICKSTART.md) |
+| Learn how to use Rosetta workflows | [USAGE_GUIDE.md](USAGE_GUIDE.md) |
 | Deploy Rosetta for my organization | [DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md) |
 | Understand the system architecture | [ARCHITECTURE.md](docs/ARCHITECTURE.md) |
 | Navigate the codebase | [DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md) |
 | Contribute a change | [CONTRIBUTING.md](CONTRIBUTING.md) |
 | Debug a problem | [TROUBLESHOOTING.md](TROUBLESHOOTING.md) |
+| Read the security policy | [SECURITY.md](SECURITY.md) |
 | See release history | [CHANGELOG.md](CHANGELOG.md) |
-| Security Policy | [SECURITY.md](SECURITY.md) |
 
 ## Contributing
 

From 544da1592c1bee8a13ba93dae38fee48f36698d6 Mon Sep 17 00:00:00 2001
From: Yuri <yuri_makaruk@apple.com>
Date: Thu, 14 May 2026 17:56:09 +0300
Subject: [PATCH 5/6] docs: update contributing guidelines and developer
 documentation for clarity

---
 CONTRIBUTING.md    | 43 +++++++++++--------------------------------
 DEVELOPER_GUIDE.md | 28 +++++++++++++++++++++++++---
 OVERVIEW.md        |  2 +-
 README.md          |  2 +-
 4 files changed, 38 insertions(+), 37 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9f559618..fb20a34f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -7,9 +7,7 @@
 
 ## Before You Start
 
-- Read the [OVERVIEW](OVERVIEW.md) to understand what Rosetta is
-- Understand the [Architecture](docs/ARCHITECTURE.md)
-- Follow the [Developer Guide](DEVELOPER_GUIDE.md)
+If you haven't already, read [OVERVIEW.md](OVERVIEW.md) to understand what Rosetta is. The [Architecture](docs/ARCHITECTURE.md) is useful background but not required for most contributions. For local dev setup and where things live in the repo, the [Developer Guide](DEVELOPER_GUIDE.md) is the next stop after you've read this file.
 
 ## What Contributions Are Welcome
 
@@ -45,41 +43,22 @@ fork/clone → branch → edit → validate → push → PR
 
 See [Overall Development Flow](DEVELOPER_GUIDE.md#overall-development-flow) on how to run, test, build, review, and validate.
 
-## Prompt Changes
+## Prompt Change PRs
 
-Rosetta is a prompt engineering system. Prompt changes have outsized impact and need extra care.
+A prompt change changes how AI agents behave across every project that uses Rosetta. There's no compile error and no failing test if you break something — regressions are silent. That's why prompt PRs need evidence of behavior, not just a code-style review.
 
-**Use the prompting flow.** The [`coding-agents-prompting-flow`](USAGE_GUIDE.md#workflows) with `coding-agents-prompt-authoring` skill helps you author, design, refactor, harden, and modernize prompt families (agents, skills, workflows, workflow phases, rules). It understands Rosetta internals. Use it with Opus 4.6 model.
+The PR must include:
 
-Examples:
+1. **A prompt brief** — goal, non-goals, constraints.
+2. **Before/after behavior examples** — a prompt run on the old version, the same prompt on the new version, both outputs in the PR.
+3. **Validation evidence** — what you ran to confirm the new prompt doesn't regress what the old one did. Attach to the PR description.
 
-1. Refactoring old rosetta prompt to new:
-   ```
-   MUST FULLY EXECUTE `instructions/r2/core/workflows/coding-agents-prompting-flow.md` to refactor old Rosetta prompt `<prompt full path>` as R2 prompt family in Rosetta.
-   ```
-   
-2. Creating a new prompt:   
-   ```
-   MUST FULLY EXECUTE `instructions/r2/core/workflows/coding-agents-prompting-flow.md` to author a new R2 Rosetta <skill/agent/workflow/rule/prompt family> `<name>`: <description of what it should be>
-   ```
-   
-3. Using Rosetta MCP:
-   ```
-   MUST ACQUIRE coding-agents-prompting-flow.md FROM KB AND FULLY EXECUTE IT to author a new R2 Rosetta <skill/agent/workflow/rule/prompt family> `<name>`: <description of what it should be>
-   ```
+Two automated gates run on prompt PRs. Both must pass before merge:
 
-**What to include in the PR:**
+- **Static AI review** — checks the prompt file for structural problems (missing schema sections, broken frontmatter, missing required tags) before a human reviews it.
+- **Scenario comparison** — runs the same scenarios against the old prompt and your new prompt, then shows the behavioral diff so the reviewer can see what actually changed.
 
-1. A prompt brief: goal, non-goals, constraints
-2. Before/after behavior examples
-3. Validation evidence (attach to PR description)
-
-**Automated review pipelines will run on your PR:**
-
-- **Static AI review** validates prompt changes for structure, quality, correctness, and governance
-- **Scenario comparison** runs scenarios with old and new prompts, then validates the behavioral difference
-
-Both must pass before merge.
+For *how* to author the prompt change itself (which workflow to use, which model, concrete invocations), see [Developer Guide → step 2 of Overall Development Flow](DEVELOPER_GUIDE.md#overall-development-flow).
 
 ## AI-Assisted Contributions
 
diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md
index 0ca03b77..e7afaeb6 100644
--- a/DEVELOPER_GUIDE.md
+++ b/DEVELOPER_GUIDE.md
@@ -14,8 +14,30 @@
    - See [Contributing Workflow](CONTRIBUTING.md#contributing-workflow) for git-related info
 
 2. **Develop Rosetta using claude code / codex / cursor** or **Use the prompting flow.**
-   - Development: existing rules will kick in, we use HTTP MCP, everything is preconfigured using claude standards. The repo's `.mcp.json` pre-configures Claude Code to connect to the **dev** MCP endpoint (`rosetta-dev.example.com/mcp`) — this is intentional so contributors see their in-progress instruction changes reflected immediately. End users connect to the production endpoint instead.
-   - Prompting: use the [`coding-agents-prompting-flow` (description + examples)](CONTRIBUTING.md#prompt-changes) to author, refactor, or harden prompts.
+   - **Development:** existing rules kick in, HTTP MCP is preconfigured. The repo's `.mcp.json` pre-configures Claude Code to connect to the **dev** MCP endpoint (`rosetta-dev.example.com/mcp`) — this is intentional so contributors see their in-progress instruction changes reflected immediately. End users connect to the production endpoint instead.
+   - **Prompting:** use the [`coding-agents-prompting-flow`](USAGE_GUIDE.md#workflows) with the `coding-agents-prompt-authoring` skill to author, refactor, or harden prompts (agents, skills, workflows, rules, templates). Use Opus 4.6 or newer.
+
+     Concrete invocations:
+
+     Refactor an old prompt to R2 format:
+
+     ```text
+     MUST FULLY EXECUTE `instructions/r2/core/workflows/coding-agents-prompting-flow.md` to refactor old Rosetta prompt `<prompt full path>` as R2 prompt family in Rosetta.
+     ```
+
+     Create a new prompt:
+
+     ```text
+     MUST FULLY EXECUTE `instructions/r2/core/workflows/coding-agents-prompting-flow.md` to author a new R2 Rosetta <skill/agent/workflow/rule/prompt family> `<name>`: <description of what it should be>
+     ```
+
+     Via Rosetta MCP (instead of file path):
+
+     ```text
+     MUST ACQUIRE coding-agents-prompting-flow.md FROM KB AND FULLY EXECUTE IT to author a new R2 Rosetta <skill/agent/workflow/rule/prompt family> `<name>`: <description of what it should be>
+     ```
+
+     For PR submission requirements (brief, before/after, validation evidence), see [CONTRIBUTING → Prompt Change PRs](CONTRIBUTING.md#prompt-change-prs).
 
 3. **Check your output.**
    - [General Review Criteria](REVIEW.md#general-review-criteria)
@@ -45,7 +67,7 @@
    - All: update documentation, including web site
 
 7. **Pipelines.**
-   - [Automated pipelines](CONTRIBUTING.md#prompt-changes) will execute
+   - [Automated pipelines](CONTRIBUTING.md#prompt-change-prs) will execute
    - Static AI review and scenario comparison
    - Both must pass
 
diff --git a/OVERVIEW.md b/OVERVIEW.md
index 17264016..19172791 100644
--- a/OVERVIEW.md
+++ b/OVERVIEW.md
@@ -25,7 +25,7 @@ Design principles:
 
 **Release-based versioning.** Instructions are organized by release (r1, r2, r3). New instructions can be developed without breaking agents on stable versions. Rollback is always possible. See [Architecture — Tradeoffs](docs/ARCHITECTURE.md#tradeoffs) for rationale.
 
-**Rules-as-code.** AI behavior is authored, versioned, reviewed, and approved through standard engineering workflows. Same rigor as application code. See [Contributing — Prompt Changes](CONTRIBUTING.md#prompt-changes) for the authoring process.
+**Rules-as-code.** AI behavior is authored, versioned, reviewed, and approved through standard engineering workflows. Same rigor as application code. See [Developer Guide — Overall Development Flow](DEVELOPER_GUIDE.md#overall-development-flow) for the authoring process, and [Contributing — Prompt Change PRs](CONTRIBUTING.md#prompt-change-prs) for PR requirements.
 
 **Security by design.** No source code transfer. Air-gap capable. Runs inside the organization's perimeter. See [Context — Design Philosophy](docs/CONTEXT.md#design-philosophy) for the full set.
 
diff --git a/README.md b/README.md
index f17dacb4..1a8e29f1 100644
--- a/README.md
+++ b/README.md
@@ -125,7 +125,7 @@ For details and troubleshooting, see [QUICKSTART.md](QUICKSTART.md) and [TROUBLE
 
 ## Contributing
 
-Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for workflow and expectations.
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for workflow and expectations.
 
 ## Community
 

From 665c208a15a4d58cb32f73b960dd58483f85aff5 Mon Sep 17 00:00:00 2001
From: Yuri <yuri_makaruk@apple.com>
Date: Mon, 18 May 2026 15:51:09 +0300
Subject: [PATCH 6/6] - Consolidated key concepts into a new TERMINOLOGY.md . -
 Updated OVERVIEW.md to link to TERMINOLOGY.md - Enhanced PLUGINS.md with
 clearer installation instructions and warnings. - fix  QUICKSTART.md for
 first-time users, emphasizing project initialization and common issues. -
 Added FAQ.md to address common questions and installation issues. - Revised
 REVIEW.md to ensure consistent terminology referencing TERMINOLOGY.md. -
 Improved TROUBLESHOOTING.md with additional guidance and links to FAQ.md. -
 Clarified architecture details in ARCHITECTURE.md and updated references to
 terminology. - Adjusted bootstrap rules in instructions to reflect Git
 instead of SCM for file exclusions.

---
 .claude/settings.local.json                   |   5 +
 FAQ.md                                        | 101 +++++++
 INSTALLATION.md                               |  66 ++---
 OVERVIEW.md                                   |  24 +-
 PLUGINS.md                                    |  81 +++---
 QUICKSTART.md                                 | 247 +++++-------------
 README.md                                     |  21 +-
 REVIEW.md                                     |   2 +-
 TERMINOLOGY.md                                |  21 ++
 TROUBLESHOOTING.md                            |   3 +-
 docs/ARCHITECTURE.md                          |   8 +-
 .../r2/core/rules/bootstrap-rosetta-files.md  |   6 +-
 12 files changed, 278 insertions(+), 307 deletions(-)
 create mode 100644 .claude/settings.local.json
 create mode 100644 FAQ.md
 create mode 100644 TERMINOLOGY.md

diff --git a/.claude/settings.local.json b/.claude/settings.local.json
new file mode 100644
index 00000000..f0b1bf4b
--- /dev/null
+++ b/.claude/settings.local.json
@@ -0,0 +1,5 @@
+{
+  "disabledMcpjsonServers": [
+    "Rosetta"
+  ]
+}
diff --git a/FAQ.md b/FAQ.md
new file mode 100644
index 00000000..2a9ed808
--- /dev/null
+++ b/FAQ.md
@@ -0,0 +1,101 @@
+# FAQ
+
+**Who is this for?** Anyone evaluating, installing, or using Rosetta who has a quick question that isn't a bug or setup issue.
+**When should I read this?** Before opening an issue — most meta-questions are answered here. For setup problems see [INSTALLATION.md](INSTALLATION.md); for things that aren't working see [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
+
+---
+
+## Installation & Detection
+
+**How do I know if Rosetta is installed and configured for this repo?**
+
+Four signals, in order of reliability:
+
+1. After you send your first prompt in a new chat session, the agent's reply opens with `I have loaded context using Rosetta: ...`. This is the definitive sign — Rosetta successfully bootstrapped for the session. (Subsequent prompts in the same session reuse the loaded context and won't repeat the line.)
+2. The MCP server shows as connected in your IDE's MCP settings (Rosetta endpoint reachable). See [INSTALLATION.md](INSTALLATION.md) for setup or [TROUBLESHOOTING.md](TROUBLESHOOTING.md#connection--authentication) if it's disconnected.
+3. A bootstrap rule file exists in the repo (e.g. `CLAUDE.md`, `AGENTS.md`, `.cursor/rules/`, or your IDE's instruction file) and contains the Rosetta bootstrap block. This is the fallback when MCP isn't available.
+4. The Rosetta entry exists in your IDE's configuration. The [Uninstalling section in INSTALLATION.md](INSTALLATION.md#uninstalling) lists exactly where Rosetta lives for each IDE and mode — invert it to check for presence:
+   - **Plugin:** run `claude plugin list` (Claude Code), check installed Copilot agents (VS Code), or look for extracted plugin files in the repo (Codex)
+   - **MCP:** run `claude mcp list` / `codex mcp list`, or open your IDE's MCP config file (Cursor, VS Code, Windsurf, JetBrains, Antigravity, OpenCode) and look for a `Rosetta` entry
+   - **Offline:** confirm an `instructions/` directory exists in the repo
+
+If none of these are true, Rosetta is not active for this session. See [INSTALLATION.md](INSTALLATION.md).
+
+**How do I install Rosetta for the first time?**
+
+See the [Get Started section in README.md](README.md#get-started) 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.
+
+**How do I upgrade from R1 to R2?**
+
+Open a new chat in your IDE and type: `Initialize this repository using Rosetta (upgrade R1 to R2)`. Rosetta will detect the existing R1 layout and migrate it. <!-- TODO: confirm exact wording and link to migration notes if any -->
+
+---
+
+## Token Usage & Performance
+
+**Does an AI agent consume more tokens with Rosetta?**
+
+Yes, but with a purpose. Rosetta loads bootstrap rules, the workflow for your request type, and any skills needed for the task — typically a few thousand extra tokens up front. In return you get:
+
+- Fewer wrong-path executions that would burn far more tokens being undone
+- Less back-and-forth because the agent asks the right questions early (HITL)
+- Reusable plans, specs, and memory that compound across sessions
+
+For small/trivial tasks the overhead can feel high relative to the task. For medium/large tasks the overhead is small relative to total work and the reliability gain usually pays for itself. <!-- TODO: link to any published benchmarks if available -->
+
+**Why does the first message in a session take longer?**
+
+Rosetta runs prep steps once per session: it loads context, classifies the request, picks a workflow, and reads relevant project files (`CONTEXT.md`, `ARCHITECTURE.md`, etc.). Subsequent messages reuse this context and are fast.
+
+---
+
+## Behavior & Modes
+
+**Does Rosetta work in plan mode, Auto mode, or `danger-full-access`?**
+
+Yes. Rosetta runs in every mode. Permission modes and Auto mode only change what the agent is *allowed* to do without asking — they do not turn off Rosetta's prep steps, workflows, or HITL gates. The only way to opt out of HITL is to explicitly tell the agent `fully autonomous` or `no HITL`.
+
+**Can I skip the prep steps for a trivial one-line change?**
+
+No. Prep steps are a blocking gate and run once per session. They are lightweight (load context, classify request, pick workflow) and are designed so even trivial tasks get the right routing. The savings from skipping are tiny; the cost of skipping and getting the wrong answer is high.
+
+**How do I opt out of HITL (human-in-the-loop) for a single task?**
+
+Include the literal phrase `fully autonomous` or `no HITL` in your request. This is the only accepted opt-out; ambiguous phrasing won't disable HITL by design. Use sparingly — HITL exists to catch ambiguous intent and risky actions.
+
+**The agent stopped following Rosetta mid-session. What happened?**
+
+Most likely an expired MCP OAuth token. See [TROUBLESHOOTING.md](TROUBLESHOOTING.md#agent-not-using-rosetta) — re-authenticate through your IDE's MCP settings.
+
+---
+
+## Concepts
+
+**What's the difference between a skill, workflow, agent, and rule?**
+
+- **Rule** — always-on policy the agent must follow (e.g. guardrails, HITL questioning, file naming). Loaded at the start of every session.
+- **Skill** — a focused capability the agent invokes for a specific need (e.g. `load-context`, `questioning`, `tech-specs`). Invoked on demand.
+- **Workflow** — an end-to-end multi-phase process for a class of request (e.g. coding, modernization, research). One per top-level request.
+- **Agent / subagent** — a specialized role spawned by the orchestrator to do delegated work in isolation (e.g. reviewer, researcher, engineer).
+
+See [OVERVIEW.md](OVERVIEW.md) for the full picture.
+
+**Where do I put project-specific overrides?**
+
+In `gain.json` at the repo root. It defines SDLC setup and locations of Rosetta files and wins in any conflict with default Rosetta conventions. See [bootstrap-rosetta-files](https://github.com/griddynamics/rosetta/blob/main/instructions/r2/core/rules/bootstrap-rosetta-files.md?plain=1) for the canonical file list.
+
+**What files does Rosetta create in my repo?**
+
+The headline ones are `docs/CONTEXT.md` and `docs/ARCHITECTURE.md`. The full set (including `TODO.md`, `ASSUMPTIONS.md`, `TECHSTACK.md`, `DEPENDENCIES.md`, `CODEMAP.md`, `IMPLEMENTATION.md`, `MEMORY.md`, and the `plans/` and `refsrc/` directories) is documented in the `bootstrap-rosetta-files` rule. <!-- TODO: link to a user-friendly explainer once one exists -->
+
+---
+
+## Contributing & Support
+
+**Where do I report bugs or request features?**
+
+Open an [issue](https://github.com/griddynamics/rosetta/issues).
+
+**Where do I propose changes to Rosetta itself?**
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md).
diff --git a/INSTALLATION.md b/INSTALLATION.md
index 4704b7d6..359b9b3f 100644
--- 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: HTTP, STDIO, plugins, offline, or environment variables. For the fastest path, see [QUICKSTART.md](QUICKSTART.md).
+**When should I read this?** When you need the full picture: plugins, HTTP, STDIO, offline, or environment variables. For the fastest path, see the [Get Started section in README.md](README.md#get-started).
 
 > [!CAUTION]
 > You must receive a prior approval from your manager and company to use it.
@@ -13,18 +13,22 @@
 
 ## Choose Your Mode
 
-|                    | HTTP          | STDIO                                   | Plugin                                       | Offline                                     |
-| ------------------ | --------------------------- | --------------------------------------- | -------------------------------------------- | ------------------------------------------- |
-| Setup              | Single URL, OAuth automatic | Env vars, API key per user              | IDE-specific install or extract zip          | Download zip, copy files                    |
-| Local dependencies | None                        | Python 3.12+, uvx                       | None                                         | None                                        |
-| Auth               | OAuth via browser           | API key from Rosetta Server             | None                                         | None                                        |
-| Network            | Requires internet           | Requires internet                       | Download only                                | No network needed (with local models)       |
-| Best for           | Most users                  | Custom configs, controlled environments | Claude Code, VS Code Copilot, Codex          | Air-gapped or highly regulated environments |
+|                    | Plugin                                            | HTTP                                 | STDIO                                   | Offline                                     |
+| ------------------ | ------------------------------------------------- | ------------------------------------ | --------------------------------------- | ------------------------------------------- |
+| Setup              | IDE-specific install or extract zip               | Single URL, OAuth automatic          | Env vars, API key per user              | Download zip, copy files                    |
+| Local dependencies | None                                              | None                                 | Python 3.12+, uvx                       | None                                        |
+| Auth               | None                                              | OAuth via browser                    | API key from Rosetta Server             | None                                        |
+| Network            | Download only                                     | Requires internet                    | Requires internet                       | No network needed (with local models)       |
+| Best for           | Most users (Claude Code, VS Code Copilot, Codex)  | MCP-compatible IDEs without a plugin | Custom configs, controlled environments | Air-gapped or highly regulated environments |
 
 ## Step 1: Install
 
 Pick one mode and follow its section.
 
+### Plugin-Based Installation (recommended)
+
+See [PLUGINS.md](PLUGINS.md) to install Rosetta in your IDE (Claude Code, Cursor, VS Code Copilot, JetBrains Copilot, Codex).
+
 ### HTTP Transport
 
 One URL, no local dependencies, OAuth handles authentication automatically.
@@ -409,46 +413,6 @@ Required for STDIO transport. Optional otherwise.
 
 Do not set `VERSION`. It uses a server-controlled default for managed upgrades. See [Architecture — Tradeoffs](docs/ARCHITECTURE.md#tradeoffs) for rationale.
 
-### Plugin-Based Installation (pre-release)
-
-Rosetta publishes plugins for supported IDEs. Each plugin installs the full Rosetta instruction set locally.
-
-Read more about plugin contents and capabilities in [PLUGINS.md](PLUGINS.md).
-
-#### Claude Code
-
-```sh
-claude plugin marketplace add griddynamics/rosetta
-claude plugin install rosetta@rosetta
-```
-
-Updating after installation:
-
-```sh
-claude plugin marketplace update rosetta
-claude plugin update rosetta@rosetta
-```
-
-#### VS Code / GitHub Copilot
-
-Install `rosetta` via VS Code Copilot Plugins (not VS Code extensions).
-
-#### JetBrains / GitHub Copilot
-
-1. Download `core-copilot-*.zip` from the [latest release](https://github.com/griddynamics/rosetta/releases/latest)
-2. Create a `.github` folder in your repository and extract the archive contents into it
-3. Delete files not needed for JetBrains: `.github/.mcp.json`, `.github/hooks.json`, `.github/templates`, `.github/rules/bootstrap.md`
-4. Copy the contents of `.github/rules/plugin-files-mode.md` into `.github/copilot-instructions.md` and append before the closing `</plugin_files_mode>` tag: `Rosetta plugin root: ".github", get_context_instructions: must read fully all five "cat .github/rules/bootstrap-*.md" files all lines. You MUST FOLLOW ALL instructions and then MUST select workflow and execute it. All workflows are stored in ".github/rules/<workflowtag>.md".`
-5. Enable in JetBrains GitHub Copilot settings: Agent Mode, Custom Agent, Coding Agent, Subagent, Skills
-
-#### Codex
-
-Download `core-codex-*.zip` from the [latest release](https://github.com/griddynamics/rosetta/releases/latest), extract on top of the repository, and enable hooks:
-
-```sh
-codex features enable hooks
-```
-
 ### Offline Installation (No MCP)
 
 For environments without network access to Rosetta Server.
@@ -531,9 +495,9 @@ The agent runs an eight-phase workflow (see [Usage Guide — Init Workspace](USA
 
 ### Workspace Files Created
 
-After initialization, Rosetta maintains these files in your repository. Read more about their purpose in [Architecture — Workspace Files](docs/ARCHITECTURE.md#workspace-files).
+After initialization, Rosetta maintains the following files in your repository. Read more about their purpose in [Architecture — Workspace Files](docs/ARCHITECTURE.md#workspace-files).
 
-**Committed to SCM:**
+**Committed to Git:**
 
 - `gain.json` - SDLC setup and Rosetta file locations
 - `docs/CONTEXT.md` - business context (no technical details)
@@ -551,7 +515,7 @@ After initialization, Rosetta maintains these files in your repository. Read mor
 - `plans/<FEATURE>/<FEATURE>-SPECS.md` - tech specs
 - `refsrc/INDEX.md` - index of reference documentation (only refsrc file committed)
 
-**Excluded from SCM:**
+**Excluded from Git:**
 
 - `refsrc/*` (except INDEX.md) - reference knowledge files
 - `agents/TEMP/<FEATURE>` - temporary implementation files
diff --git a/OVERVIEW.md b/OVERVIEW.md
index 19172791..9fbf23de 100644
--- a/OVERVIEW.md
+++ b/OVERVIEW.md
@@ -33,27 +33,9 @@ Design principles:
 
 **Batteries included.** Ships proven defaults from real-world projects. Makes the right thing the easy thing.
 
-## Key Concepts
-
-These terms are defined here and referenced everywhere else.
-
-
-| Term               | Definition                                                                                                                                  |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Bootstrap**      | Critical universal policies (core, execution, hitl, guardrails) loaded at agent startup.                                                    |
-| **Classification** | Auto-detection of request type (coding, testing, research, init, etc.) that routes to a specific workflow.                                  |
-| **Workflow**       | Multi-phase pipeline coordinating subagents for a specific request type. Defines phases, steps, and approval gates. Alias **Command**       |
-| **Skill**          | Reusable unit of work loaded into agents on demand. Skills define *how* to accomplish a specific task.                                      |
-| **Rule**           | Persistent constraint applied globally or by path pattern. Defines best practices, guardrails, guidelines.                                  |
-| **Subagent**       | Delegated specialist with fresh context and its own system prompt. Alias: **Agent**. Examples: orchestrator, planner, executor, and others. |
-| **Template**       | Parameterized prompt with variables and validated placeholders.                                                                             |
-| **Release**        | Versioned instruction set (r1, r2, r3). Enables safe evolution, rollback, and A/B testing.                                                  |
-| **Guardrails**     | Safety measures: scope limits, data protection, transparency rules, approval gates, risk assessment.                                        |
-| **HITL**           | Human-in-the-loop. Approval gates at critical decision points (specs, plans, risky actions).                                                |
-| **Meta-prompting** | Rosetta MCP consults the AI agent on what should be done and how using meta-prompts.                                                        |
-| **Rosetta**        | MCP and CLI of Instruction and Knowledge Management System.                                                                                 |
-| **Prompt**         | Skill, Rule, Workflow, Command, Subagent, Agent, Template, or any generic prompt. **Rosetta prompt** prompt for Rosetta.                    |
-| **Shells**         | Small prompt proxies with proper fronmatters created during onboarding so that coding agents are aware of skill, agents, commands.          |
+## Terminology
+
+See [TERMINOLOGY.md](TERMINOLOGY.md) for definitions of bootstrap, classification, workflow, skill, rule, subagent, template, release, guardrails, HITL, meta-prompting, prompt, and shells.
 
 
 ## How Rosetta Fits into Your Workflow
diff --git a/PLUGINS.md b/PLUGINS.md
index 630f3167..47fc5ccd 100644
--- a/PLUGINS.md
+++ b/PLUGINS.md
@@ -1,43 +1,56 @@
+# Plugins
+
+Rosetta plugins bundle the bootstrap rule, skills, agents, workflows, and other instructions directly into your IDE. The agent loads them locally — no live connection to Rosetta is needed at request time.
+
+Two install modes per IDE:
+
+- **Marketplace** — managed install from a plugin marketplace. Easier; preferred when available.
+- **Standalone** — manual zip extraction into your repo. For IDEs without a marketplace path, or environments that block external marketplaces.
+
 > [!CAUTION]
-> You must receive a prior approval from your manager and company to use it.
+> You must receive prior approval from your manager and company to use Rosetta.
 
 > [!WARNING]
-> Use **Sonnet 4.6**, **GPT-5.3-codex-medium**, **gemini-3.1-pro** or better models. Avoid Auto model selection.
+> Use **Sonnet 4.6**, **GPT-5.3-codex-medium**, **gemini-3.1-pro**, or better. Avoid Auto.
 
->[!NOTE]
-> This is pre-release, but it already works.
+> [!NOTE]
+> Plugins are pre-release. They install and run; report bugs at <https://github.com/griddynamics/rosetta/issues>.
 
-## Claude Code Full Plugin Installation
+## Claude Code
 
 ```sh
-
 claude plugin marketplace add griddynamics/rosetta
 claude plugin install rosetta@rosetta
-
 ```
 
-## Cursor Standalone
+To update later:
 
-1. Download `core-cursor-standalone-*.zip` from the [latest release](https://github.com/griddynamics/rosetta/releases/latest)
-2. Extract the archive contents directly into the repository.
-3. Verify you can see a file `.cursor/agents/architect.md`. Ensure there are no `.cursor/.cursor` folders.
+```sh
+claude plugin marketplace update rosetta
+claude plugin update rosetta@rosetta
+```
 
-## Cursor Team Marketplace
+## Cursor
 
-If you have respective edition of Cursor you can add it as plugin to your corporate marketplace. See https://cursor.com/docs/plugins#team-marketplaces
+### Marketplace (recommended)
 
-You can also install plugin to claude code and it will appear in Cursor :)
+If you have a Cursor edition that supports plugins, add `https://github.com/griddynamics/rosetta` to your team marketplace. See <https://cursor.com/docs/plugins#team-marketplaces> for the setup steps on the Cursor side.
 
-`https://github.com/griddynamics/rosetta` provides marketplace and plugin for Cursor.
+Cursor also sees plugins installed via Claude Code. If you've already installed via `claude plugin install`, do **not** install again in Cursor — the same content would be duplicated in Cursor's context.
 
-> [!WARNING]
-> Cursor sees and uses all claude code plugins, so you should not install plugins to claude code and cursor, just install to claude code. Otherwise everything will be duplicated in Cursor context!
+### Standalone
+
+1. Download `core-cursor-standalone-*.zip` from the [latest release](https://github.com/griddynamics/rosetta/releases/latest).
+2. Extract the archive contents into your repository.
+3. Verify `.cursor/agents/architect.md` exists. Ensure there is no nested `.cursor/.cursor/` folder.
 
-## VS Code Github Copilot
+## VS Code (GitHub Copilot)
 
-Add marketplace to `chat.plugins.marketplaces` in settings using using local files path: `https://github.com/griddynamics/rosetta`.
+### Marketplace (recommended)
 
-Go to agent customizations screen (settings gear icon in Copilot chat plane), click `Browse Marketplaces`, click `install` for `rosetta`.
+1. In VS Code settings, add `https://github.com/griddynamics/rosetta` to `chat.plugins.marketplaces`.
+2. Open the Copilot chat panel, click the settings gear icon to open agent customizations.
+3. Click **Browse Marketplaces**, then **install** for `rosetta`.
 
 <img src="docs/images/vscode-add-marketplaces.png" alt="Add marketplaces to VS Code" width="710"/>
 
@@ -45,18 +58,26 @@ Go to agent customizations screen (settings gear icon in Copilot chat plane), cl
 
 <img src="docs/images/vscode-install-plugins.png" alt="Install plugins" width="710"/>
 
-## Github Copilot Standalone (JetBrains and VS Code)
+### Standalone
 
-1. Download `core-copilot-standalone-*.zip` from the [latest release](https://github.com/griddynamics/rosetta/releases/latest)
-2. Extract the archive contents directly into the repository, if `.github/copilot-instructions.md` you will have to merge contents: first from Rosetta, then the original content.
-3. Verify you can see a file `.github/agents/architect.agent.md`. Ensure there are no `.github/.github` folders.
+See [GitHub Copilot Standalone](#github-copilot-standalone-jetbrains-and-vs-code) below — same procedure for VS Code and JetBrains.
 
-## Codex plugins (standalone only)
+## GitHub Copilot Standalone (JetBrains and VS Code)
 
-Codex plugins only allow to pass hooks, MCPs and skills as of now (Apr 2026).
+Use this when the marketplace path isn't available — JetBrains Copilot (no marketplace), or VS Code environments that block external marketplaces.
 
-Download `core-codex-*.zip` from the [latest release](https://github.com/griddynamics/rosetta/releases/latest), extract on top of the repository, and enable hooks:
+1. Download `core-copilot-standalone-*.zip` from the [latest release](https://github.com/griddynamics/rosetta/releases/latest).
+2. Extract the archive contents into your repository. If `.github/copilot-instructions.md` already exists, merge contents — Rosetta first, then the original content.
+3. Verify `.github/agents/architect.agent.md` exists. Ensure there is no nested `.github/.github/` folder.
 
-```sh
-codex features enable hooks
-```
+## Codex
+
+Codex plugins currently support hooks, MCPs, and skills only (as of April 2026).
+
+1. Download `core-codex-*.zip` from the [latest release](https://github.com/griddynamics/rosetta/releases/latest).
+2. Extract the archive contents into your repository.
+3. Enable hooks:
+
+   ```sh
+   codex features enable hooks
+   ```
diff --git a/QUICKSTART.md b/QUICKSTART.md
index caf12517..a5b2d832 100644
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@@ -1,233 +1,104 @@
-# Quick Start
+# Quick Start — your first session with Rosetta
 
-**Who is this for?** New users setting up Rosetta for the first time.
-**When should I read this?** When you want to go from zero to a working setup.
+**Who is this for?** You've just installed Rosetta and want to do your first real task.
+**When should I read this?** Right after install. For install steps, see [README](README.md) (Get Started section) or [PLUGINS.md](PLUGINS.md). For troubleshooting setup itself, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
 
 ---
 
-## Step 1: Connect Rosetta MCP
+## 1. Open the right folder
 
-> [!CAUTION]
-> You must receive a prior approval from your manager and company to use it.
+Open the **actual project repo** in your IDE — not the parent folder that contains it. Rosetta initializes whatever folder Claude is running in, so opening a parent directory scatters Rosetta files into the wrong place.
 
-> [!WARNING]
-> Use **Sonnet 4.6**, **GPT-5.3-codex-medium**, **gemini-3.1-pro** or better models. Avoid Auto model selection.
+Quick check: in the IDE's terminal, run `pwd`. The output should be your project root (where your `package.json`, `pom.xml`, `pyproject.toml`, etc. lives), not its parent.
 
-> [!NOTE]
-> Rosetta is designed to never use or see data or IP.
-> Instead it uses inversion of control, by providing a "menu" to AI coding agents.
-
-Rosetta uses HTTP MCP transport with OAuth. Pick your IDE and add the configuration.
-
-<details>
-<summary><b>Cursor</b></summary>
-
-Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
-
-```json
-{
-  "mcpServers": {
-    "Rosetta": {
-      "url": "https://mcp.rosetta.griddynamics.net/mcp"
-    }
-  }
-}
-```
-
-</details>
-
-<details>
-<summary><b>Claude Code</b></summary>
+## 2. Start Claude and verify Rosetta loaded
 
 ```sh
-claude mcp add --transport http Rosetta https://mcp.rosetta.griddynamics.net/mcp
+claude
 ```
 
-Authenticate inside a claude session with `/mcp`, select Rosetta, Authenticate, and complete the OAuth flow.
-
-</details>
-
-<details>
-<summary><b>Codex</b></summary>
+Inside the session, type:
 
-```sh
-codex mcp add Rosetta --url https://mcp.rosetta.griddynamics.net/mcp
-codex mcp login Rosetta
 ```
-
-</details>
-
-<details>
-<summary><b>VS Code / GitHub Copilot</b></summary>
-
-Add to `.vscode/mcp.json` or `~/.mcp.json`:
-
-```json
-{
-  "servers": {
-    "Rosetta": {
-      "url": "https://mcp.rosetta.griddynamics.net/mcp"
-    }
-  }
-}
-```
-
-</details>
-
-<details>
-<summary><b>GitHub Copilot (JetBrains)</b></summary>
-
-`Settings` > `Tools` > `GitHub Copilot` > `MCP Settings`. Add to `~/.config/github-copilot/intellij/mcp.json`:
-
-```json
-{
-  "servers": {
-    "Rosetta": {
-      "url": "https://mcp.rosetta.griddynamics.net/mcp"
-    }
-  }
-}
+What can you do, Rosetta?
 ```
 
-Restart IDE after changes.
-
-</details>
+You should see a list of workflows (`coding-flow`, `init-workspace-flow`, `code-analysis-flow`, etc.) and high-value skills:
 
-<details>
-<summary><b>JetBrains Junie</b></summary>
+<img src="docs/images/Rosetta-ProperResponse1.png" alt="Rosetta proper response" width="355"/> <img src="docs/images/Rosetta-ProperResponse2.png" alt="Rosetta proper response" width="300"/>
 
-`Settings` > `Tools` > `Junie` > `MCP Settings` > `+ Add` > `As JSON`:
+If the response is generic Claude output with no Rosetta-specific mentions, the plugin or MCP didn't load — see [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
 
-```json
-{
-  "mcpServers": {
-    "Rosetta": {
-      "url": "https://mcp.rosetta.griddynamics.net/mcp"
-    }
-  }
-}
-```
+The first time a Rosetta skill is invoked, Claude asks for permission. Pick option **2** ("Yes, and don't ask again…") so future calls don't keep interrupting.
 
-</details>
+> **Model matters.** Use Sonnet 4.6, GPT-5.3-codex-medium, gemini-3.1-pro, or better. Avoid Auto — weaker models silently skip Rosetta's tools. Use `/model` to check or change in Claude Code.
 
-<details>
-<summary><b>Windsurf</b></summary>
+## 3. Initialize the repository
 
-Add to your Windsurf MCP config:
+Once per repo:
 
-```json
-{
-  "mcpServers": {
-    "Rosetta": {
-      "url": "https://mcp.rosetta.griddynamics.net/mcp"
-    }
-  }
-}
 ```
-
-</details>
-
-<details>
-<summary><b>Antigravity</b></summary>
-
-Add to your Antigravity MCP config:
-
-```json
-{
-  "mcpServers": {
-    "Rosetta": {
-      "serverUrl": "https://mcp.rosetta.griddynamics.net/mcp"
-    }
-  }
-}
+Initialize this repository using Rosetta
 ```
 
-</details>
+Rosetta scans your tech stack and generates a baseline set of workspace docs (`docs/CONTEXT.md`, `docs/ARCHITECTURE.md`, `docs/TECHSTACK.md`, `docs/CODEMAP.md`, `docs/DEPENDENCIES.md`, plus state files under `agents/`). It will ask you a series of decisions before writing anything.
 
-<details>
-<summary><b>OpenCode</b></summary>
+**The init decision prompts:**
 
-Add to `opencode.json`:
+- **Doc depth** — the most consequential.
+  - **Lightweight** — concise core docs. Right for small or single-service apps and most pet projects.
+  - **Full** — adds patterns extraction, deeper diagrams, NFRs. Pick this for large codebases you'll evolve over months.
+  - **Minimal** — only `CONTEXT.md`, `ARCHITECTURE.md`, `IMPLEMENTATION.md`. Don't pick to save time — future workflows need `TECHSTACK.md` and `DEPENDENCIES.md` and will re-ask the same questions every task without them.
+- **Patterns**, **Status**, **Target state** — the "Recommended" option is usually correct. Override only with specific reason.
 
-```json
-{
-  "mcp": {
-    "Rosetta": {
-      "type": "http",
-      "url": "https://mcp.rosetta.griddynamics.net/mcp",
-      "enabled": true
-    }
-  }
-}
-```
+After decisions, Rosetta asks **clarifying questions about your project** (purpose, users, architecture choices, conventions). Answer them carefully — these populate `CONTEXT.md` and `ARCHITECTURE.md`, which every future workflow reads on every task. Vague answers here mean Rosetta asks them again on every coding task.
 
-</details>
-
-Any MCP client that supports HTTP transport can connect using the endpoint URL. Complete the OAuth flow when prompted.
-
-STDIO transport is available for air-gapped environments. See [INSTALLATION.md](INSTALLATION.md).
-
-## Step 2: Verify
+> **Composite workspaces:** init each repository separately, then init at the workspace level with "This is composite workspace" appended.
+> **Dead code or existing specs:** mention their location in the prompt to save Rosetta time.
 
-Ask the agent:
+When init finishes, **exit and restart Claude** — context files only load at session start:
 
+```sh
+/exit
+claude
 ```
-What can you do, Rosetta?
-```
-
-It should use Rosetta MCP to retrieve agents, guardrails, and instructions:
 
-<img src="docs/images/Rosetta-ProperResponse1.png" alt="Rosetta proper response" width="355"/> <img src="docs/images/Rosetta-ProperResponse2.png" alt="Rosetta proper response" width="300"/>
-
-## Step 3: Initialize (once per repository)
+## 4. Run your first task
 
-Ask the agent:
+In the new session, describe what you want in plain language:
 
 ```
-Initialize this repository using Rosetta
+Add password reset functionality. I want to review the plan before any code is written.
 ```
 
-The agent will analyze your tech stack, generate documentation (TECHSTACK.md, CODEMAP.md, DEPENDENCIES.md, ARCHITECTURE.md, CONTEXT.md), and ask clarifying questions. Read more about [workspace files](INSTALLATION.md#workspace-files-created) and [all workflows](USAGE_GUIDE.md#workflows).
-
-> [!NOTE]
-> **Prefer medium models:** High reasoning and Opus models consume too much token on reasoning.
-> **Composite workspaces:** init each repository separately, then init at the workspace level with "This is composite workspace" appended.
-> **Dead code or existing specs:** mention their location in the prompt to save time.
-
-## Common Issues
-
-- **OAuth prompt does not appear:** restart your IDE and retry the connection. Read more in [Troubleshooting — Connection & Authentication](TROUBLESHOOTING.md#connection--authentication).
-- **Agent ignores Rosetta tools:** confirm the MCP server shows as connected in your IDE's MCP settings. Add a [bootstrap rule](INSTALLATION.md) if the agent still skips Rosetta. Read more in [Troubleshooting — Agent Not Using Rosetta](TROUBLESHOOTING.md#agent-not-using-rosetta).
-- **Slow or empty responses:** check your network can reach your Rosetta MCP host. See [TROUBLESHOOTING.md](TROUBLESHOOTING.md#slow-or-empty-responses).
-
-## Step 4: Add Bootstrap Rule (optional)
+Rosetta routes to the coding workflow. You'll see:
 
-If something does not work.
+1. **Discovery** — a `discoverer` subagent reads `CONTEXT.md` / `ARCHITECTURE.md`, scans the relevant files, gathers constraints.
+2. **Tech plan** — an `architect` writes `<FEATURE>-SPECS.md` (the what) and `<FEATURE>-PLAN.md` (the how) under `plans/<FEATURE>/`.
+3. **Review plan** — a `reviewer` subagent inspects the spec + plan against your request.
+4. **Your approval gate** — Rosetta stops and waits. Reply with `Yes, I reviewed the plan` to proceed, or push back if something's wrong.
+5. **Implementation** — the `engineer` subagent writes only the approved scope. Build must pass; tests come later.
+6. **Code review + validation** — `reviewer` + `validator` inspect the diff.
+7. **Your second approval gate** — `Yes, I approve the implementation` to continue.
+8. **Tests** — the engineer writes and runs tests, reviewer checks coverage.
 
-Download [bootstrap.md](https://github.com/griddynamics/rosetta/blob/main/instructions/r2/core/rules/bootstrap.md?plain=1) and add it to your IDE's instruction file (keep entire contents, including YAML frontmatter):
+Two explicit gates. You can always reject and iterate. Small tasks may collapse the phases and combine the gates — approval is still always explicit. See [USAGE_GUIDE.md](USAGE_GUIDE.md#workflows) for the full phase breakdown of every workflow.
 
-| IDE                        | Destination                       |
-| -------------------------- | --------------------------------- |
-| Cursor                     | `.cursor/rules/bootstrap.mdc`     |
-| Claude Code                | `.claude/claude.md`               |
-| VS Code / GitHub Copilot   | `.github/copilot-instructions.md` |
-| GitHub Copilot (JetBrains) | `.github/copilot-instructions.md` |
-| JetBrains Junie            | `.junie/guidelines.md`            |
-| Windsurf                   | `.windsurf/rules/bootstrap.md`    |
-| Antigravity                | `.agent/rules/bootstrap.md`       |
-| OpenCode/Cursor            | `AGENTS.md`                       |
+## 5. Common first-hour gotchas
 
-## Next Steps
+- **"Agent ignores Rosetta tools."** Check `/mcp` status (MCP mode) or `claude plugin list` (plugin mode). If MCP shows disconnected, re-authenticate. If the plugin is missing, reinstall via [PLUGINS.md](PLUGINS.md).
+- **Generic output, no workflow phases visible.** Wrong model — switch off Auto and use Sonnet 4.6 / Opus / GPT-5.3-codex-medium.
+- **Init ran but the docs landed in the wrong folder.** You initialized from a parent directory (see Step 1). `cd` into the correct repo, delete the misplaced `docs/`, and re-run init.
+- **Rosetta keeps asking the same questions on every task.** Your `CONTEXT.md` and `ARCHITECTURE.md` are too thin. Fill them in — recurring questions are gaps in those files.
+- **You skipped the restart after init.** New `CONTEXT.md` / `ARCHITECTURE.md` won't load mid-session. Always `/exit` + `claude` after init.
 
-- [Usage Guide](USAGE_GUIDE.md) — how to use Rosetta flows
-- [Overview](OVERVIEW.md) — mental model and terminology
-- [Deployment Guide](DEPLOYMENT_GUIDE.md) — org-wide deployment
-- [Contributing](CONTRIBUTING.md) — make your first contribution
-- [Architecture](docs/ARCHITECTURE.md) — system internals
+Full diagnostics: [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
 
-## Video Tutorials
+## Where to next
 
-- [Install Using MCP](https://vimeo.com/1174124251/f38e017d8d?fl=ml&fe=ec) — step-by-step setup
-- [Install without MCP](https://vimeo.com/1174124213/c50179147c?fl=ml&fe=ec) — air-gapped environments
-- [Initialize with Antigravity](https://vimeo.com/1174124165/8f5fbd7775?fl=ml&fe=ec) — project initialization
-- [Subagents and Workflows in Claude Code](https://vimeo.com/1174124272/96056d5cc5?fl=ml&fe=ec) — advanced configuration
+- [USAGE_GUIDE.md](USAGE_GUIDE.md) — every workflow and skill in detail
+- [OVERVIEW.md](OVERVIEW.md) — mental model and terminology
+- [PLUGINS.md](PLUGINS.md) — per-IDE plugin install
+- [INSTALLATION.md](INSTALLATION.md) — MCP / STDIO / offline, env vars
+- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) — symptom-first diagnosis
+- [CONTRIBUTING.md](CONTRIBUTING.md) — making your first Rosetta contribution
diff --git a/README.md b/README.md
index 1a8e29f1..c54b2204 100644
--- a/README.md
+++ b/README.md
@@ -19,9 +19,15 @@
 
 ## What is Rosetta
 
+Rosetta is an open-source instruction-management system for AI coding agents. It plugs into your IDE and delivers the workflows, guardrails, and project conventions your agent needs on each request.
+
 Rosetta gives your AI coding agent your team's context — architecture, conventions, business rules — automatically, in every IDE.
 
-After installing it, you type something like *"Add password reset to the customer portal"*. Instead of a generic implementation, you get a spec + plan that already understands your codebase, with explicit approval gates before any code is written.
+After installing it, you type something like *"Add password reset to the customer portal"*. Instead of a generic implementation, the agent:
+
+1. Drafts a **spec** at `plans/password-reset/password-reset-SPECS.md` — components touched, contracts, acceptance criteria — informed by your existing `CONTEXT.md`, `ARCHITECTURE.md`, and conventions
+2. Drafts a **plan** at `plans/password-reset/password-reset-PLAN.md` — phased tasks, subagent delegation, HITL checkpoints
+3. Stops at each **approval gate** and waits for explicit confirmation, e.g. `"Yes, I reviewed the plan"` before implementation, `"Yes, I approve the implementation"` before finalizing
 
 Works with Claude Code, Cursor, VS Code Copilot, JetBrains, Codex, Windsurf, OpenCode, and any MCP-compatible tool.
 
@@ -51,12 +57,9 @@ For architectural controls and the threat model, see [SECURITY.md](SECURITY.md).
 
 ### Option A — Install the plugin (recommended)
 
-| IDE                          | Command                                                                                                            |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| **Claude Code**              | `claude plugin marketplace add griddynamics/rosetta` then `claude plugin install core@rosetta`                      |
-| **VS Code / GitHub Copilot** | Install `core-copilot` via VS Code Copilot Plugins                                                                  |
-| **JetBrains / Copilot**      | Zip + manual config — see [INSTALLATION.md](INSTALLATION.md#plugin-based-installation)                              |
-| **Codex**                    | Zip + `codex features enable codex_hooks` — see [INSTALLATION.md](INSTALLATION.md#plugin-based-installation)        |
+A plugin bundles Rosetta's bootstrap rule, skills, agents, and workflows directly into your IDE. No MCP wiring, no manual bootstrap file.
+
+See [PLUGINS.md](PLUGINS.md) to install Rosetta in your IDE (Claude Code, Cursor, VS Code Copilot, JetBrains Copilot, Codex).
 
 ### Option B — Connect via MCP (fallback for IDEs without a plugin)
 
@@ -104,7 +107,7 @@ You should see Rosetta's workflow list. Then, once per repo:
 Initialize this repository using Rosetta
 ```
 
-This generates your `docs/CONTEXT.md`, `docs/ARCHITECTURE.md`, and friends. Restart the chat after init so the new context loads.
+This generates your `docs/CONTEXT.md`, `docs/ARCHITECTURE.md`, and associated files. Restart the chat after init so the new context loads.
 
 For details and troubleshooting, see [QUICKSTART.md](QUICKSTART.md) and [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
 
@@ -113,12 +116,14 @@ For details and troubleshooting, see [QUICKSTART.md](QUICKSTART.md) and [TROUBLE
 | I want to... | Read |
 |---|---|
 | Understand what Rosetta is and how to think about it | [OVERVIEW.md](OVERVIEW.md) |
+| Look up a Rosetta-specific term | [TERMINOLOGY.md](TERMINOLOGY.md) |
 | See the full setup guide (all IDEs, troubleshooting) | [QUICKSTART.md](QUICKSTART.md) |
 | Learn how to use Rosetta workflows | [USAGE_GUIDE.md](USAGE_GUIDE.md) |
 | Deploy Rosetta for my organization | [DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md) |
 | Understand the system architecture | [ARCHITECTURE.md](docs/ARCHITECTURE.md) |
 | Navigate the codebase | [DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md) |
 | Contribute a change | [CONTRIBUTING.md](CONTRIBUTING.md) |
+| Get answers to common questions | [FAQ.md](FAQ.md) |
 | Debug a problem | [TROUBLESHOOTING.md](TROUBLESHOOTING.md) |
 | Read the security policy | [SECURITY.md](SECURITY.md) |
 | See release history | [CHANGELOG.md](CHANGELOG.md) |
diff --git a/REVIEW.md b/REVIEW.md
index e2b03a8f..5740a945 100644
--- a/REVIEW.md
+++ b/REVIEW.md
@@ -73,7 +73,7 @@ Instructions (skills, agents, workflows, rules, templates) define how AI agents
 - **Precise wording.** No vague qualifiers ("approximately", "generally", "might"). Measurable and specific.
 - **Explicit over implicit.** State requirements directly. Do not assume the agent will infer intent.
 - **Imperative form.** "Do X", not "You should consider doing X". Target each rule line below 8 words.
-- **Use common and domain terms.** Avoid jargon unless defined in [OVERVIEW.md — Key Concepts](OVERVIEW.md#key-concepts). Consistent terminology across all instructions.
+- **Use common and domain terms.** Avoid jargon unless defined in [TERMINOLOGY.md](TERMINOLOGY.md). Consistent terminology across all instructions.
 - **No AI slop.** No filler, no em-dashes, no marketing language. If it sounds like a LinkedIn post, rewrite.
 - **No non-operational content.** Remove history, rationale annotations, origin labels, change notes. Instructions describe current state.
 - **Structured over prose.** Prefer lists, tables, and short sections over paragraphs.
diff --git a/TERMINOLOGY.md b/TERMINOLOGY.md
new file mode 100644
index 00000000..32f1e625
--- /dev/null
+++ b/TERMINOLOGY.md
@@ -0,0 +1,21 @@
+# Terminology
+
+**Who is this for?** Anyone reading or contributing to Rosetta docs who needs the definition of a Rosetta-specific term.
+**When should I read this?** As a lookup — these terms appear throughout the rest of the docs.
+
+| Term               | Definition                                                                                                                                  |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Bootstrap**      | Critical universal policies (core, execution, hitl, guardrails) loaded at agent startup.                                                    |
+| **Classification** | Auto-detection of request type (coding, testing, research, init, etc.) that routes to a specific workflow.                                  |
+| **Workflow**       | Multi-phase pipeline coordinating subagents for a specific request type. Defines phases, steps, and approval gates. Alias **Command**       |
+| **Skill**          | Reusable unit of work loaded into agents on demand. Skills define *how* to accomplish a specific task.                                      |
+| **Rule**           | Persistent constraint applied globally or by path pattern. Defines best practices, guardrails, guidelines.                                  |
+| **Subagent**       | Delegated specialist with fresh context and its own system prompt. Alias: **Agent**. Examples: orchestrator, planner, executor, and others. |
+| **Template**       | Parameterized prompt with variables and validated placeholders.                                                                             |
+| **Release**        | Versioned instruction set (r1, r2, r3). Enables safe evolution, rollback, and A/B testing.                                                  |
+| **Guardrails**     | Safety measures: scope limits, data protection, transparency rules, approval gates, risk assessment.                                        |
+| **HITL**           | Human-in-the-loop. Approval gates at critical decision points (specs, plans, risky actions).                                                |
+| **Meta-prompting** | Rosetta MCP consults the AI agent on what should be done and how using meta-prompts.                                                        |
+| **Rosetta**        | MCP and CLI of Instruction and Knowledge Management System.                                                                                 |
+| **Prompt**         | Skill, Rule, Workflow, Command, Subagent, Agent, Template, or any generic prompt. **Rosetta prompt** prompt for Rosetta.                    |
+| **Shells**         | Small prompt proxies with proper fronmatters created during onboarding so that coding agents are aware of skill, agents, commands.          |
diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md
index 2c6e5da0..50cc4bc0 100644
--- a/TROUBLESHOOTING.md
+++ b/TROUBLESHOOTING.md
@@ -1,7 +1,7 @@
 # Troubleshooting
 
 **Who is this for?** Anyone blocked while using or developing Rosetta.
-**When should I read this?** When something isn't working and you need a quick fix.
+**When should I read this?** When something isn't working and you need a quick fix. For meta-questions ("how does X work", "does Rosetta do Y"), see [FAQ.md](FAQ.md) first.
 
 ---
 
@@ -96,6 +96,7 @@ Common causes: unsupported file format, oversized documents, malformed markdown.
 
 ## Still Stuck?
 
+- [FAQ.md](FAQ.md) — common questions about behavior, token usage, and concepts
 - [Discord](https://discord.gg/QzZ2cWg36g)
 - [Open an issue](https://github.com/griddynamics/rosetta/issues)
 - [rosetta-support@griddynamics.com](mailto:rosetta-support@griddynamics.com)
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index fdd51c8b..8008587a 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -4,7 +4,7 @@
 
 **When should I read this?** After [OVERVIEW.md](../OVERVIEW.md). Before touching MCP tools, CLI publishing, instruction content, or folder structure.
 
-For terminology (workflow, skill, rule, subagent, bootstrap, etc.), see [OVERVIEW.md — Key Concepts](../OVERVIEW.md#key-concepts).
+For terminology (workflow, skill, rule, subagent, bootstrap, etc.), see [TERMINOLOGY.md](../TERMINOLOGY.md).
 
 ---
 
@@ -407,7 +407,7 @@ Instructions live in `/instructions/r2/` in the instructions repository, using a
 
 **Layered customization.** Core provides the universal foundation. Organization folders extend or override it. Files at the same VFS resource path get **bundled together** by the Bundler. `INSTRUCTION_ROOT_FILTER` controls which layers are included (e.g., `CORE,GRID`).
 
-**Component relationships.** Workflows invoke subagents. Subagents use skills. All reference rules. Templates live inside skills. Guardrails are rules. See [Overview — Key Concepts](../OVERVIEW.md#key-concepts) for definitions.
+**Component relationships.** Workflows invoke subagents. Subagents use skills. All reference rules. Templates live inside skills. Guardrails are rules. See [TERMINOLOGY.md](../TERMINOLOGY.md) for definitions.
 
 **Naming.** Lowercase, dash-separated, globally unique filenames. Entry points: `SKILL.md` for skills, `<name>.md` for agents, workflows, and rules.
 
@@ -439,8 +439,8 @@ Rosetta initializes and maintains a standard file structure in **target reposito
 
 **Other:**
 - `gain.json` — general SDLC setup and Rosetta file locations (wins in conflicts)
-- `refsrc/*` — reference source code for knowledge only (excluded from SCM except `refsrc/INDEX.md`)
-- `agents/TEMP/<FEATURE>` — temporary files during implementation (excluded from SCM)
+- `refsrc/*` — reference source code for knowledge only (excluded from Git except `refsrc/INDEX.md`)
+- `agents/TEMP/<FEATURE>` — temporary files during implementation (excluded from Git)
 
 Prep step 2 loads `CONTEXT.md` and `ARCHITECTURE.md` from the target repository. The agent updates `IMPLEMENTATION.md` and `MEMORY.md` as it works. See [Installation — Workspace Files Created](../INSTALLATION.md#workspace-files-created) for the full list of committed and excluded files.
 
diff --git a/instructions/r2/core/rules/bootstrap-rosetta-files.md b/instructions/r2/core/rules/bootstrap-rosetta-files.md
index d7ce5af8..896ad105 100644
--- a/instructions/r2/core/rules/bootstrap-rosetta-files.md
+++ b/instructions/r2/core/rules/bootstrap-rosetta-files.md
@@ -10,7 +10,7 @@ baseSchema: docs/schemas/rule.md
 
 <bootstrap_rosetta_files compact="NEVER" optimize="NEVER" summarize="AS-IS">
 
-All rosetta files below: SRP, DRY, MECE, very concise. Each file starts with a self-describing sentence of its purpose. Grep-friendly topical headers. Headers include status. No explicit ToC. All committed to SCM unless stated otherwise.
+All rosetta files below: SRP, DRY, MECE, very concise. Each file starts with a self-describing sentence of its purpose. Grep-friendly topical headers. Headers include status. No explicit ToC. All committed to Git unless stated otherwise.
 It must be possible to grep by headers and receive useful information and ToC.
 
 1. `gain.json` defines and overrides general SDLC setup and locations of Rosetta files; this file wins in conflicts.
@@ -29,8 +29,8 @@ It must be possible to grep by headers and receive useful information and ToC.
 14. `plans/<FEATURE>/<FEATURE>-SPECS.md`. Tech specs.
 15. `plans/<FEATURE>/plan.json`. Plan manager execution tracking file.
 16. `plans/<FEATURE>/*`. Feature implementation supporting files.
-16. `refsrc/*`. Source code used only for knowledge! Exclude from SCM with single exception `refsrc/INDEX.md` to be committed.
-17. `agents/TEMP/<FEATURE>`. Temporary folder used during feature implementation. Exclude `agents/TEMP` from SCM.
+16. `refsrc/*`. Source code used only for knowledge! Exclude from Git with single exception `refsrc/INDEX.md` to be committed.
+17. `agents/TEMP/<FEATURE>`. Temporary folder used during feature implementation. Exclude `agents/TEMP` from Git.
 18. `docs/raw`. Folder with raw input files for requirements.
 
 </bootstrap_rosetta_files>