diff --git a/README.md b/README.md
index aa5cceb162..75e879669b 100644
--- a/README.md
+++ b/README.md
@@ -17,6 +17,4 @@ yarn demo:echo     # runnable echo-agent example (no API key needed)
 yarn demo:coding   # the real DeepSeek coding agent (needs DEEPSEEK_API_KEY)
 ```
 
-For agent instructions see [AGENTS.md](AGENTS.md). For the architecture design see [docs/architecture.md](docs/architecture.md). Each subdirectory has its own README.md with local context: [packages/](packages/), [vendor/](vendor/).
-
-For local setup, hooks, environment variables, and quality gates, see the [development guide](docs/development.md).
+For humans, start with the [development guide](docs/development.md) for local setup, hooks, environment variables, and quality gates, then read the [architecture design](docs/architecture.md) before package work. For agents, follow [AGENTS.md](AGENTS.md). Local context lives in [packages/](packages/) and [vendor/](vendor/).