diff --git a/docgen.py b/docgen.py
index be710a9..4f8922b 100644
--- a/docgen.py
+++ b/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:
-- What the project does (its purpose)
-- Key architectural patterns (routing, middleware, etc.)
-- The main abstractions and how they fit together
+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.
+
+Structure your response with these sections (use markdown headers):
+
+## 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:"""