docs: add motivation section and reorganize README

[nicksenap]

Summary

• Add "Why?" section explaining the lightweight approach compared to Playwright/automation tools
• Reorganize sections: motivation → capabilities → setup → internals
• Cleaner flow for new users

🤖 Generated with Claude Code

[claude]

PR Review: Documentation Reorganization

Overview

This PR improves the README structure by adding a motivation section and reorganizing content for better user flow. The changes are documentation-only with no code modifications.

Strengths

1. Better User Journey: The new flow (Why → Tools → Quick Start → Architecture) is more intuitive for new users who want to understand the value proposition before diving into technical details.

2. Clear Value Proposition: The Why section effectively communicates Paparazzi's lightweight approach compared to Playwright/automation tools, which helps users quickly understand when to use this tool.

3. Improved Scannability: Moving the tools table earlier makes it easy for users to quickly assess available functionality.

4. No Breaking Changes: This is purely documentation reorganization with no code changes, making it a safe merge.

Minor Suggestions

1. Tool Description Consistency (README.md:15-24)

   • The simplified tool descriptions lost some valuable details:
     • auto-chunks pages >7000px for take_screenshot
     • with timing for get_network_requests
   • Consider keeping these implementation details as they help users understand capabilities and limitations.

2. Manual Setup Step 3 (README.md:55)

   • Changed from Restart Claude to Restart Claude Desktop or Claude Code
   • Good clarification! This is more precise and helps users across both platforms.

Content Review

Removed Content Analysis:

• Removed duplicate/redundant phrasing without losing information
• Maintained all essential setup steps
• Preserved all tool listings and their core functionality

Added Content Analysis:

• Why section is concise and addresses a clear user need
• Explains the lightweight approach effectively
• Good contrast with Playwright without being dismissive

Test Coverage

N/A - Documentation changes only. Existing tests remain unaffected.

Security Concerns

None - No code changes.

Performance Considerations

None - No code changes.

Final Recommendation

APPROVE

This is a solid documentation improvement that enhances the user experience. The reorganization makes the README more approachable for new users while maintaining all technical accuracy.

The only minor suggestion is to restore the detailed tool descriptions (auto-chunking and timing info) as they provide valuable implementation details without cluttering the table.

Great work on improving the documentation flow!