docs/: move the design and working documents out of the repo root (CLAUDE.md and AGENTS.md stay, harnesses read them there)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

AGENTS.md

@@ -5,11 +5,14 @@ replacing the Claude app for daily use. Rust/Axum backend on the desktop,
 Kotlin/Compose Android app, WireGuard + pinned self-signed TLS + bearer token
 between them.
 
-**`PLAN.md` is the design source of truth** — every decision with its date,
+**`docs/PLAN.md` is the design source of truth** — every decision with its
-its rationale, and what was rejected. Read it before changing anything
+date, its rationale, and what was rejected. Read it before changing anything
 structural, and update it in place when a decision changes rather than
 letting this file and the plan become two versions of the truth. This file is
 the working notes layer: layout, commands, rigs, and things that have bitten.
+The design and working documents live under `docs/` — everything except this
+file and `CLAUDE.md`, which stay at the root because that is where Claude
+Code and other agent harnesses look for them.
 
 The central design point, worth not undoing by accident: **a session is a
 child process, translated into one common event model.** A new session type
@@ -22,7 +25,7 @@ Mirrors `../dev-updater` deliberately: same stack (axum 0.8 +
 axum-server/rustls, tokio, clap; Kotlin 2.4.x + Compose Multiplatform, single
 `:androidApp` module), same cert scheme, same registry pattern. Read
 dev-updater's `README.md` and `AGENTS.md` before diverging from them.
-Module-by-module intent is in PLAN.md's "Backend layout".
+Module-by-module intent is in `docs/PLAN.md`'s "Backend layout".
 
 - `server/` — the Rust backend (`ai-server`). `routes.rs`'s module doc
   comment is the HTTP table and the surface's source of truth.
@@ -40,16 +43,23 @@ Module-by-module intent is in PLAN.md's "Backend layout".
   projects version-locked to the commit this repo pins. What deliberately did
   **not** move is the API surface and the config *schema*: routes, drivers,
   sessions and setups are what makes this project itself.
-- `EXPLORER.md` — the file explorer's design (`server/src/files.rs` and
+- `docs/` — every design and working document except this file and
-  `FilesScreen.kt` / `FileViewer.kt` / `FileEditor.kt`).
+  `CLAUDE.md`:
-- `TRANSCRIPT_CACHE.md` — the phone's copy of what it has been sent. Read it
+  - `docs/EXPLORER.md` — the file explorer's design (`server/src/files.rs`
-  before touching `TranscriptCache.kt`, `TranscriptSource.kt`, or the opening
+    and `FilesScreen.kt` / `FileViewer.kt` / `FileEditor.kt`).
-  and stream effects in `SessionScreen.kt`.
+  - `docs/TRANSCRIPT_CACHE.md` — the phone's copy of what it has been sent.
-- `TODO.md` — the working list.
+    Read it before touching `TranscriptCache.kt`, `TranscriptSource.kt`, or
-- `RUST.md` — the plan for moving the app to Rust (on the `rustify`
+    the opening and stream effects in `SessionScreen.kt`.
-  branch of the `ai-app-2` clone): what has to be reproduced, the
+  - `docs/TODO.md` — the working list.
-  framework decision, and the ordered experiments with their pass
+  - `docs/RUST.md` — the plan for moving the app to Rust (on the `rustify`
-  conditions. Read it before touching anything under that branch.
+    branch of the `ai-app-2` clone): what has to be reproduced, the
+    framework decision, and the ordered experiments with their pass
+    conditions. Read it before touching anything under that branch.
+  - `docs/IRIS.md`, `docs/IRIS_TODO.md`, `docs/DECISIONS.md`,
+    `docs/LAYOUT.md`, `docs/TEXTURES.md`, `docs/CLIENT_CORE.md` — iris's
+    own public API log, working list, decisions log, layout/render design,
+    and texture-atlas design, and the client-core crate's design,
+    respectively.
 - `.dev-updater.ron` — what Dev Updater builds here: the server (run as
   `service: Managed(…)`, supervised by Dev Updater's own implementation
   rather than a script kept here) and the APK, in parallel. It points at
@@ -312,7 +322,7 @@ means here:
 ## Sessions outlive the backend
 
 Since 2026-08-29 a session's process is deliberately left running when
-`ai-server` stops, and adopted again when it starts. PLAN.md has the design;
+`ai-server` stops, and adopted again when it starts. docs/PLAN.md has the design;
 day to day:
 
 - **Stopping the server no longer stops the sessions.** After `pkill
@@ -345,7 +355,7 @@ count tells you what continuing a session will cost. Shown, not warned about;
 importing a large session is a choice somebody is entitled to make.
 
 **Never import a Claude Code session that is open in a terminal.** The app
-refuses it — see PLAN.md for the incident that made that a refusal rather
+refuses it — see docs/PLAN.md for the incident that made that a refusal rather
 than a warning.
 
 **One Claude Code session id can name two files, and the listing offers it
@@ -521,4 +531,4 @@ belongs in `~/.claude/TOOLCHAIN.md` or `~/.claude/MACHINE.md` instead.
   `BasicTextField`, which costs two seconds a frame at 128 kB and stops the
   app at 1 MiB, so `EDIT_LIMIT` caps it at 32 kB with the reason said on
   screen. If you make the editor faster, that number is what to move.
-  EXPLORER.md's "What the measurements said" has the rest.
+  docs/EXPLORER.md's "What the measurements said" has the rest.

client-core/Cargo.toml

@@ -7,7 +7,7 @@ edition = "2024"
 # with `server/` via `event-model`), the REST + SSE clients for its HTTP
 # surface (see `server/src/routes.rs`'s module doc for the table), the
 # transcript fold and cache, the markdown block model, the syntax
-# highlighter and the ANSI parser. See CLIENT_CORE.md at the repo root for
+# highlighter and the ANSI parser. See `docs/CLIENT_CORE.md` for
 # what this holds today, what it does not yet, and how it corresponds to
 # the Kotlin it replaces.
 #

client-core/src/lib.rs

@@ -1,5 +1,5 @@
 //! The app's pure logic, shared between the server and any Rust client --
-//! see `CLIENT_CORE.md` at the repo root for what lives here and what does
+//! see `docs/CLIENT_CORE.md` for what lives here and what does
 //! not yet.
 
 pub mod ansi;

client-core/src/transcript_cache.rs

@@ -1,7 +1,7 @@
 //! This phone's copy of the transcripts it has already been sent, so
 //! reopening a session does not download it again. Ported from
-//! `app/.../TranscriptCache.kt`; see `TRANSCRIPT_CACHE.md` at the repo root
+//! `app/.../TranscriptCache.kt`; see `docs/TRANSCRIPT_CACHE.md`
-//! for the design and `CLIENT_CORE.md` for how this file corresponds to it.
+//! for the design and `docs/CLIENT_CORE.md` for how this file corresponds to it.
 //!
 //! What is stored is the server's own JSON for one event per line, in
 //! transcript order. Reading the cache means running the same [`seq_of`]