feat: upgrade repo-level doc prompt for CLAUDE.md-quality narratives

Repo summaries now generate structured, opinionated overviews with:
- What This Project Does (purpose, not generic description)
- Architecture (entry points, request flow, key abstractions)
- Key Patterns (conventions an agent must match)
- Where Things Live (non-obvious file ownership map)
- Gotchas (surprises, race conditions, naming traps)

Addresses Mike/Dmitry feedback: roll-up summaries must be 'actually usable.'
Old prompt produced 4-6 generic sentences. New prompt produces a real
onboarding doc that reads like a senior engineer wrote it.

docgen.py

@@ -90,17 +90,33 @@ def generate_repo_doc(readme: str, entry_files: list[tuple[str, str]]) -> str:
 
     readme_section = readme[:3000] if len(readme) > 3000 else readme
 
-    prompt = f"""You are a senior software engineer writing a project overview.
+    prompt = f"""You are a senior software engineer writing a project overview that will be consumed by AI coding agents and new developers joining the team.
 
-Based on the README and key source files below, write a 4-6 sentence summary of this project. Cover:
+Write a concise but opinionated overview of this project. This should read like the best possible onboarding document — the kind a senior engineer writes after spending a week with the codebase. It should help someone (human or AI) understand the system well enough to start making changes confidently.
-- What the project does (its purpose)
+
-- Key architectural patterns (routing, middleware, etc.)
+Structure your response with these sections (use markdown headers):
-- The main abstractions and how they fit together
+
+## What This Project Does
+One paragraph. What problem does it solve? Who uses it? Be specific, not generic.
+
+## Architecture
+How is the code organized? What are the key abstractions and how do they compose? Mention the main entry points and the flow of a typical request/operation through the system. Name specific files and types.
+
+## Key Patterns
+What conventions does this codebase follow? Middleware chains, handler signatures, error handling patterns, configuration approach. An agent needs to match these patterns when writing new code.
+
+## Where Things Live
+A brief map: which directories/files own which concerns. Focus on the non-obvious — things a newcomer would waste time searching for.
+
+## Gotchas
+Anything surprising, non-obvious, or easy to get wrong. Race conditions, initialization order, naming conventions that break expectations.
+
+Be direct and opinionated. Say "the router is the heart of the system" not "the project contains routing functionality." Use file names and type names. Skip generic statements about Go or web frameworks.
 
 README:
 {readme_section}
 
-Key source files:
+Key source files (with their generated documentation):
 {files_section}
 
 Project Overview:"""