From 9a33cb5384e498af5f47acb451f55668a95ebf7e Mon Sep 17 00:00:00 2001 From: iris <2+iris@noreply.localhost> Date: Sat, 5 Sep 2026 13:03:42 -0400 Subject: [PATCH] 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 --- AGENTS.md | 42 ++++++++++++------- client-core/Cargo.toml | 2 +- client-core/src/lib.rs | 2 +- client-core/src/transcript_cache.rs | 4 +- CLIENT_CORE.md => docs/CLIENT_CORE.md | 0 DECISIONS.md => docs/DECISIONS.md | 0 EXPLORER.md => docs/EXPLORER.md | 0 IRIS.md => docs/IRIS.md | 0 IRIS_TODO.md => docs/IRIS_TODO.md | 0 LAYOUT.md => docs/LAYOUT.md | 0 PLAN.md => docs/PLAN.md | 0 RUST.md => docs/RUST.md | 0 TEXTURES.md => docs/TEXTURES.md | 0 TODO.md => docs/TODO.md | 0 .../TRANSCRIPT_CACHE.md | 0 15 files changed, 30 insertions(+), 20 deletions(-) rename CLIENT_CORE.md => docs/CLIENT_CORE.md (100%) rename DECISIONS.md => docs/DECISIONS.md (100%) rename EXPLORER.md => docs/EXPLORER.md (100%) rename IRIS.md => docs/IRIS.md (100%) rename IRIS_TODO.md => docs/IRIS_TODO.md (100%) rename LAYOUT.md => docs/LAYOUT.md (100%) rename PLAN.md => docs/PLAN.md (100%) rename RUST.md => docs/RUST.md (100%) rename TEXTURES.md => docs/TEXTURES.md (100%) rename TODO.md => docs/TODO.md (100%) rename TRANSCRIPT_CACHE.md => docs/TRANSCRIPT_CACHE.md (100%) diff --git a/AGENTS.md b/AGENTS.md index af47340..4531760 100644 --- a/AGENTS.md +++ b/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, -its rationale, and what was rejected. Read it before changing anything +**`docs/PLAN.md` is the design source of truth** — every decision with its +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 - `FilesScreen.kt` / `FileViewer.kt` / `FileEditor.kt`). -- `TRANSCRIPT_CACHE.md` — the phone's copy of what it has been sent. Read it - before touching `TranscriptCache.kt`, `TranscriptSource.kt`, or the opening - and stream effects in `SessionScreen.kt`. -- `TODO.md` — the working list. -- `RUST.md` — the plan for moving the app to Rust (on the `rustify` - 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/` — every design and working document except this file and + `CLAUDE.md`: + - `docs/EXPLORER.md` — the file explorer's design (`server/src/files.rs` + and `FilesScreen.kt` / `FileViewer.kt` / `FileEditor.kt`). + - `docs/TRANSCRIPT_CACHE.md` — the phone's copy of what it has been sent. + Read it before touching `TranscriptCache.kt`, `TranscriptSource.kt`, or + the opening and stream effects in `SessionScreen.kt`. + - `docs/TODO.md` — the working list. + - `docs/RUST.md` — the plan for moving the app to Rust (on the `rustify` + 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. diff --git a/client-core/Cargo.toml b/client-core/Cargo.toml index 1560b81..953bf55 100644 --- a/client-core/Cargo.toml +++ b/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. # diff --git a/client-core/src/lib.rs b/client-core/src/lib.rs index 80f65f0..852cc1e 100644 --- a/client-core/src/lib.rs +++ b/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; diff --git a/client-core/src/transcript_cache.rs b/client-core/src/transcript_cache.rs index 9196d40..a0ec342 100644 --- a/client-core/src/transcript_cache.rs +++ b/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 -//! for the design and `CLIENT_CORE.md` for how this file corresponds to it. +//! `app/.../TranscriptCache.kt`; see `docs/TRANSCRIPT_CACHE.md` +//! 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`] diff --git a/CLIENT_CORE.md b/docs/CLIENT_CORE.md similarity index 100% rename from CLIENT_CORE.md rename to docs/CLIENT_CORE.md diff --git a/DECISIONS.md b/docs/DECISIONS.md similarity index 100% rename from DECISIONS.md rename to docs/DECISIONS.md diff --git a/EXPLORER.md b/docs/EXPLORER.md similarity index 100% rename from EXPLORER.md rename to docs/EXPLORER.md diff --git a/IRIS.md b/docs/IRIS.md similarity index 100% rename from IRIS.md rename to docs/IRIS.md diff --git a/IRIS_TODO.md b/docs/IRIS_TODO.md similarity index 100% rename from IRIS_TODO.md rename to docs/IRIS_TODO.md diff --git a/LAYOUT.md b/docs/LAYOUT.md similarity index 100% rename from LAYOUT.md rename to docs/LAYOUT.md diff --git a/PLAN.md b/docs/PLAN.md similarity index 100% rename from PLAN.md rename to docs/PLAN.md diff --git a/RUST.md b/docs/RUST.md similarity index 100% rename from RUST.md rename to docs/RUST.md diff --git a/TEXTURES.md b/docs/TEXTURES.md similarity index 100% rename from TEXTURES.md rename to docs/TEXTURES.md diff --git a/TODO.md b/docs/TODO.md similarity index 100% rename from TODO.md rename to docs/TODO.md diff --git a/TRANSCRIPT_CACHE.md b/docs/TRANSCRIPT_CACHE.md similarity index 100% rename from TRANSCRIPT_CACHE.md rename to docs/TRANSCRIPT_CACHE.md