docs: shorten guides and map repository filesHEADmain

1 files changed, 78 insertions, 105 deletions

diff --git a/docs/CHAT-PRODUCTION.txt b/docs/CHAT-PRODUCTION.txt
index 03f5ba4..fdb48a6 100644
--- a/docs/CHAT-PRODUCTION.txt
+++ b/docs/CHAT-PRODUCTION.txt
@@ -16,70 +16,57 @@ along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 PRODUCTION CHAT INTEGRATION
 
-    Implemented on main.
-    Building and testing a release does not activate the VPS. This is experimental software without an
-    independent cryptographic or application security audit. Read the limitations
-    in CHAT-APPLICATION.txt before using it for private conversations.
-
-    Four services run through rootless Podman: Caddy, cgit, SearXNG, and chat.
-    The release contains statically linked x86_64 GNU/Linux management and chat
-    binaries, the WASM browser module, exact corresponding sources, and saved
-    native container images. The chat image starts FROM scratch: no compiler,
-    shell, package manager, or first-party Python. Its root filesystem is read
-    only, capabilities are dropped, and only its private data directory is writable.
-
-    Caddy terminates HTTPS at CHAT_HOST and redirects www.CHAT_HOST while keeping
-    the requested path. CHAT_UPSTREAM defaults to chat:8080 on the private
-    container network. Chat publishes no host ports. Production publishes only
-    the gateway HTTP and TCP/UDP HTTPS ports. Existing host SSH policy is separate.
-
-    The gateway supplies an explicit external origin selected from root .env.
-    The server accepts that exact HTTPS origin or the dedicated local gateway
-    origin. Forwarded client headers never select the trusted origin. Origin
-    checks supplement cryptographic authentication; they are not authentication.
+    Implemented on main. Builds/tests do not activate the VPS. Experimental;
+    no independent cryptographic or application security audit. Read
+    CHAT-APPLICATION.txt limitations before private use.
+
+    Rootless Podman runs Caddy, cgit, SearXNG, and chat. Releases contain static
+    x86_64 GNU/Linux management/chat binaries, browser WASM, exact corresponding
+    sources, and native images. Chat starts FROM scratch: no compiler, shell,
+    package manager, or first-party Python. Root filesystem is read-only;
+    capabilities are dropped; only private data is writable.
+
+    Caddy serves HTTPS at CHAT_HOST and redirects www.CHAT_HOST, preserving paths.
+    CHAT_UPSTREAM defaults to private chat:8080. Chat publishes no host ports;
+    only gateway HTTP and TCP/UDP HTTPS are published. Host SSH policy is separate.
+
+    Root .env selects the explicit external origin. Chat accepts exactly that
+    HTTPS origin or the dedicated local gateway origin. Forwarded client headers
+    cannot select it. Origin checks supplement cryptographic authentication.
 
 BUILD ON THE WORKSTATION
 
-    Current releases require an x86_64 GNU/Linux build host and matching target.
-    Use the pinned Rust toolchain, Podman, Git, GnuPG, a GCC-compatible C compiler,
-    Linux UAPI headers, libclang, pkg-config, make, Perl, curl, tar, Node >=22.18.0,
-    and npm. Native
-    workspace checks need OpenSSL 3.5+ development libraries. Browser testing
-    additionally needs the pinned Playwright, Chromium, and Firefox. These tools remain
-    on the workstation; production does not need Cargo or a compiler.
+    Build host and target must be x86_64 GNU/Linux. Requires pinned Rust, Podman,
+    Git, GnuPG, GCC-compatible C compiler, Linux UAPI headers, libclang, pkg-config,
+    make, Perl, curl, tar, Node >=22.18.0, npm, and OpenSSL 3.5+ development libraries.
+    Browser tests also need pinned Playwright, Chromium, and Firefox. Workstation
+    tools stay local; production needs neither Cargo nor compiler.
 
         cargo stack release
 
-    This first builds/checks TypeScript, then runs formatting, strict Clippy,
-    all workspace tests, rustdoc, cargo-deny,
-    and cargo-about. It then builds static native binaries, the WASI module,
-    corresponding sources, the chat/cgit images, and the complete image export.
-    THIRD-PARTY-LICENSES.html is regenerated from the full workspace before
-    packaging. Check the archive checksum and test recovery before deployment.
+    Runs TypeScript build/checks, formatting, strict Clippy, workspace tests,
+    rustdoc, cargo-deny, and cargo-about. Builds static binaries, WASI, exact
+    sources, chat/cgit images, and complete image export. Regenerates workspace
+    THIRD-PARTY-LICENSES.html. Verify archive checksum and recovery before deployment.
 
     infra/chat/build-native.sh verifies OpenSSL 3.6.5's original source archive:
         a2157c2830efdec3788939b00c9b0638306d3f0bbb76dc4832ee503bb397df98
     It verifies Alpine musl-dev 1.2.6-r3 headers:
         310b51cff12e1d5ce5f135c558a82e2550427da5465bbd16c9ff9b05e63ee3d9
-    Sources come from the official OpenSSL GitHub release and Alpine CDN. The
-    compiler uses isolated musl/GCC built-in headers plus host Linux UAPI headers;
-    glibc headers are excluded. OpenSSL is static, has no dynamic providers, and
-    seeds its RNG through getrandom. The native cryptographic compatibility probe
-    must pass after the build. WASI uses its separately verified SDK and OpenSSL
-    build recorded in CHAT-OPENSSL-MIGRATION.txt. No crypto algorithm was changed.
-
-    Cached inputs live only under .tools/. Rebuild OpenSSL when its version,
-    source, or build flags change. An OpenSSL update requires reviewing upstream
-    security notices, updating every affected URL/hash, native and WASI rebuilds,
-    rerunning both browsers and cargo-deny, regenerating notices and exact source,
-    and repeating release recovery. Never approve a dependency advisory merely
-    to make the build pass. cargo-deny does not audit C/OpenSSL advisories.
-
-    The source download includes first-party code, Cargo-vendored dependencies,
-    and unmodified OpenSSL source. Toolchain/sysroot development inputs are not
-    bundled as application sources. Saved images preserve the tested runtime.
-    An ARM host needs a separately supported native release; do not copy these
-    x86_64 binaries there and assume they will work.
+    Sources: official OpenSSL GitHub release and Alpine CDN. Compilation uses
+    isolated musl/GCC built-in and host Linux UAPI headers, excluding glibc.
+    Static OpenSSL has no dynamic providers and seeds through getrandom. The
+    native compatibility probe must pass. WASI uses separately verified SDK/OpenSSL
+    inputs in CHAT-OPENSSL-MIGRATION.txt. Cryptographic algorithms stay fixed.
+
+    Inputs cache under .tools/. Version/source/flag changes require an OpenSSL
+    rebuild. Updates require upstream advisory review, every affected URL/hash,
+    native/WASI rebuilds, both browsers, cargo-deny, regenerated notices/sources,
+    and release recovery. Never waive advisories to pass. cargo-deny excludes C/OpenSSL.
+
+    Source downloads include first-party code, Cargo-vendored dependencies, and
+    unmodified OpenSSL, excluding development toolchain/sysroot inputs. Saved
+    images preserve tested runtime. ARM requires a separately supported native release.
 
 LOCAL MODES AND ORIGIN BINDING
 
@@ -98,36 +85,31 @@ LOCAL MODES AND ORIGIN BINDING
         https://CHAT_HOST/ with the configured HTTPS_PORT
         var/data/chat
 
-    These are distinct browser origins and require separate identity files. The
-    direct process and production deliberately use the same relative database
-    name on their respective machines. Do not switch an installation containing
-    valuable identities between direct development and production. Use a fresh
-    restored release directory for integration tests. Rebuild the release after
-    edits to refresh the packaged browser, server, sources, notices, and image.
+    Distinct origins require separate identity files. Direct development and
+    production share a relative database path on separate machines; do not switch
+    valuable installations between them. Integration tests need a fresh restored
+    release. Rebuild after edits to refresh browser, server, sources, notices, and image.
 
-    The single root .env holds public hostnames, ports, upstreams, backup settings,
-    SEARXNG_SECRET, and CHAT_SETUP_TOKEN. The example is public; actual .env is
-    ignored and never included in public releases or source downloads. Caddy keys
-    and chat databases are generated private runtime state under var/data.
-    Initialization preserves configured values and generates missing secrets.
+    One root .env holds hostnames, ports, upstreams, backups, SEARXNG_SECRET, and
+    CHAT_SETUP_TOKEN. Only the example is public; releases/source downloads exclude
+    actual .env. Caddy keys/chat databases stay under var/data. Initialization
+    preserves configured values and generates missing secrets.
 
 DEPLOY AND CREATE THE REAL OWNER FILE
 
-    Use the release upload/activation instructions in OPERATIONS.txt. Extract
-    the new prebuilt management binary into var/incoming/bootstrap and invoke
-    it with --root pointing at the current installation. Use the management
-    binary from that verified release so activation understands its service
-    schema. It verifies the archive and installs packaged chat artifacts before
-    starting services.
+    Follow OPERATIONS.txt. Extract the verified release's new management binary
+    into var/incoming/bootstrap; invoke with --root set to the current installation.
+    The new binary understands its release schema, verifies the archive, and
+    installs chat artifacts before startup.
     The host needs rootless Podman prerequisites, user linger, low-port permission,
     DNS A/AAAA records for CHAT_HOST and www.CHAT_HOST, and the normal 80/443
     firewall rules. Caddy obtains and renews public certificates automatically.
     Public certificate validation requires standard reachable ACME ports.
 
     The systemd user service runs ./bin/stack up --production at boot and
-    ./bin/stack down on stop. Podman restart policies restart failed containers.
-    Neither mechanism compiles code or requests a registry pull for a complete
-    release on the matching architecture. Check all four services after activation:
+    ./bin/stack down on stop. Podman restarts
+    failed containers. Complete matching-architecture releases need no compilation
+    or registry pull. Check all four services after activation:
 
         ./bin/stack status
 
@@ -136,57 +118,48 @@ DEPLOY AND CREATE THE REAL OWNER FILE
     The displayed limitations are CHAT-APPLICATION.txt. Chat has its own origin;
     the main website remains JavaScript-free. Its Message Me links lead to chat.
 
-    In the browser on the production HTTPS origin, choose OWNER SETUP. Read the
-    setup token from the production root .env locally; never publish it or send it
-    through chat. Choose a unique owner-file password, save the downloaded file,
-    reopen it, and unlock it. Store that file and password in KeePassXC and keep
-    a protected backup of the database. The setup token cannot replace this file.
-    Never copy a development owner file and silently change its pinned origin.
+    At the production HTTPS origin, choose OWNER SETUP. Read the root .env token
+    locally; never publish or send it through chat. Choose a unique password;
+    save, reopen, and unlock the downloaded owner file. Keep file/password in
+    KeePassXC with a protected database backup. The token cannot replace the file.
+    Never silently change a development file's pinned origin.
 
 BACKUP, RESTORE, AND KEY LOSS
 
     A complete encrypted application export:
         ./bin/stack backup --include-images
 
-    Download the .gpg and .sha256 files off the VPS. A backup on the same VPS is
-    vulnerable to loss of that VPS. Existing configured backup recipients apply.
-    This export includes the single .env, consistent SQLite snapshots for chat
-    and chat-local, Caddy certificate state, repositories, static binaries, WASM,
-    sources, and exact container images. SQLite uses its online backup API; chat
-    is left unpaused so a pending writer cannot block snapshot completion.
-    The database contains ciphertext and public keys, plus the metadata described
-    in CHAT-APPLICATION.txt. The owner private file and GnuPG secret key are not
-    server data; back them up separately.
+    Copy .gpg and .sha256 off the VPS; local backups cannot survive VPS loss.
+    Configured recipients apply. Export includes one .env, online SQLite snapshots
+    for chat/chat-local, Caddy certificates, repositories, static binaries, WASM,
+    sources, and exact images. Chat stays unpaused so pending writers can complete.
+    Database contents are ciphertext/public keys and CHAT-APPLICATION.txt metadata.
+    Owner private file and GnuPG secret key need separate backups.
 
     Restore to a new directory, verify, then explicitly start production mode:
         ./bin/stack restore /path/export.tar.gz.gpg /path/stack-restored
         cd /path/stack-restored
         ./bin/stack up --production
 
-    Restore defaults to local mode and changes container project names to avoid
-    accidentally replacing another installation. up --production selects the
-    production database and HTTPS origin again. Keep the same hostname/origin,
-    point DNS at the replacement host, and use unchanged owner/visitor files and
-    passwords. A new IP does not change an origin. A changed hostname or HTTPS
-    port does. Do not expose two restored copies simultaneously under one origin.
-    Server restart invalidates sessions; reopening identity files authenticates
-    again. Historical ciphertext and counters persist across restart and recovery.
+    Restore defaults to local mode with fresh project names, avoiding replacement
+    of another installation. up --production reselects production database/origin.
+    Keep hostname/origin, repoint DNS, and use unchanged identity files/passwords.
+    IP changes preserve origin; hostname/HTTPS-port changes do not. Never expose
+    two restored copies under one origin. Restart invalidates sessions; reopening
+    files authenticates again. Historical ciphertext/counters persist.
 
-    Losing the owner private file cannot be repaired by CHAT_SETUP_TOKEN. If its
-    backups are also lost, reset deliberately deletes every stored conversation
-    and message. It does not decrypt or recover anything. This backend operation
-    has no HTTP endpoint and requires filesystem/Podman access:
+    CHAT_SETUP_TOKEN cannot recover a lost private file. If backups are also lost,
+    reset deletes every conversation/message; it decrypts and recovers nothing.
+    Reset has no HTTP endpoint and requires filesystem/Podman access:
 
         ./bin/stack chat --owner-fingerprint
         ./bin/stack down
         ./bin/stack chat --reset-owner PASTE_CURRENT_OWNER_FINGERPRINT_HERE
         ./bin/stack up --production
 
-    A running server holds a filesystem lock; reset refuses until it stops. The
-    full fingerprint must match. Root .env and previous exports are preserved.
-    Create a new production owner file afterward. Old visitor files reject its
-    changed pinned owner key and need a new chat identity. A reset does not erase
-    copies already present in exports or external snapshots.
+    Reset requires a stopped server and matching full fingerprint. Root .env and
+    exports survive. Create a new production owner file; old visitor files reject
+    its changed key and need fresh identities. Exports/external snapshots are not erased.
 
 VERIFICATION