diff --git a/README.md b/README.md
index 8394baf..3ca86c6 100644
--- a/README.md
+++ b/README.md
@@ -1,43 +1,94 @@
 # hephaestus
 
-A personal context management system — a unified, self-hosted application that fuses a wiki-style knowledge base (Zettelkasten) with task management. Built in Rust, offline-capable, and syncs to a central instance hosted in blumeops.
+A personal context management system — a single, self-hosted Rust application that fuses a wiki-style knowledge base (Zettelkasten) with task management. Notes and tasks are **first-class, cross-linkable entities** in one database, so a task like "Fix the roof leak" stays coupled to the home-repair log and contractor-call notes that give it context.
 
-See [the project design document](docs/explanation/design.md) for goals, architecture, and the development roadmap.
+It is **offline-first**: fully useful on a laptop with no network, and (when the distributed layer lands) auto-syncing to a central instance hosted in blumeops. The primary surface will be a Neovim plugin (`heph.nvim`, an obsidian.nvim replacement); a CLI (`heph`) is the utility/scripting surface.
 
-## What's Included
+> **Why "what is next?" is the flagship.** heph is organized around concise, honest answers to recurring questions — above all *"what do I do right now?"* — built from ~10 years of the owner's lived prioritization discipline: projects-as-contexts; attention colors (white/orange/red/blue, where **red = a consequence exists if late**, not importance); **do-dates, not due-dates** (earliest-actionable, never a deadline alarm); and working-set tensions surfaced honestly (no "fake happy", no overwhelm).
 
-- **Documentation** — [Diataxis](https://diataxis.fr/)-structured docs built with [Quartz](https://quartz.jzhao.xyz/)
-- **Changelog** — [Towncrier](https://towncrier.readthedocs.io/) fragment-based changelog
-- **CI/CD** — [Dagger](https://dagger.io/) pipelines + Forgejo `build` and `release` workflows
-- **Pre-commit hooks** — [prek](https://github.com/dustinblackman/prek) with linting, formatting, secret detection
-- **AI assistance** — `AGENTS.md` + structured docs for Claude Code (C0/C1/C2 change process, Mikado method)
-- **Task runner** — [mise](https://mise.jdx.dev/) tasks for docs validation, Mikado chain management, release preview, and runner inspection
+See **[docs/explanation/design.md](docs/explanation/design.md)** for the vision and rationale, and **[docs/reference/tech-spec.md](docs/reference/tech-spec.md)** for the implementation-facing specification.
 
-## Getting Started
+## Status
+
+**Phase 1 (v1 prototype) — in progress** on branch `feature/v1-prototype`. The **local-only system is feature-complete and the offline-sync merge engine converges**; remaining work is the network transport, auth, and the Neovim plugin. Built test-first (102 tests at last update). The canonical tracker is **tech-spec §14**.
+
+| Area | State |
+|---|---|
+| Data model, markdown extraction, wiki-links, export | ✅ done |
+| Tasks, links, "what is next?" ranking, recurrence, per-task logs | ✅ done |
+| `hephd` daemon — **local mode** (file lock + JSON-RPC over a unix socket) | ✅ done |
+| `heph` CLI; `list` / `health` / `journal` / full-text `search` (FTS5) | ✅ done |
+| Sync engine — HLC, op-log, converging merge + conflict queue (no network yet) | ✅ done |
+| yrs text-CRDT for body merge | ⏳ next |
+| `server`/`client` modes + network push/pull sync | ⏳ |
+| OIDC/Authentik auth + per-user isolation | ⏳ |
+| `heph.nvim` (primary surface) | ⏳ |
+
+## Architecture
+
+A Cargo workspace, layered so the same core runs from a laptop to a hub:
+
+- **`crates/heph-core`** — the library: data model, the `Store` trait + SQLite store, markdown parsing/extraction, recurrence, the "what is next?" engine, and the sync engine (op-log, hybrid logical clocks, CRDT/LWW merge, conflict detection). Synchronous and clock-injected (no ambient wall-clock reads) so ranking and merge are deterministic.
+- **`crates/hephd`** — the per-device daemon. One binary, three modes — **`local`** (own SQLite replica), **`server`** (also a network endpoint + sync hub), **`client`** (thin, remote) — selected by configuration via a targetable `Store` backend. Surfaces connect to it over a unix socket; it owns the DB handle and (later) background sync.
+- **`crates/heph`** — the CLI: a thin client of the daemon (no direct DB access).
+- **`heph.nvim/`** *(planned)* — the Neovim plugin, the primary editing/agenda surface.
+
+**Storage:** SQLite is the source of truth; a node's body is markdown; `export` materializes the whole store as a directory of `.md` files. **Sync:** each device holds a full replica + an append-only op-log; devices reconcile through a hub with automatic merge (text-CRDT bodies, last-writer-wins scalars, OR-set links) and a conflict queue for the ambiguous remainder. **Auth** *(planned)*: OIDC against Authentik, with per-user isolation.
+
+## Build & run
+
+Requires a Rust toolchain (stable). The build is a standard Cargo workspace:
 
 ```bash
-# Install git hooks
-prek install && prek install --hook-type commit-msg
-
-# Run all pre-commit checks
-prek run --all-files
-
-# List available tasks
-mise tasks
-
-# Build docs (requires Dagger)
-dagger call build-docs --src=. --version=dev export --path=./docs-dev.tar.gz
+cargo build              # build all crates
+cargo test --all         # run the full test suite
+cargo clippy --all-targets -- -D warnings
 ```
 
-## Project Structure
+Run the daemon in local mode, then drive it with the CLI:
+
+```bash
+# Terminal 1 — start the daemon (creates ~/.local/share/heph/heph.db and a socket)
+cargo run -p hephd
+
+# Terminal 2 — talk to it
+cargo run -p heph -- task "Fix the roof leak" --attention red
+cargo run -p heph -- next                 # the "what is next?" ranking
+cargo run -p heph -- doc "Roof log" --body "Called the contractor."
+cargo run -p heph -- search roof          # full-text search
+cargo run -p heph -- journal 2026-06-01   # open/create today's journal
+cargo run -p heph -- export ./snapshot    # write the store as a .md tree
+```
+
+The daemon takes an exclusive lock on its DB file; `--db` and `--socket` override the defaults.
+
+## Development
+
+- **Test-driven.** Every feature has tests at the appropriate layer(s) — unit, property tests, real-socket daemon integration, and CLI process tests. No feature is "done" without them.
+- **Change process.** Changes are classified **C0 / C1 / C2** (quick fix / human-review PR / Mikado chain). The v1 prototype is a single long-lived **C1**. See [docs/how-to/agent-change-process.md](docs/how-to/agent-change-process.md).
+- **Git hooks & tooling.** [prek](https://github.com/dustinblackman/prek) runs formatting, linting, and secret detection; [mise](https://mise.jdx.dev/) runs repo automation; CI (Forgejo) runs `prek` plus `cargo fmt`/`clippy`/`test` via `.forgejo/scripts/build`.
+
+```bash
+prek install && prek install --hook-type commit-msg   # set up hooks
+prek run --all-files                                  # run all checks
+mise tasks                                            # list automation tasks
+mise run ai-docs                                      # docs AI agents read first
+```
+
+- **Documentation** is [Diataxis](https://diataxis.fr/)-structured and built with [Quartz](https://quartz.jzhao.xyz/); changelog fragments use [Towncrier](https://towncrier.readthedocs.io/) under `docs/changelog.d/`. Working agents should read **[AGENTS.md](AGENTS.md)** first.
+
+## Repository layout
 
 ```
-./docs/                 # documentation (Diataxis, Quartz)
-./docs/changelog.d/     # leave only .gitkeep in the template; generated repos add towncrier fragments here
-./.dagger/              # Dagger module backing docs builds and releases
-./.forgejo/workflows/   # generic build/release workflows for generated repos
-./.forgejo/scripts/     # optional per-project hooks consumed by those workflows
-./mise-tasks/           # scripts via `mise run`
+./Cargo.toml            # workspace manifest
+./crates/heph-core/     # core library: model, store, extraction, recurrence, ranking, sync
+./crates/hephd/         # daemon: local mode (JSON-RPC over a unix socket); server/client planned
+./crates/heph/          # CLI: thin client of the daemon
+./heph.nvim/            # Neovim plugin (planned)
+./docs/                 # Diataxis docs (design, tech-spec, how-to), Quartz config
+./.forgejo/             # CI build + release workflows and hooks
+./.dagger/              # Dagger module backing docs builds/releases
+./mise-tasks/           # repo automation via `mise run`
 ```
 
 ## License