diff --git a/AGENTS.md b/AGENTS.md
index b2a2972..6b75d64 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,30 +1,44 @@
 # AGENTS.md
 
-EFS production web client. Vite + Lit. This is the public-facing client (cf. `packages/nextjs/` in `efs-project/contracts`, which is a Scaffold-ETH-based debug UI — not this).
+EFS legacy v1 web client. Vite + Lit.
 
-> **Outdated.** This repo lags `efs-project/contracts` and the planning vault. Don't assume documentation here reflects current EFS state until you've verified against `contracts/specs/` and the planning vault's `Designs/`. A modernization pass is on the cross-repo Backlog.
+> **Repository status (2026-07-23): reference implementation, not the Client v2
+> target.** This code predates the from-scratch EFS v2 redesign and lags the
+> deployed v1 contracts. Do not start new product architecture or assume this
+> repository will be evolved in place until the Client v2 design chooses an
+> implementation target.
 
-## Read on init
+The active Client v2 design set is:
+https://github.com/efs-project/planning/tree/main/Designs/clientv2
+
+The active protocol redesign is:
+https://github.com/efs-project/planning/tree/main/Designs/efsv2
 
-- [`CLAUDE.md`](./CLAUDE.md) — repo-local architecture and command guide (Claude Code auto-loads this; other agents should read it).
-- [`README.md`](./README.md)
-- [`design.md`](./design.md) — historical, may be stale; cross-check before relying on it.
+## Read on init
 
-## Cross-repo coordination — the planning vault
+- [`CLAUDE.md`](./CLAUDE.md) — how the legacy v1 client is structured and run.
+- [`README.md`](./README.md) — legacy setup.
+- [`design.md`](./design.md) — historical architecture sketch.
 
-EFS uses a separate **planning vault** as the cross-repo coordination point across this repo, the contracts repo, and the future SDK. Repo: [efs-project/planning](https://github.com/efs-project/planning); target layout `/efs/{contracts,client,sdk,planning}/`.
+Read those files to understand this code, not to infer the v2 product model.
 
-The vault holds:
+## Repository boundaries
 
-- Cross-repo designs with a name-first → numbered-at-promotion lifecycle.
-- Cross-repo Kanban board, milestones (notably **OnionDAO hackathon 2026-06-01**), and decisions log.
-- Glossary of cross-cutting EFS terms.
-- Onboarding for AI agents (start-here, conventions, escalation).
+- `client/` is the old Vite/Lit browser client.
+- `contracts/packages/nextjs/` is the newer v1 explorer and debug UI.
+- `planning/Designs/clientv2/` is the current product and OS architecture work.
+- `sdk/` contains an unmerged pre-v2 SDK implementation. It is legacy input,
+  not the API contract for Client v2.
 
-Read the vault's [`AGENTS.md`](https://github.com/efs-project/planning/blob/main/AGENTS.md) for cross-repo tasks. Client-only tasks: this repo's docs are sufficient.
+For deployed v1 on-chain behavior, `contracts/specs/` and
+`contracts/docs/adr/` are authoritative. For v2 architecture and prioritization,
+the planning vault is authoritative.
 
-## Sibling repos
+## Working here
 
-- [`efs-project/contracts`](https://github.com/efs-project/contracts) — Solidity contracts, ADRs, system specs. Authoritative for on-chain behavior.
-- [`efs-project/planning`](https://github.com/efs-project/planning) — cross-repo coordination vault.
-- `efs-project/sdk` (future) — on-chain + off-chain SDK packages, will replace ad-hoc EAS interactions in this client when it lands.
+- Preserve IPFS-compatible relative assets.
+- Treat hardcoded Sepolia addresses, EAS assumptions, topic-tree semantics, and
+  direct SDK usage as v1-specific.
+- Do not retrofit v2 decisions into this repository piecemeal. Wait for an
+  explicit implementation plan or a narrowly scoped maintenance request.
+- If a task spans repos, read the planning vault's `AGENTS.md` first.
diff --git a/CLAUDE.md b/CLAUDE.md
index a401001..ae25607 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,6 +2,10 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+> **Legacy v1 architecture.** This file describes the code that exists here; it
+> does not describe the from-scratch EFS v2 or Client v2 target. Read
+> `AGENTS.md` before acting and use the planning vault for current architecture.
+
 ## Commands
 
 ```bash
diff --git a/README.md b/README.md
index 6dff977..fe4d55c 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,9 @@
 # Ethereum File System Client
 
+> **Legacy v1 client.** This repository is retained as implementation evidence
+> during the EFS v2 redesign. It is not the current Client v2 architecture or an
+> approved base for new v2 work.
+
 This project is in early development and takes some technical skill to set up and use.
 
 ## Getting Started
diff --git a/design.md b/design.md
index bcbf315..406c5a6 100644
--- a/design.md
+++ b/design.md
@@ -1,5 +1,8 @@
 # Ethereum File System (EFS)
 
+> **Historical v1 sketch.** The active Client v2 architecture lives in the
+> planning repository under `Designs/clientv2/`.
+
 This document lays out the components and high level functions
 
 ## Components
@@ -26,4 +29,4 @@ Request resources, visualize attestations
 
 ## Component Load order
 
-Kernel --> libefs --> shell
\ No newline at end of file
+Kernel --> libefs --> shell