docs: reorganize developer documentation

README.md

@@ -1,5 +1,31 @@
-# 夜居 | Yoi agent
+# Yoi
 
-夜居(Yoi)は不休のエージェントループを回すためのエージェントプラットフォーム。
+Yoi is an agent runtime for building, running, and orchestrating LLM Pods while preserving explicit history, scoped capabilities, and developer-controlled workflows.
 
-ワークフローを統括し、四六時中電力を消費し、イテレーションします。
+Runtime surfaces use `yoi`, `.yoi`, `~/.yoi`, and `YOI_*`.
+
+## Documentation map
+
+Start with [`docs/README.md`](docs/README.md). The repository documentation is intentionally small: it should explain current design intent and development workflow, not preserve every old plan or external research note.
+
+Important entry points:
+
+- [`docs/design/overview.md`](docs/design/overview.md) — architecture and crate ownership map.
+- [`docs/design/context-history.md`](docs/design/context-history.md) — the rules for history, context, and prompt-cache-safe inputs.
+- [`docs/design/pod-session-state.md`](docs/design/pod-session-state.md) — why Pod metadata, session logs, and live runtime hints are separate.
+- [`docs/development/work-items.md`](docs/development/work-items.md) — work item and ticket workflow.
+- [`docs/development/validation.md`](docs/development/validation.md) — validation expectations.
+
+## Development
+
+This repository dogfoods Yoi to develop Yoi. Work is tracked through `work-items/` and `./tickets.sh`; git history plus work item files are the authoritative record of state changes.
+
+Common local checks:
+
+```sh
+./tickets.sh doctor
+git diff --check
+cargo test --workspace
+```
+
+E2E testing with real spawned processes is not yet designed. Avoid adding compatibility layers or broad formatting churn only to reduce short-term edit size; prefer clear boundaries and type safety.