docs: shorten guides and map repository filesHEADmain

1 files changed, 66 insertions, 75 deletions

diff --git a/docs/POLICY.txt b/docs/POLICY.txt
index 4c6c6d3..dea595b 100644
--- a/docs/POLICY.txt
+++ b/docs/POLICY.txt
@@ -17,89 +17,80 @@ PROJECT CONVENTIONS
 
     License: GNU Affero General Public License, version 3 or later.
     SPDX identifier: AGPL-3.0-or-later.
-    Copyright holder: Doan Luu Duc Tai <doan@luuduct.ai>, 2026.
-
-    Every nontrivial first-party source, configuration, template, and prose
-    file carries the AGPL copyright and permission header. LICENSE is the
-    unmodified license text. Binary public keys and empty WKD policy files
-    retain their protocol format. Generated Cargo.lock retains Cargo's own
-    metadata as well as the project notice. JSON npm manifests carry the legal
-    notice in a top-level // metadata field; compiler JSONC files use the usual
-    header syntax. Keep generated JavaScript legal markers when compiling.
-
-    Do not add explanatory source comments. Express intent through structure
-    and names. Legal headers are the required exception. Use .txt for prose
-    documentation. The generated HTML license page is an explicit exception.
-    Rust documentation attributes provide crate metadata without comments.
-
-    Keep deployment overrides and configured secrets in the single root .env.
-    Never commit .env or var/.
-    Only the root .env.example is published; environment variants and nested
-    examples are ignored. The commented .env.example publishes supported public
-    defaults and private placeholders. Public GPG keys, paths, templates, shared
-    configuration logic, and source belong in Git. Actual public hostnames remain
-    visible in rendered pages; .env centralization is not an access boundary.
-    TLS account/certificate private keys, databases, and other generated
-    private state are persistent data in var/data, not .env configuration.
-    The GPG secret key and revocation certificate remain outside this project.
+    Copyright holder/commit author: Doan Luu Duc Tai <doan@luuduct.ai>, 2026.
+    Sign commits with RSA-2048 key:
+        3346AA3150F8F16828BB0D14F8C66DF77AFECEA6
+
+    Every nontrivial first-party source/config/template/prose file needs the AGPL
+    copyright and permission header. LICENSE stays unmodified. Binary public keys
+    and empty WKD policy files retain protocol format. Generated Cargo.lock keeps
+    Cargo metadata plus project notice. JSON npm manifests use top-level // legal
+    metadata; compiler JSONC uses its usual header syntax. Preserve generated
+    JavaScript legal markers.
+
+    No explanatory source comments. Express intent through names/structure.
+    Required legal headers are the exception. Prose uses .txt; generated HTML
+    license page is an explicit exception. Rust doc attributes supply crate
+    metadata without comments.
+
+    One root .env holds deployment overrides/configured secrets. Never commit
+    .env or var/. Publish only root .env.example; ignore variants/nested examples.
+    Its comments document public defaults/private placeholders. Public GPG keys,
+    paths, templates, shared config logic, and source belong in Git. Hostnames
+    stay visible in rendered pages; .env centralization is no access boundary.
+    TLS account/certificate private keys, databases, and generated private state
+    live under var/data, not .env. Keep GPG secret key/revocation certificate
+    outside the project.
 
 STRICTNESS
 
-    All enabled Clippy groups and individual rules are forbidden, with no
-    blanket allow entries. Rust and Rustdoc checks use forbid wherever supported
-    by generated code. Three Rust settings remain deny for pinned Serde derives;
-    their unaffected members are independently forbidden. First-party lint
-    allowances are forbidden. See LINTING.txt for tested workarounds, generated
-    attribute evidence, and the narrow duplicate-dependency configuration.
-    Private app namespaces retain narrow internal visibility while both
-    redundant_pub_crate and unreachable_pub are enforced.
-
-    cargo-deny rejects duplicate crate versions, wildcard requirements, unknown
-    registries, unknown Git sources, and yanked versions. The chat prototype has
-    exact-version duplicate exceptions reviewed in CHAT-OPENSSL-MIGRATION.txt.
-    No RustSec advisories are ignored. First-party AGPL and required dependency
-    license allowances are scoped to their individual packages.
-    The dependency allowlist retains the requested permissive licenses and
-    Zlib; an unused allowance may produce an informational audit warning.
-
-    Browser logic and automation use strict TypeScript configurations with
-    separate browser/worker/Node environments and checked untrusted responses.
-    npm dependencies are exact, development-only, integrity-locked, and installed
-    with lifecycle scripts disabled. Typed ESLint forbids unsafe any/assertions,
-    unchecked promises, and suppression directives. Both supported compiler APIs
-    and npm advisories are checked. See TYPESCRIPT.txt and LINTING.txt.
-
-    Human license names follow https://www.gnu.org/licenses/license-list.html.
-    In particular, display Expat License for SPDX MIT. Do not alter original
-    copyright notices, legal texts, crate metadata, or machine SPDX identifiers.
-    cargo-about covers Rust dependencies. Supporting container applications
-    and their operating-system packages carry additional upstream licenses.
+    Forbid every enabled Clippy group/individual rule; no blanket allows.
+    Rust/Rustdoc use forbid where generated code supports it. Three Rust settings
+    stay deny for pinned Serde derives; unaffected members remain independently
+    forbidden. No first-party lint allowances. LINTING.txt records tested
+    workarounds, generated-attribute evidence, and narrow duplicate exceptions.
+    Private app namespaces keep narrow visibility while redundant_pub_crate and
+    unreachable_pub both remain enforced.
+
+    cargo-deny rejects duplicate versions, wildcard requirements, unknown
+    registries/Git sources, and yanked versions. Chat has exact-version duplicate
+    exceptions reviewed in CHAT-OPENSSL-MIGRATION.txt. Ignore no RustSec advisory.
+    Scope first-party AGPL/required dependency license allowances per package.
+    Allowlist retains requested permissive licenses and Zlib; unused allowances
+    may produce informational audit warnings.
+
+    Strict TypeScript separates browser/worker/Node environments and validates
+    untrusted responses. npm dependencies stay exact, development-only,
+    integrity-locked; disable installation lifecycle scripts. Typed ESLint rejects
+    unsafe any/assertions, unchecked promises, and suppression directives. Check
+    both supported compiler APIs and npm advisories. See TYPESCRIPT.txt/LINTING.txt.
+
+    Human license names follow https://www.gnu.org/licenses/license-list.html:
+    display Expat License for SPDX MIT. Preserve original copyright, legal text,
+    crate metadata, and machine SPDX identifiers. cargo-about covers Rust.
+    Container applications/OS packages retain their additional upstream licenses.
 
 PORTABILITY
 
-    All first-party project files and state live below stack/. Standard host
-    integration consists of packages, subordinate UID/GID allocations, one
-    low-port sysctl setting, user linger, and a systemd user-service link.
-    Host SSH keys, firewall policy, accounts, and disks are host administration,
-    not application export contents.
+    All first-party files/state live below stack/. Standard host integration:
+    packages, subordinate UID/GID allocations, one low-port sysctl, user linger,
+    systemd user-service link. Host SSH keys, firewall policy, accounts, and disks
+    are host administration, excluded from application exports.
 
-    Releases contain static x86_64 Linux management/chat commands, the WASM
-    browser crypto module, exact corresponding sources, and native
-    linux/amd64 container images. They are portable across compatible x86_64
-    Linux machines. An ARM machine needs a native release build; the command
-    rejects mismatched production images. Development mode may fetch/build
-    native images on an architecture mismatch. Container source and Rust
-    source are public so new targets can be added without restoring an OS.
+    Releases include static x86_64 Linux management/chat commands, WASM browser
+    crypto, exact corresponding sources, native linux/amd64 container images.
+    Compatible x86_64 Linux hosts can run them. ARM needs a native release build;
+    production rejects mismatched images. Development may fetch/build native
+    images on architecture mismatch. Public container/Rust sources permit new
+    targets without restoring an OS.
 
-    Generated third-party legal texts retain upstream whitespace and line endings.
-    .gitattributes exempts only THIRD-PARTY-LICENSES.html from whitespace errors;
-    first-party source checks remain strict. Workspace audits include every member.
+    Preserve upstream whitespace/line endings in generated third-party legal
+    texts. .gitattributes exempts only THIRD-PARTY-LICENSES.html from whitespace
+    errors. First-party checks stay strict; workspace audits cover every member.
 
 STATIC ASSET CACHING
 
-    Main-site stylesheet links include the SHA-256 of web/styles.css as a query
-    version. Update both website templates when CSS changes. The render test
-    checks that the published URL matches the current stylesheet, preventing
-    old cached CSS from being paired with new markup. Tooltip text carries the
-    native hidden attribute as well as CSS visibility rules, so a stylesheet
-    failure cannot expose it as ordinary page text.
+    Main-site stylesheet URLs include web/styles.css SHA-256 as query version.
+    Update both website templates after CSS changes. Render test checks the
+    published hash, preventing stale CSS/new markup pairs. Tooltip text uses
+    native hidden plus CSS visibility, so stylesheet failure cannot expose it.