docs: shorten guides and map repository filesHEADmain

4 files changed, 35 insertions, 47 deletions

diff --git a/crates/README.txt b/crates/README.txt
index 296f1a9..f724a28 100644
--- a/crates/README.txt
+++ b/crates/README.txt
@@ -15,10 +15,7 @@ along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 RUST BACKENDS
 
-    New first-party web backends belong in subdirectories here. Add their
-    paths to the workspace members in the root Cargo.toml. Use edition 2024,
-    AGPL-3.0-or-later, and workspace lints. Keep configured secrets in the one
-    root .env and pass only the required keys to each service.
-
-    The current stack has no blog or comment backend. This directory reserves
-    a place for those features without adding an unused service or database.
+    New web backends belong here. Add paths to root Cargo.toml workspace members.
+    Use edition 2024, AGPL-3.0-or-later, workspace lints.
+    Keep configured secrets in one root .env. Pass each service only required keys.
+    No blog/comment backend or unused service/database exists.
diff --git a/crates/chat-crypto/README.txt b/crates/chat-crypto/README.txt
index 114544d..0fb26e7 100644
--- a/crates/chat-crypto/README.txt
+++ b/crates/chat-crypto/README.txt
@@ -13,34 +13,27 @@ GNU Affero General Public License for more details.
 You should have received a copy of the GNU Affero General Public License
 along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
-
 PRIVATE CHAT CRYPTOGRAPHY
 
     Fixed encryption: RFC 9980 ML-KEM-1024 + X448, OpenPGP v6.
     Signing: ML-DSA-87 + Ed448, OpenPGP v6.
-    Backend: Sequoia 2.4.2 with OpenSSL 3.6.5. No algorithm substitution or
-    vulnerability-advisory exception was used. The original RustCrypto backend
-    is historical and no longer selected.
-
-    This crate implements purpose-specific identity creation, Argon2id/AES-256-GCM
-    protected files, detached authentication proofs, signed two-recipient messages,
-    bounded verified history batches, and the original compatibility probe.
-    Native Rust and browser WASI share the implementation. The standalone command
-    accepts one JSON request on stdin; empty input runs the compatibility probe.
-    Its browser WASI host grants no filesystem or network access. Private request
-    data must remain in local memory and must never be submitted to the server.
-
-    See ../../docs/CHAT-APPLICATION.txt for implemented formats, local setup,
-    tests, backups, and limitations. See ../../docs/CHAT-PRODUCTION.txt for
-    packaged HTTPS integration. Work remains experimental;
-    compatibility tests are not an application security audit.
-
-    ../../docs/CHAT-OPENSSL-MIGRATION.txt records the complete backend decision,
-    pinned source hashes, build flags, FFI/capability limitations, and reviewed
-    dependency-policy exceptions. ../../docs/CHAT-SECURITY-REVIEW.txt records
-    the superseded RustCrypto findings without advisory ignores.
-
-CHECKS FROM THE WORKSPACE ROOT
+    Sequoia 2.4.2 + OpenSSL 3.6.5. No algorithm substitution or advisory exception.
+    Superseded RustCrypto backend is not selected.
+
+    Provides purpose-specific identities, Argon2id/AES-256-GCM protected files,
+    detached authentication proofs, signed two-recipient messages, bounded
+    verified history batches, compatibility probe. Native Rust and browser WASI
+    share code. Standalone CLI: one JSON request on stdin; empty stdin runs probe.
+    Browser WASI has no filesystem/network access. Private requests stay in local
+    memory; never send them to server.
+
+    ../../docs/CHAT-APPLICATION.txt: formats, setup, tests, backups, limits.
+    ../../docs/CHAT-PRODUCTION.txt: packaged HTTPS.
+    ../../docs/CHAT-OPENSSL-MIGRATION.txt: backend decision, source hashes,
+    build flags, FFI/capability limits, reviewed dependency exceptions.
+    Experimental. Compatibility tests are not an application security audit.
+
+CHECK FROM WORKSPACE ROOT
 
         cargo test --locked -p stack-chat-crypto
         cargo run --locked -p stack-chat-crypto
@@ -48,9 +41,8 @@ CHECKS FROM THE WORKSPACE ROOT
         PLAYWRIGHT_BROWSERS_PATH="$PWD/.tools/browsers" npm run test:crypto
         cargo stack check
 
-    Native builds require OpenSSL >=3.5 development files and libclang.
-    The cross-build script supports an x86_64 GNU/Linux development host.
-    Installed browser tooling is excluded from source archives and releases.
-    The TypeScript tests and locked toolchain declarations are public.
-    The probe uses public fixture credentials and creates temporary identities
-    in memory. It does not open the root .env or use the canonical RSA key.
+    Native build: OpenSSL >=3.5 development files, libclang.
+    Cross-build host: x86_64 GNU/Linux. Browser tooling excluded from archives
+    and releases; TypeScript tests and locked toolchain declarations remain public.
+    Probe uses public fixture credentials and temporary in-memory identities.
+    It never opens root .env or uses canonical RSA key.
diff --git a/crates/chat-server/README.txt b/crates/chat-server/README.txt
index 0562385..1cd97d5 100644
--- a/crates/chat-server/README.txt
+++ b/crates/chat-server/README.txt
@@ -13,11 +13,11 @@ GNU Affero General Public License for more details.
 You should have received a copy of the GNU Affero General Public License
 along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
+PRIVATE CHAT SERVER — EXPERIMENTAL
 
-EXPERIMENTAL PRIVATE CHAT SERVER
+        cargo stack chat --init
+        cargo stack chat
 
-    See docs/CHAT-APPLICATION.txt at the workspace root for local setup,
-    file formats, API/security limits, backups, recovery, source licensing,
-    and tests. Start with cargo stack chat --init, then cargo stack chat.
-    See docs/CHAT-PRODUCTION.txt for the prebuilt Podman/HTTPS deployment,
-    production owner setup, and full encrypted export/recovery procedure.
+    From workspace root: local setup, formats, API/security limits, backup,
+    recovery, licensing, tests: docs/CHAT-APPLICATION.txt.
+    Prebuilt Podman/HTTPS, production owner, encrypted export: docs/CHAT-PRODUCTION.txt.
diff --git a/crates/config/README.txt b/crates/config/README.txt
index 8648852..dccfbf4 100644
--- a/crates/config/README.txt
+++ b/crates/config/README.txt
@@ -13,8 +13,7 @@ GNU Affero General Public License for more details.
 You should have received a copy of the GNU Affero General Public License
 along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
-SHARED STACK CONFIGURATION
+SHARED CONFIGURATION
 
-    Public defaults are documented in the root .env.example. Each installation
-    overrides them in the single root .env alongside private settings. Rendering
-    uses an explicit public allowlist. See docs/CONFIGURATION.txt for details.
+    Root .env.example: public defaults. Single root .env: overrides and secrets.
+    Rendering uses explicit public allowlist. See docs/CONFIGURATION.txt at root.