docs: shorten guides and map repository files

1 files changed, 70 insertions, 83 deletions

diff --git a/docs/TYPESCRIPT.txt b/docs/TYPESCRIPT.txt
index 7fbc5a4..7fa5125 100644
--- a/docs/TYPESCRIPT.txt
+++ b/docs/TYPESCRIPT.txt
@@ -15,81 +15,75 @@ along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 TYPESCRIPT BROWSER TOOLCHAIN
 
-    All first-party browser logic and browser automation are TypeScript.
-    Rust still implements cryptography, the API, backups, and deployment.
-    Browsers execute JavaScript generated by TypeScript; TypeScript adds
-    compile-time checks and does not replace validation of untrusted input.
+    First-party browser logic/automation use TypeScript. Rust handles crypto,
+    API, backups, deployment. Browsers run generated JavaScript; compile-time
+    types never replace validation of untrusted input.
 
 SOURCE LAYOUT
 
     crates/chat-server/web/app.ts
-        Interface, session state, history, downloads, and API validation.
+        Interface, session, history, downloads, API validation.
     crates/chat-server/web/worker.ts
-        One-shot cryptographic worker; its lifetime ends after each request.
+        One-shot crypto worker; ends after each request.
     crates/chat-crypto/browser/wasi.ts
-        Restricted browser WASI host for the unchanged Rust/OpenSSL module.
+        Restricted WASI host for unchanged Rust/OpenSSL module.
     crates/chat-crypto/browser/protocol.d.ts
-        Shared API and cryptographic request/response contracts. Declarations
-        emit no JavaScript and are checked for both browser environments.
+        Shared API/crypto request/response contracts. No emitted JavaScript;
+        checked in both browser environments.
     crates/chat-crypto/tests/browser.ts
-        Real WebAssembly compatibility, entropy, and capability tests.
+        Real WebAssembly compatibility, entropy, capability tests.
     crates/chat-server/tests/browser.ts
-        Complete browser chat and recovery tests, including GNU LibreJS.
+        Complete browser chat/recovery tests, including GNU LibreJS.
     crates/chat-server/tests/progress.ts
-        Download progress and failure tests, including GNU LibreJS.
+        Download progress/failure tests, including GNU LibreJS.
     tests/browser-support.ts
-        Checked fixture parsing and typed browser-automation helpers.
+        Checked fixture parsing, typed browser-automation helpers.
 
-    eslint.config.ts and tsconfig.tools.json supply the typed lint-tool checks.
-    src/app and crates/chat-server/src/app contain the private Rust CLI
-    implementations; their parser and runtime changes are recorded in LINTING.txt.
+    eslint.config.ts/tsconfig.tools.json provide typed lint-tool checks.
+    Private Rust CLIs: src/app and crates/chat-server/src/app. Parser/runtime
+    changes: LINTING.txt.
 
-    tsconfig.json supplies shared strict checks. The browser, worker, and
-    test configurations use separate DOM, WebWorker, and Node environments.
-    Production browser builds cannot accidentally rely on Node APIs.
-    strict, unchecked indexed access, exact optional properties, unused
-    declarations/parameters, implicit returns, switch fallthrough, implicit
-    overrides, and indexed-property access are checked. Type errors prevent
-    emission. No suppression directives or untyped escape hatches are used.
+    tsconfig.json supplies shared strict checks. Separate browser/worker/test
+    configs use DOM/WebWorker/Node environments, preventing accidental production
+    Node API use. Check strict, unchecked indexed access, exact optional properties,
+    unused declarations/parameters, implicit returns, switch fallthrough, implicit
+    overrides, indexed-property access. Type errors prevent emission.
+    No suppression directives or untyped escape hatches.
 
 DEVELOPMENT
 
-    Install Node >=22.18.0 and npm on the development machine. Root package.json
-    and package-lock.json pin TypeScript 7.0.2, Playwright 1.64.1, Node type
-    declarations, platform compiler packages, and their integrity hashes.
-    ESLint 10.14.0 and typescript-eslint 8.72.1 provide typed strict linting.
-    TypeScript 6.0.3 supplies their supported JavaScript API; the pinned native
-    TypeScript 7.0.2 alias remains the emitting compiler. Both check the sources.
-    LINTING.txt documents the advisory-driven minimatch override.
-    There are no npm application/runtime dependencies. TypeScript and
-    Playwright use the Apache License, Version 2.0; Node declarations and
-    undici-types use the Expat License. Original notices remain in the
-    installed packages. SPDX identifiers retain their required spelling.
+    Development needs Node >=22.18.0/npm. Root package.json/package-lock.json pin
+    TypeScript 7.0.2, Playwright 1.64.1, Node declarations, platform compilers,
+    integrity hashes. ESLint 10.14.0/typescript-eslint 8.72.1 supply typed strict
+    linting. TypeScript 6.0.3 supplies their supported JavaScript API; native
+    TypeScript 7.0.2 alias emits. Both check sources. LINTING.txt explains the
+    advisory-driven minimatch override. No npm application/runtime dependencies.
+    TypeScript/Playwright: Apache License, Version 2.0. Node declarations/
+    undici-types: Expat License. Installed packages retain original notices;
+    machine SPDX spelling stays unchanged.
 
-    Build and check all TypeScript, including browser tests:
+    Build/check all TypeScript, including browser tests:
 
         npm run build
 
-    infra/chat/build-typescript.sh installs the locked development packages
-    with lifecycle scripts disabled, checks browser/worker/test/tool configurations,
-    typed ESLint, both compiler versions, and npm advisories, then
-    emits JavaScript under var/build/typescript. The npm cache stays under
-    .tools/npm-cache. node_modules and generated outputs are ignored by Git.
-    Generated scripts are readable and unminified; no bundler is needed.
+    infra/chat/build-typescript.sh installs locked dev packages without lifecycle
+    scripts, checks browser/worker/test/tool configs, typed ESLint, both compilers,
+    npm advisories; emits JavaScript under var/build/typescript. npm cache:
+    .tools/npm-cache. Git ignores node_modules/generated output. Scripts stay
+    readable/unminified; no bundler needed.
 
-    cargo stack check includes this build, then the strict Rust checks and
-    cargo-about license generation. cargo stack release builds TypeScript
-    before packaging the complete production release.
+    cargo stack check runs this build, strict Rust checks, cargo-about generation.
+    cargo stack release builds TypeScript before packaging production artifacts.
 
-    Recheck without reinstalling packages after npm run build:
+    Recheck after npm run build without reinstalling:
 
         npm run check
 
-    Fetch the pinned Playwright browser versions once:
+    Fetch pinned Playwright browsers once:
 
         PLAYWRIGHT_BROWSERS_PATH="$PWD/.tools/browsers" node_modules/.bin/playwright install chromium firefox
 
-    After building the native chat server and WASI module:
+    Build native chat server/WASI module, then run:
 
         PLAYWRIGHT_BROWSERS_PATH="$PWD/.tools/browsers" npm run test:crypto
         PLAYWRIGHT_BROWSERS_PATH="$PWD/.tools/browsers" npm run test:chat
@@ -97,42 +91,35 @@ DEVELOPMENT
         CHAT_LIBREJS=1 PLAYWRIGHT_BROWSERS_PATH="$PWD/.tools/browsers" npm run test:chat
         CHAT_LIBREJS=1 PLAYWRIGHT_BROWSERS_PATH="$PWD/.tools/browsers" npm run test:progress
 
-    LibreJS variants require the signed Mozilla extension at
-    .tools/librejs.xpi as documented in CHAT-APPLICATION.txt. The complete
-    chat test proves LibreJS is active and rejects an unlicensed control.
-    Run chat variants sequentially because they share the default test port.
-    npm audit checks development dependencies as part of npm run check and the
-    Cargo check/release path. It does not audit Rust, browser-delivered code, or
-    containers; cargo-deny remains the separate strict Rust dependency audit.
+    LibreJS variants need signed Mozilla extension .tools/librejs.xpi; see
+    CHAT-APPLICATION.txt. Complete chat test proves LibreJS active and rejects an
+    unlicensed control. Run chat variants sequentially; they share default port.
+    npm audit checks dev dependencies in npm run check/Cargo check/release;
+    it does not audit Rust, delivered browser code, or containers. cargo-deny
+    remains the separate strict Rust dependency audit.
 
 RELEASES, SOURCE, AND LIBREJS
 
-    Generated app.js, worker.js, and wasi.mjs keep their existing public URLs.
-    They preserve the AGPL headers and recognized @license/@license-end
-    markers. The JavaScript license table links each generated file to its
-    complete corresponding TypeScript and Rust source archive. Classic scripts
-    and importScripts remain in use for LibreJS compatibility; the migration
-    introduces no runtime module loader or third-party browser scripts.
-
-    Local native-server tests serve generated files from var/build/typescript.
-    The release packages those files into bin/chat/web and bin/chat/wasi.mjs.
-    Containers serve the packaged files. HTML and CSS are copied explicitly,
-    so TypeScript source files are not substituted for executable JavaScript.
-    /SOURCE.tar.gz includes TypeScript, shared declarations, all compiler
-    configurations, the npm lock, tests and build scripts, together with the
-    existing Cargo-vendored dependencies and verified OpenSSL source archive.
-    Node/npm/TypeScript are general-purpose development tools, documented and
-    pinned here; their installed copies and downloaded browsers are excluded.
-
-    Source exports, releases, and backups carry the root npm manifests and
-    TypeScript configurations. Release activation and restored prebuilt images
-    need no Node, npm, TypeScript, or Rust installation on the destination.
-    They retain the single private root .env and existing persistent data.
-    The source archive excludes that .env, credentials, runtime databases,
-    exports, .git, node_modules, and build/cache directories. The root
-    .env.example remains public. No additional environment file is introduced.
-
-    Test the actual generated JavaScript after any compiler upgrade. Static
-    types cannot guarantee privacy, security, or LibreJS recognition. Browser
-    storage restrictions, protocol validation, and algorithm choices continue
-    to be enforced by the existing runtime and Rust implementation.
+    Generated app.js/worker.js/wasi.mjs retain public URLs, AGPL headers,
+    recognized @license/@license-end markers. JavaScript license table links
+    each file to complete corresponding TypeScript/Rust source archive.
+    Classic scripts/importScripts preserve LibreJS compatibility. No runtime
+    module loader or third-party browser scripts added.
+
+    Local native-server tests serve var/build/typescript. Release packages files
+    into bin/chat/web and bin/chat/wasi.mjs; containers serve packaged files.
+    Copy HTML/CSS explicitly; never substitute TypeScript for executable JS.
+    /SOURCE.tar.gz contains TypeScript, shared declarations, every compiler config,
+    npm lock, tests/build scripts, Cargo-vendored dependencies, verified OpenSSL
+    archive. Node/npm/TypeScript are general-purpose development tools pinned and
+    documented here. Exclude installed copies/downloaded browsers.
+
+    Source exports/releases/backups carry root npm manifests/TypeScript configs.
+    Activation/restored prebuilt images need no destination Node/npm/TypeScript/
+    Rust. Preserve single private root .env and persistent data. Source archive
+    excludes .env, credentials, runtime DBs, exports, .git, node_modules, build/cache
+    directories. Root .env.example remains public; no extra environment file.
+
+    Test generated JavaScript after every compiler upgrade. Static types cannot
+    guarantee privacy, security, or LibreJS recognition. Existing runtime/Rust
+    still enforce browser storage restrictions, protocol validation, algorithms.