docs: expand README as repo orientation and guardrail index

Points anyone (or any agent) landing cold at the vision, decisions, architecture,
data model, and BDD feature specs; states the Clean Architecture / TDD-BDD / TBD
approach and the homelab conventions reused. Notes the repo is pre-code and the
docs are the version-controlled design intent.

README.md

@@ -1,3 +1,44 @@
 # tapir
 
-Watches a user's YouTube/Vimeo subscriptions and summarizes new videos (highlights + takeaways) via local-first AI with optional BYO-AI fallback. Standalone-first; brain is one optional sink. Go.
+Watches a user's YouTube/Vimeo subscriptions and, when a subscribed channel posts a new
+video, summarizes it into highlights and takeaways using a **local-first** AI stack with an
+optional, per-user **BYO-AI** fallback. **Standalone-first**; feeding a personal knowledge
+base ("brain") is one optional sink, not the reason Tapir exists. Written in Go.
+
+## Status
+
+Pre-code. The repository currently holds the **guardrail documentation** — vision, decisions,
+architecture, data model, and behavior specs — committed before implementation so the design
+intent is version-controlled and the build has something to be checked against.
+
+## Read these first (the guardrails)
+
+| Doc | What it is |
+|-----|-----------|
+| [`VISION.md`](VISION.md) | Product vision, principles, and the **staged Definition of Success**. Stage 0 ("useful to me") is the gate before any multi-user work. |
+| [`DECISIONS.md`](DECISIONS.md) | Architecture Decision Records (append-only). Why Go, why no Supabase, standalone-first, captions-first, etc. |
+| [`docs/architecture/architecture.md`](docs/architecture/architecture.md) | C4 context + container diagrams, key sequence diagrams, and the Clean Architecture layering (Mermaid). |
+| [`docs/data-model.md`](docs/data-model.md) | Entities and the per-user isolation model (Stage 0 / Stage 1 scope). |
+| [`docs/use-cases/`](docs/use-cases/) | **Gherkin `.feature` files** — the BDD behavior spec that seeds the test suite. |
+
+## Approach
+
+- **Clean Architecture / ports & adapters.** A provider- and sink-agnostic engine depends only
+  on interfaces (`VideoSource`, `Summarizer`, `Sink`, `SecretStore`). YouTube, Vimeo, the AI
+  router, the user store, and the brain sink are adapters. "Standalone vs homelab" is a wiring
+  choice, not two codebases.
+- **TDD/BDD.** The `.feature` files are the living behavior spec; the use-case core is tested
+  through fake adapters. Behavior is specified as executable scenarios, not prose that drifts.
+- **Trunk-Based Development.** Commit directly to `main`, one logical change per commit, every
+  commit deployable (see ADR-009). CI is the quality gate.
+
+## Conventions
+
+Reuses homelab conventions: Go, Dex for identity, ESO + 1Password for secrets, Postgres for
+persistence. No new auth or secrets system (ADR-002).
+
+## Next
+
+First implementation step: scaffold the Go service (engine + interfaces + the copied `llm`
+package), captions-first, with the store and brain sink adapters — decomposable into
+independent units suitable for a Claude Code swarm. Tracked as the first build issue.