docs: shorten guides and map repository filesHEADmain

1 files changed, 175 insertions, 0 deletions

diff --git a/docs/MAP.txt b/docs/MAP.txt
new file mode 100644
index 0000000..6f5e13d
--- /dev/null
+++ b/docs/MAP.txt
@@ -0,0 +1,175 @@
+Copyright (C) 2026 Doan Luu Duc Tai <doan@luuduct.ai>
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+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/>.
+
+FILE MAP
+
+    Public tree: every tracked file, including this map.
+    Static inventory; update when public paths change. Root: stack/.
+    Private/generated trees below list roles only; contents stay unlisted.
+
+stack/  Personal service source, build recipes and recovery tooling.
+|-- .cargo/  Cargo command aliases.
+|   `-- config.toml  Cargo stack alias.
+|-- crates/  Workspace application/configuration crates.
+|   |-- chat-crypto/  Fixed-suite Rust and browser cryptography.
+|   |   |-- browser/  Browser crypto types and WASI adapter.
+|   |   |   |-- protocol.d.ts  Shared typed API, crypto, worker, WASI message contracts.
+|   |   |   `-- wasi.ts  Browser WASI host: memory, I/O, entropy, command execution.
+|   |   |-- src/  Rust crypto library and executable.
+|   |   |   |-- application.rs  Protected identities, authentication proofs, message encryption/decryption.
+|   |   |   |-- lib.rs  Public crypto API and fixed-suite compatibility round trip.
+|   |   |   `-- main.rs  Native/WASI executable: request input and crypto result output.
+|   |   |-- tests/  Real-browser crypto compatibility tests.
+|   |   |   `-- browser.ts  Real-browser crypto probe, entropy-failure and network-isolation checks.
+|   |   |-- Cargo.toml  Crypto library/probe targets, fixed backend features, dependencies.
+|   |   `-- README.txt  Crypto suite, native/WASI build, compatibility checks.
+|   |-- chat-server/  Private-chat backend and browser client.
+|   |   |-- src/  Rust HTTP server and maintenance entry.
+|   |   |   |-- app/  Server argument, HTTP, service and storage modules.
+|   |   |   |   |-- cli.rs  Server flags, listener defaults, maintenance argument conflicts.
+|   |   |   |   |-- http.rs  HTTP routes, packaged assets, response security headers.
+|   |   |   |   |-- maintenance.rs  Server file lock, owner fingerprint, destructive owner reset.
+|   |   |   |   |-- service.rs  Authentication challenges/sessions, authorization, chat operations.
+|   |   |   |   `-- store.rs  SQLite owner metadata, conversations, ciphertext history persistence.
+|   |   |   |-- app.rs  Server initialization, origin/listener checks, command dispatch.
+|   |   |   `-- main.rs  Chat server executable entry point.
+|   |   |-- tests/  Chat browser integration and loading-state tests.
+|   |   |   |-- browser.ts  Chat browser flows, owner/visitor access, packaged backup/restore.
+|   |   |   `-- progress.ts  Crypto-download progress, unknown length, failure and LibreJS checks.
+|   |   |-- web/  Chat markup, styling and TypeScript client.
+|   |   |   |-- app.ts  Chat browser UI, credentials, API calls, encrypted conversations.
+|   |   |   |-- index.html  Chat page markup and public-origin template.
+|   |   |   |-- javascript.html  Browser JavaScript license/source listing.
+|   |   |   |-- style.css  Chat page layout, controls, status and conversation styling.
+|   |   |   `-- worker.ts  One-operation crypto worker; returns result/error, then closes.
+|   |   |-- Cargo.toml  Chat HTTP server dependencies and workspace lint inheritance.
+|   |   `-- README.txt  Server purpose, local startup, browser-test entry.
+|   |-- config/  Shared environment/configuration crate.
+|   |   |-- src/  Validated configuration and public-rendering implementation.
+|   |   |   `-- lib.rs  Root .env parsing/validation, defaults, public-only template values.
+|   |   |-- Cargo.toml  Shared configuration crate dependencies and lint inheritance.
+|   |   `-- README.txt  Configuration crate responsibilities and public rendering boundary.
+|   `-- README.txt  Workspace crate roles and shared policy.
+|-- docs/  Plaintext setup, policy, security and recovery guides.
+|   |-- CHAT-APPLICATION.txt  Chat setup, protected files, user flows, recovery, security limits.
+|   |-- CHAT-OPENSSL-MIGRATION.txt  OpenSSL crypto migration evidence, dependencies, reviewed exceptions.
+|   |-- CHAT-PRODUCTION.txt  Chat release packaging, HTTPS activation, owner setup, production recovery.
+|   |-- CONFIGURATION.txt  Supported root settings, validation, public/private state boundaries.
+|   |-- LINTING.txt  Strict Rust/browser checks, generated-code limits, justified exceptions.
+|   |-- MAP.txt  This public-file tree and private/runtime directory roles.
+|   |-- OPERATIONS.txt  Stack development, encrypted backup/restore, host setup, deployment.
+|   |-- POLICY.txt  License/header, source-comment, configuration, strictness and portability rules.
+|   `-- TYPESCRIPT.txt  Typed browser/worker/test builds, ESLint policy, compiler/test commands.
+|-- infra/  Service definitions, host integration and build recipes.
+|   |-- chat/  Native/WASI/TypeScript/source build scripts.
+|   |   |-- build-browser.sh  Link Rust/OpenSSL browser crypto command into WASI WebAssembly.
+|   |   |-- build-native.sh  Build static musl management/server commands and native crypto probe.
+|   |   |-- build-openssl-wasi.sh  Fetch verified SDK/OpenSSL sources; build browser crypto library.
+|   |   |-- build-source.sh  Archive corresponding source, vendored Rust crates and OpenSSL source.
+|   |   |-- build-typescript.sh  Install locked dev dependencies; run typed checks and emit browser JS.
+|   |   `-- openssl-wasi.conf  OpenSSL build target settings for WASI.
+|   |-- containers/  Container build contexts.
+|   |   |-- cgit/  cgit image and its nginx/FastCGI process configuration.
+|   |   |   |-- .containerignore  Restrict cgit build context to required container files.
+|   |   |   |-- Containerfile  Build pinned Debian cgit/nginx/FastCGI/supervisor image.
+|   |   |   |-- cgitrc  cgit repository listing, paths and presentation template.
+|   |   |   |-- entrypoint.sh  Prepare cgit container runtime and start its supervisor.
+|   |   |   |-- nginx.conf  Serve cgit HTTP/static assets; route CGI through fcgiwrap.
+|   |   |   `-- supervisord.conf  Run nginx and fcgiwrap inside the cgit container.
+|   |   `-- chat/  Prebuilt chat image recipe.
+|   |       `-- Containerfile  Package prebuilt static chat server and web/crypto assets.
+|   |-- searxng/  Search service configuration.
+|   |   `-- settings.yml  SearXNG defaults: private instance, rate limiting, HTML search.
+|   |-- Caddyfile  Production domain routing, HTTPS, WKD and service reverse proxies.
+|   |-- Caddyfile.local  Loopback development routing without public certificate requests.
+|   |-- host-setup.sh  Debian ops-user Podman packages, UID/GID checks, low ports and linger.
+|   |-- podman.conf  Legacy Podman override selecting slirp4netns rootless networking.
+|   |-- services.toml  Service images, mounts, environment allowlists, security and health probes.
+|   `-- stack.service  Systemd user boot unit for ~/stack start/stop.
+|-- src/  Management executable source.
+|   |-- app/  Management command implementation modules.
+|   |   |-- archive.rs  Consistent snapshots, encrypted exports and validated directory restores.
+|   |   |-- chat.rs  Chat build/package artifacts, container settings and owner administration.
+|   |   |-- cli.rs  Management subcommands, flags and argument validation.
+|   |   |-- files.rs  Safe filesystem/archive operations, manifests and hashes.
+|   |   |-- images.rs  Export/import exact container images; enforce platform and content locks.
+|   |   |-- process.rs  Run child processes; capture output and report failures/status.
+|   |   |-- project.rs  Discover/lock project; settings, Podman commands, service lifecycle.
+|   |   |-- release.rs  Build checked release archives; validate/install production artifacts.
+|   |   `-- render.rs  Render per-mode Caddy, website and cgit configuration.
+|   |-- app.rs  Management command dispatch, check pipeline and license generation.
+|   `-- main.rs  Management executable entry point.
+|-- tests/  Shared first-party browser-test helpers.
+|   `-- browser-support.ts  Shared browser-test response validators, server and browser cleanup helpers.
+|-- web/  Main-site template, styles, licenses and public key discovery.
+|   |-- .well-known/  Standard public discovery endpoints.
+|   |   `-- openpgpkey/  WKD public-key discovery tree.
+|   |       |-- hu/  Direct WKD hashed-user key files.
+|   |       |   `-- t76q8xqkeassgy1kr38re1ppj6cpc1dp  Owner public key for direct WKD lookup.
+|   |       |-- luuduct.ai/  Advanced WKD namespace for luuduct.ai.
+|   |       |   |-- hu/  Advanced WKD hashed-user key files.
+|   |       |   |   `-- t76q8xqkeassgy1kr38re1ppj6cpc1dp  Same owner public key for advanced luuduct.ai WKD lookup.
+|   |       |   `-- policy  Advanced WKD policy marker for luuduct.ai.
+|   |       `-- policy  Direct WKD policy marker.
+|   |-- THIRD-PARTY-LICENSES.html  Generated Rust dependency attribution and full license texts.
+|   |-- index.html  Main-site public links, identity and service-origin template.
+|   `-- styles.css  Main-site visual layout, links and tooltips.
+|-- .env.example  Public settings template; private-value placeholders.
+|-- .gitattributes  Whitespace handling for generated third-party license HTML.
+|-- .gitignore  Exclude secrets, runtime state, dependencies, build output.
+|-- Cargo.lock  Exact Rust dependency versions and source checksums.
+|-- Cargo.toml  Management binary, workspace members, dependencies, strict lints.
+|-- LICENSE  Unmodified GNU AGPLv3 license text; sources allow later versions.
+|-- README.txt  Project entry: setup, commands, checks, documentation links.
+|-- about.hbs  HTML template for generated Rust dependency licenses.
+|-- about.toml  License-page acceptance list and private-package handling.
+|-- clippy.toml  Reviewed duplicate-crate exceptions for Clippy.
+|-- deny.toml  Dependency advisory, license, source and duplicate-version policy.
+|-- eslint.config.ts  Typed ESLint rules and per-environment file scopes.
+|-- package-lock.json  Exact npm dev dependency versions, integrity and dependency graph.
+|-- package.json  Browser tooling dependencies and npm check/build/test commands.
+|-- rust-toolchain.toml  Pinned Rust version, formatting/lint components and target triples.
+|-- tsconfig.browser.json  Browser main-thread and WASI-host compiler scope.
+|-- tsconfig.json  Shared strict TypeScript compiler options.
+|-- tsconfig.tests.json  Node browser-automation compiler scope.
+|-- tsconfig.tools.json  Node ESLint configuration compiler scope.
+`-- tsconfig.worker.json  Web-worker compiler scope, separate from DOM globals.
+
+PRIVATE AND GENERATED PATHS — NOT PUBLIC SOURCE
+
+    .env                 Sole private root configuration; never commit.
+    .git/                Local Git objects, refs, hooks and repository settings.
+    .tools/              Downloaded toolchains, build tools, sources and caches.
+    bin/                 Prebuilt management/chat commands and packaged chat assets.
+    dist/                Locally built release tarballs and checksum files.
+    node_modules/        Locked npm development dependencies; recreated by npm ci.
+    target/              Cargo build output, WASM targets and generated rustdoc.
+    var/                 Private/generated project state; excluded from Git.
+      backups/           Imported backup archives and recovery test destinations.
+      build/             Generated TypeScript, source/vendor bundles and build work.
+      data/              Persistent application databases, TLS keys and Git repos.
+        caddy/           ACME account/certificate keys, Caddy data/configuration.
+        chat/            Production chat database: owner identity and ciphertext.
+        chat-local/      Isolated local chat database and server state.
+        repos/           Served bare Git repositories; separate from root .git/.
+        searxng/         Runtime search configuration and persistent service files.
+      exports/           Encrypted application backups and checksum files.
+      incoming/          Copied release archives and temporary deployment bootstrap.
+      podman/            Recreated container storage/run state; never transfer as backup.
+      graphify/          Public-source graph index, visual map and extraction artifacts.
+
+    Other var/ paths may hold generated fixtures or temporary work. This map does
+    not enumerate private files. Backups must keep .env and var/data; public Git
+    alone cannot recover services. See OPERATIONS.txt.