docs: reorganize README — lead with problem and value

[carlos-alm]

Summary

• Restructure README to lead with the problem (AI agents burning tokens re-orienting in large codebases) instead of defensive competitive comparisons
• New narrative flow: Problem → Value proposition → Ease of use → Quick Start → Reference docs
• Add "three commands to get started" block highlighting zero-config setup
• Add before/after comparison table showing concrete value
• Condense competitive comparison to a single table at the bottom with link to full analysis
• Remove Narsil-MCP head-to-head section
• Add --format mermaid diff-impact example from PR feat: add Mermaid output to diff-impact #58
• Pick up updated benchmark numbers from main (1.9 ms/file native, 6.6 ms/file WASM)

Test plan

• Verify all internal anchor links resolve correctly
• Confirm no duplicate sections remain
• Review rendering on GitHub

[claude]

Claude finished @carlos-alm's task —— View job

---

PR Review: Documentation Reorganization

Reviewing this README reorganization PR using the 4-phase review process:

Todo List

• Phase 1: Root cause analysis - understand problem being solved
• Phase 2: Configuration change detection (not applicable - docs only)
• Phase 3: Test integrity check (not applicable - docs only)
• Phase 4: Code quality review - check formatting, links, content flow
• Final Assessment: Provide rating and recommendation

Phase 1: Root Cause Analysis ✅

Problem Being Solved: The current README leads with defensive competitive comparisons rather than clearly articulating the core problem that codegraph solves. This creates friction for new users who need to understand the value proposition before caring about how it compares to alternatives.

Why This Approach: The reorganization follows a classic product marketing structure (Problem → Solution → Value → Implementation) which is more effective for user conversion and understanding. Leading with "AI agents burn tokens re-orienting in large codebases" immediately resonates with the target audience.

Risk Assessment: LOW RISK - This is pure documentation restructuring with no code changes. The changes improve user experience without affecting functionality.

Phase 2 & 3: Configuration/Test Changes ✅

Not applicable - This PR only changes documentation.

Phase 4: Code Quality Review ✅

Content & Structure

✅ Excellent narrative flow: The new structure (Problem → Value → Ease of use → Quick Start) is much more compelling than the previous competitive-first approach.

✅ Value proposition clarity: The before/after comparison table at lines 62-68 effectively demonstrates concrete value.

✅ "Three commands" section: Lines 50-58 perfectly capture the zero-config promise.

✅ Updated benchmarks: Correctly shows 1.9 ms/file (native) and 6.6 ms/file (WASM) from latest runs.

✅ Mermaid example added: Line 181 includes the new --format mermaid example as mentioned in the PR description.

✅ Competitive analysis condensed: Moved to bottom (lines 535-551) with link to full analysis, removing the head-to-head section as intended.

Critical Issues Found

❌ Broken anchor links (lines 19-27): Several navigation links don't match actual headers:

• #what-codegraph-does → should be #what-codegraph-does ✅ (this one works)
• #-language-support → should be #-language-support ✅ (this one works)
• #-ai-agent-integration → should be #-ai-agent-integration ✅ (this one works)

Actually, I need to check this more carefully - GitHub auto-generates anchors from headers. Let me verify the headers match:

Header: ## 🚀 Quick Start → Anchor should be: #-quick-start ✅
Header: ## 📦 Commands → Anchor should be: #-commands ✅
Header: ## 🌐 Language Support → Anchor should be: #-language-support ✅
Header: ## 🤖 AI Agent Integration → Anchor should be: #-ai-agent-integration ✅
Header: ## ⚙️ How It Works → Anchor should be: #️-how-it-works ✅
Header: ## 📋 Recommended Practices → Anchor should be: #-recommended-practices ✅
Header: ## 🗺️ Roadmap → Anchor should be: #️-roadmap ✅

The anchor links appear correct for GitHub's auto-generation.

⚠️ Nested "Code Navigation" header (line 376): There's a ## Code Navigation header nested under ## 🤖 AI Agent Integration. This should probably be ### Code Navigation to maintain proper hierarchy.

Minor Issues

✅ No duplicate sections found
✅ Markdown formatting is clean
✅ All mentioned changes from PR description are present

Root Cause Analysis

Problem Being Solved: Poor user onboarding due to defensive positioning instead of value-first messaging
Why This Approach: Follows proven product marketing patterns (problem → solution → value → implementation)
Risk Assessment: MINIMAL - Documentation-only changes with clear improvement to user experience

Critical Concerns

Minor header hierarchy issue: Line 376 uses ## Code Navigation when it should be ### Code Navigation for proper nesting under the AI Integration section.

Final Recommendation

• Rating: ⭐⭐⭐⭐☆ (4/5)
• Action: APPROVE WITH CONDITIONS
• Reasoning: Excellent content reorganization that significantly improves user experience and onboarding. The new narrative structure is compelling and addresses the core problem effectively. The only issue is a minor header hierarchy problem that should be fixed before merge.

Recommended fix: Change line 376 from ## Code Navigation to ### Code Navigation

---

[greptile-apps]

Greptile Summary

This PR successfully restructures the README to lead with the problem AI agents face (re-orienting in large codebases, wasting tokens) and the concrete value codegraph provides, rather than starting with defensive competitive comparisons.

Key improvements:

• New narrative flow: Problem → Solution → Quick Start → Reference docs
• "Three commands to get started" block highlights zero-config setup
• Before/after comparison table shows concrete value (20+ tool calls → 1 call)
• Competitive comparison condensed to single table at bottom with link to full analysis
• Removed lengthy Narsil-MCP head-to-head section
• Added --format mermaid example for diff-impact command (from PR feat: add Mermaid output to diff-impact #58)
• Updated benchmark numbers (1.9 ms/file native, 6.6 ms/file WASM) from main

All verification checks passed:

• All internal anchor links resolve correctly
• All referenced files exist (docs/ai-agent-guide.md, generated/COMPETITIVE_ANALYSIS.md, etc.)
• No duplicate sections found
• Formatting is consistent throughout

Confidence Score: 5/5

• This PR is completely safe to merge — documentation-only changes with no code modifications
• Score of 5 because this is a pure documentation PR that restructures content without changing any code, configuration, or dependencies. All internal links verified, all referenced files exist, and the narrative flow improvement is clear and well-executed.
• No files require special attention

Important Files Changed

Filename	Overview
README.md	Complete restructure of README — leads with problem/value, condenses competitive comparison, adds concrete examples, all links verified

_{Last reviewed commit: 545aa0f}

[greptile-apps]

_{1 file reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[claude]

Claude finished @carlos-alm's task —— View job

---

PR Review: Documentation Reorganization

Reviewing this README reorganization PR using the 4-phase review process:

Todo List

• Phase 1: Root cause analysis - understand problem being solved
• Phase 2: Configuration change detection
• Phase 3: Test integrity check
• Phase 4: Code quality review - check formatting, links, content flow
• Final Assessment: Provide rating and recommendation

Phase 1: Root Cause Analysis ✅

Problem Being Solved: The current README leads with defensive competitive comparisons rather than clearly articulating the core problem that codegraph solves. This creates friction for new users who need to understand the value proposition before caring about how it compares to alternatives.

Why This Approach: The reorganization follows a classic product marketing structure (Problem → Solution → Value → Implementation) which is more effective for user conversion and understanding. Leading with "AI agents burn tokens re-orienting in large codebases" immediately resonates with the target audience.

Risk Assessment: LOW RISK - This is pure documentation restructuring with no code changes. The changes improve user experience without affecting functionality.

Phase 2 & 3: Configuration/Test Changes ✅

Not applicable - This PR only changes documentation. The package-lock.json changes are just version updates (2.1.0 → 2.2.1) for the platform-specific native addon packages, which is expected maintenance.

Phase 4: Code Quality Review ✅

Content & Structure

✅ Excellent narrative flow: The new structure (Problem → Value → Ease of use → Quick Start) is much more compelling than the previous competitive-first approach.

✅ Value proposition clarity: The before/after comparison table at lines 62-68 effectively demonstrates concrete value.

✅ "Three commands" section: Lines 50-58 perfectly capture the zero-config promise.

✅ Updated benchmarks: Correctly shows 1.9 ms/file (native) and 6.6 ms/file (WASM) from latest runs.

✅ Mermaid example added: Line 181 includes the new --format mermaid example as mentioned in the PR description.

✅ Competitive analysis condensed: Moved to bottom (lines 535-551) with link to full analysis, removing the head-to-head section as intended.

Link Verification

✅ All internal anchor links verified: Navigation links (lines 19-27) correctly point to existing headers:

• #the-problem → "## The Problem" ✅
• #what-codegraph-does → "## What Codegraph Does" ✅
• #-quick-start → "## 🚀 Quick Start" ✅
• #-language-support → "## 🌐 Language Support" ✅
• #-ai-agent-integration → "## 🤖 AI Agent Integration" ✅
• #-how-it-works → "## ⚙️ How It Works" ✅
• #-recommended-practices → "## 📋 Recommended Practices" ✅
• #-roadmap → "## 🗺️ Roadmap" ✅

✅ All external file links verified: All referenced docs exist:

• docs/ai-agent-guide.md ✅
• docs/recommended-practices.md ✅
• docs/adding-a-language.md ✅
• generated/COMPETITIVE_ANALYSIS.md ✅
• ROADMAP.md ✅
• CONTRIBUTING.md ✅

Critical Issues Found

❌ Header hierarchy issue (line 376): The "## Code Navigation" header should be "### Code Navigation" for proper nesting under the "### CLAUDE.md / Agent Instructions" section.

Minor Observations

✅ No duplicate sections found
✅ Markdown formatting is clean and consistent
✅ All mentioned changes from PR description are present
✅ Package-lock.json changes are legitimate version updates

Root Cause Analysis

Problem Being Solved: Poor user onboarding due to defensive positioning instead of value-first messaging
Why This Approach: Follows proven product marketing patterns (problem → solution → value → implementation)
Risk Assessment: MINIMAL - Documentation-only changes with clear improvement to user experience

Critical Concerns

Minor header hierarchy issue: Line 376 uses ## Code Navigation when it should be ### Code Navigation for proper nesting under the AI Integration section.

Final Recommendation

• Rating: ⭐⭐⭐⭐☆ (4/5)
• Action: APPROVE WITH CONDITIONS
• Reasoning: Excellent content reorganization that significantly improves user experience and onboarding. The new narrative structure is compelling and addresses the core problem effectively. The only issue is a minor header hierarchy problem that should be fixed before merge.

Recommended fix: Change line 376 from ## Code Navigation to ### Code Navigation

---