docs: shorten guides and map repository filesHEADmain

1 files changed, 43 insertions, 65 deletions

diff --git a/README.txt b/README.txt
index 516f09b..c680f43 100644
--- a/README.txt
+++ b/README.txt
@@ -15,85 +15,63 @@ along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 STACK
 
-    Personal web services, developed and managed through a root Cargo workspace.
-    Copyright (C) 2026 Doan Luu Duc Tai <doan@luuduct.ai>
-    GNU Affero General Public License, version 3 or later. See LICENSE.
+    Four services: Caddy, cgit, SearXNG, Rust private chat.
+    Rust management CLI; strict TypeScript browser code; GNU LibreJS checks.
+    SearXNG and cgit's upstream supervisor use third-party Python. No first-party Python.
+    License: GNU Affero General Public License, version 3 or later. See LICENSE.
 
-GETTING STARTED
+START LOCAL
 
-    Install Rust through rustup, Podman, Git, and GnuPG on a Linux development
-    machine, plus Node >=22.18.0 and npm for the TypeScript browser build.
-    Chat builds also need a GCC-compatible C compiler, Linux UAPI
-    headers, libclang, pkg-config, make, Perl, curl, tar, and OpenSSL 3.5+
-    development libraries for native workspace checks. The pinned toolchain
-    includes rustfmt, Clippy, and the static x86_64 Linux target.
-    See docs/CHAT-PRODUCTION.txt for the native/WASI release build.
-
-    From this directory:
+    Linux tools: rustup, Podman, Git, GnuPG, Node >=22.18.0, npm.
+    Native chat checks: GCC-compatible C compiler, Linux UAPI headers, libclang,
+    pkg-config, make, Perl, curl, tar, OpenSSL >=3.5 development libraries.
+    Pinned Rust includes rustfmt, Clippy, static x86_64 Linux target.
+    Native/WASI release builds: docs/CHAT-PRODUCTION.txt.
 
         cargo stack dev
         cargo stack status
         cargo stack down
 
-    Browse http://localhost:8080, /git/, /search/, and http://chat.localhost:8080/.
-    A fresh checkout generates a private .env automatically.
-    Local mode binds only loopback and does not request public certificates.
-
-DEVELOPMENT AND PRODUCTION
-
-    src/main.rs forwards to the private Rust management implementation in
-    src/app.rs and src/app/. Future Rust application backends
-    belong in crates/. Add each crate to the root workspace explicitly and
-    inherit its strict workspace lints.
-
-    infra/ holds service definitions, proxy configuration, container sources,
-    and the production user service. web/ holds the public website and WKD.
-    docs/ contains plaintext operations and policy documentation.
+    Open http://localhost:8080, /git/, /search/, http://chat.localhost:8080/.
+    Fresh checkout creates private .env. Local mode: loopback only, no public TLS.
 
-    The single root .env holds deployment settings and configured secrets.
-    The commented .env.example documents hostnames, ports, upstreams, chat,
-    backup recipients, and secret-setting names. See docs/CONFIGURATION.txt.
-    var/ contains private persistent data, container storage, temporary work,
-    and exports. Generated TLS private keys are runtime data under var/.
-    .env, var/, .tools/, target/, bin/, dist/, and node_modules/ are excluded
-    from Git. Browser code and tests are TypeScript; see docs/TYPESCRIPT.txt.
+FILES AND STATE
 
-    The four services are Caddy, cgit, SearXNG, and the Rust chat server. The management
-    command is Rust. SearXNG and the cgit container's upstream supervisor retain
-    their third-party Python implementation. No first-party Python is needed.
+    Full file tree and uses: docs/MAP.txt. Rules: docs/POLICY.txt.
+    CLI: src/main.rs, src/app.rs, src/app/. Backends: crates/.
+    Add crates explicitly to root workspace; inherit strict workspace lints.
+    infra/: services, proxy, containers, user service. web/: site and WKD.
+    docs/: .txt guides. Browser code/tests: TypeScript; docs/TYPESCRIPT.txt.
 
-    Build and test on the development machine. Deploy prebuilt release
-    archives. The production host needs Podman, Git, and GnuPG, but no Rust
-    toolchain, Cargo, Node, npm, or TypeScript.
+    Exactly one root .env: settings and configured secrets.
+    One public .env.example: hosts, ports, upstreams, chat, backup keys/placeholders.
+    Generated databases and TLS keys: var/data. More: docs/CONFIGURATION.txt.
+    Git ignores .env, var/, .tools/, target/, bin/, dist/, node_modules/.
 
-CHECKS AND LICENSES
+CHECK AND RELEASE
 
         cargo install --locked --version 0.20.2 cargo-deny --root .tools
         cargo install --locked --version 0.9.3 --features cli cargo-about --root .tools
         cargo stack check
         cargo stack release
 
-    Check builds and checks TypeScript, then runs Rust formatting, Clippy, tests,
-    rustdoc, cargo-deny, and cargo-about. npm development dependencies are pinned
-    in package-lock.json. Typed ESLint, both compiler checks, and npm audit are
-    included. See docs/LINTING.txt for policy choices and tested exceptions.
-    THIRD-PARTY-LICENSES.html is generated from Cargo.lock and about.hbs.
-    Human-readable license headings use GNU's names. SPDX identifiers and
-    original third-party legal texts retain their exact spelling.
-
-    Detailed manual backup, recovery, deployment, and host setup instructions
-    are in docs/OPERATIONS.txt. Read docs/POLICY.txt before changing conventions.
-
-EXPERIMENTAL CHAT
-
-    main includes the experimental Rust/WASI chat application. Start with
-    docs/CHAT-APPLICATION.txt for setup, protected files, tests, backup/restore,
-    source licensing, and security limitations. cargo stack chat --init appends
-    chat configuration to the existing single root .env; cargo stack chat runs
-    the direct local service. docs/CHAT-PRODUCTION.txt describes its packaged
-    HTTPS gateway, release deployment, production owner setup, and recovery.
-    Building a release does not activate production.
-
-    SQLite snapshots use the bundled SQLite C library. Release scripts build
-    static OpenSSL against hash-verified musl headers and the Rust musl target.
-    Runtime binaries remain static; no compiler is required on the VPS.
+    Check: TypeScript build, both compilers, typed ESLint, npm audit; Rust fmt,
+    Clippy, tests, private rustdoc, cargo-deny, cargo-about. npm lock: package-lock.json.
+    Policy and tested exceptions: docs/LINTING.txt.
+    Cargo.lock + about.hbs generate THIRD-PARTY-LICENSES.html.
+    Display GNU license names; preserve exact SPDX identifiers and upstream legal text.
+
+    Build/test locally. Deploy prebuilt archives. VPS needs Podman, Git, GnuPG;
+    no Rust/Cargo/Node/npm/TypeScript. Backup, restore, host setup, deployment:
+    docs/OPERATIONS.txt. Building a release does not activate production.
+
+CHAT — EXPERIMENTAL
+
+        cargo stack chat --init
+        cargo stack chat
+
+    --init adds settings to existing root .env; chat starts direct local service.
+    Setup, protected files, tests, recovery, licensing, limits: docs/CHAT-APPLICATION.txt.
+    Packaged HTTPS, owner setup, recovery: docs/CHAT-PRODUCTION.txt.
+    SQLite snapshots use bundled SQLite C library. Static releases use OpenSSL,
+    hash-verified musl headers, Rust musl target. VPS needs no compiler.