docs(README): sharpen positioning, add architecture diagram, concrete quickstart

[esteinberg]

What

A focused editorial pass on README.md to improve time-to-understanding for first-time GitHub visitors. No code or behavior changes — content only.

Positioning & vocabulary

• Anchored on a consistent category: context engineering + governed instructions (hero + intro), retiring the ambiguous compiled / "governance and context layer" phrasings.
• Standardized "instructions" as the umbrella term; kept "meta-prompting" out of the user-facing hero (reserved for About/metadata).

New fast-comprehension pieces

• Without Rosetta / With Rosetta table near the top.
• Concrete "Add rate limiting to the checkout API" side-by-side example.
• How it works Mermaid diagram — horizontal, color-coded by ownership (🟦 shipped with Rosetta · 🟩 your org & project · ⬜ third-party tools), showing inputs → Rosetta Runtime → Agent Adapters → Guided Execution → agents.
• "Why not just use IDE rules?" objection handler.

Quick Start made real

• Install options table: Plugins (recommended) / Hosted MCP (evaluation) / Self-hosted MCP (enterprise & air-gapped).
• The actual conversational init prompt and the workspace files it generates (TECHSTACK.md, CODEMAP.md, DEPENDENCIES.md, ARCHITECTURE.md, CONTEXT.md).
• Removed fabricated pip install rosetta-cli / rosetta init guidance (verified rosetta-cli is a RAGFlow publishing/admin tool, not the entry point).
• Elevated llms-full.txt as a machine-readable entry point.

Structure & tone

• Reordered: Quick Start now precedes How it works; "Why use it" precedes "For organizations" (developer-first, then enterprise).
• Fixed manual validation by AI → independent AI validation backed by execution evidence.
• Softened a few over-absolute claims in the deep-dive for enterprise credibility; made the daily-work bullets consistent and outcome-led.

Why

The README's content was strong but front-loaded with explanation; this trades some prose for visuals, a concrete example, and a faster trial path.

Reviewer notes

• Please preview the Mermaid diagram on GitHub — confirm the color classes and legend render legibly in both light and dark themes (third-party gray especially).
• Follow-ups intentionally left out of this PR: syncing the same "validate" phase wording in docs/web/docs/introduction.md, and extending the canonical category line to GitHub About / pyproject descriptions / site metadata.

🤖 Generated with Claude Code

[esteinberg]

Follow-up work (if this PR is accepted)

This PR was deliberately scoped to README.md only. To finish the job, these follow-ups should be done in separate changes:

1. Verify the Mermaid diagram renders

• Open the Files changed tab and confirm the color-coded "How it works" diagram renders legibly in both light and dark GitHub themes (the third-party gray especially). Adjust classDef hues if washed out.

2. Propagate the canonical positioning line everywhere

The README hero now stays outcome-driven, but the canonical category line — "Meta-prompting, context engineering, and centralized instruction management for AI coding agents" — should be made consistent across the other surfaces, which currently differ:

• GitHub repo About / description
• src/*/pyproject.toml package descriptions (ims-mcp, rosetta-cli)
• docs/web site <meta> description and docs intro

3. Sync duplicated phase wording

• docs/web/docs/introduction.md:31 still reads Validate (manual validation by AI). Update it to match the README's independent AI validation backed by execution evidence so the phase description is consistent site-wide.

4. Consider a dedicated comparison page

We deliberately kept the README lean and used only a short "Why not just use IDE rules?" section. A fuller comparison vs .cursorrules / CLAUDE.md / Copilot custom instructions / internal wiki could live on a separate docs/ page rather than the top-level README.

🤖 Generated with Claude Code

[github-actions]

Rosetta Triage Review

Summary: This PR is a focused editorial pass on README.md to improve time-to-understanding for first-time GitHub visitors — adding a Without/With comparison table, a concrete side-by-side example, a Mermaid architecture diagram, and a cleaner Quick Start section. No code or behavioral changes.

Findings:

• Documentation-only change (single file: README.md); no code paths affected, no tests needed.
• Positioning reframed from "governance and context layer" to "context engineering and governed instructions" — more accurate and consistent with project vocabulary.
• Mermaid diagram uses explicit fill, stroke, and color classDef properties, aligned with the project guideline for readable colors in both light and dark themes. Reviewer attention flagged by the author — verify the light gray (#d0d7de) third-party node contrast in light mode.
• Hardcoded hosted MCP URL (https://mcp.rosetta.griddynamics.net/mcp) added to Quick Start — intentional for public documentation; confirm this is the stable production endpoint.
• The concrete "rate limiting" example and Without/With table improve scanability and reduce time-to-first-value for new visitors.
• PR description is detailed and well-structured (What / Why / Reviewer notes).

Suggestions:

• Consider whether the follow-up items noted in the PR body (syncing docs/web/docs/introduction.md and updating GitHub About / pyproject descriptions) should be filed as separate issues to avoid losing track.
• Verify the Mermaid diagram renders correctly in GitHub's light and dark themes before merging, as the author requested.

Automated triage by Rosetta agent

[isolomatov-gd]

We need more work on this one, we added more text, I'd like to think how we can either reduce it or move it.
I like idea and changes to subheader a lot.

Some things needs to be reverted: **Teach agents how to think, not what to do.** section lost its value and just a duplicate of the subheader.

I am not sure about having init workflow inside of the readme, but I really like the diagram. Maybe we should show like that our quickstart process and we can use similar to show few workflows.

[esteinberg]

Update: trimmed length + init-as-diagram

Pushed a follow-up commit addressing length/duplication feedback:

• Reverted the hero tagline to "Teach agents how to think, not what to do" — the "Encode your engineering discipline" variant duplicated the subheader.
• Cut redundancy in the intro: removed the 7 "daily work" bullets and collapsed the 5-line phases list into one line. The Without/With + Example tables and the How-it-works diagram already carry this, so the run-up to Quick Start is ~18 lines shorter.
• Quick Start init is now a process diagram (ask → Rosetta analyzes → workspace files → build), with the full step-by-step kept in QUICKSTART.md rather than inline.

Added to follow-up backlog

• Workflow diagrams: extend the same visual style to show a few key workflows (e.g. coding, AQA) — deferred to a separate PR to keep this one focused.