docs: shorten guides and map repository files

1 files changed, 74 insertions, 82 deletions

diff --git a/docs/CONFIGURATION.txt b/docs/CONFIGURATION.txt
index fc18c41..f0f8457 100644
--- a/docs/CONFIGURATION.txt
+++ b/docs/CONFIGURATION.txt
@@ -15,137 +15,129 @@ along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 CENTRAL CONFIGURATION
 
-    Each installation has one root .env for deployment settings and secrets.
-    The published .env.example documents every supported setting with public
-    defaults, private placeholders, and comments. Hostnames are public information;
-    this arrangement centralizes configuration, not secrecy or access control.
-    Public values remain visible in generated pages, DNS, certificates, and URLs.
-
-    Existing installations keep their configured secrets and settings. Missing
-    public defaults are appended to the same .env by cargo stack config, service
-    initialization, or chat initialization. No second environment file is created.
-    The example is also the shared Rust configuration library's default source,
-    so missing public settings remain compatible with older exports.
+    One root .env holds each installation's deployment settings and secrets.
+    Public .env.example documents every supported key, public default, private
+    placeholder, and comment. Hostnames remain public in generated pages, DNS,
+    certificates, and URLs. Centralization is not secrecy or access control.
+
+    cargo stack config, service initialization, and chat initialization preserve
+    existing settings/secrets and append missing public defaults to the same .env.
+    No second environment file. The shared Rust configuration library also reads
+    defaults from .env.example, keeping older exports compatible.
 
 PUBLIC SETTINGS
 
     BASE_DOMAIN
-        Root web/WKD domain. www aliases are derived from each configured host.
+        Root web/WKD domain. Derive www aliases from each configured host.
 
     SITE_HOST, GIT_HOST, SEARCH_HOST, WKD_HOST, CHAT_HOST
-        Fully qualified DNS names without schemes, paths, or ports. These
-        configure production HTTPS routes and their canonical www redirects.
-        CHAT_HOST also selects the exact trusted external chat origin.
+        Fully qualified DNS names; no scheme, path, or port. Set production
+        HTTPS routes and canonical www redirects. CHAT_HOST also selects the
+        exact trusted external chat origin.
 
     CHAT_LOCAL_HOST
-        Dedicated development gateway hostname ending in .localhost. Default:
+        Development gateway hostname ending in .localhost. Default:
         chat.localhost. Browser identity files bind to this origin and local port.
 
     WEB_BIND
-        Production host publish address. Default :: serves IPv4 and IPv6. Use
-        127.0.0.1 for isolated staging; development mode always uses loopback.
+        Production publish address. Default :: serves IPv4/IPv6. Use 127.0.0.1
+        for isolated staging. Development always binds loopback.
 
     HTTP_PORT, HTTPS_PORT
-        Production Caddy listener and Podman published ports. HTTPS also publishes
-        UDP for HTTP/3. Defaults are 80 and 443. Generated HTTPS links include a
-        nonstandard HTTPS port when configured. Ordinary public certificate
-        validation still needs the CA's standard external validation ports or an
-        appropriate alternative certificate/routing arrangement. Setting ports
-        alone does not configure DNS, firewall rules, or external port forwarding.
+        Caddy listeners and Podman published ports; defaults 80/443. HTTPS also
+        publishes UDP for HTTP/3. Generated links include nonstandard HTTPS ports.
+        Public certificate validation still needs standard external CA validation
+        ports or alternative certificate/routing arrangements. Port settings do
+        not configure DNS, firewall rules, or external forwarding.
 
     LOCAL_HTTP_PORT
-        Local Caddy HTTP port on 127.0.0.1. HTTPS host port is this value plus one.
-        Local Caddy still listens on container ports 80/443. --port overrides the
-        local port for that invocation. Existing installation/project names and
-        image state remain in var/state.json; an explicit .env local port takes
-        precedence over the previously saved port.
+        Local HTTP on 127.0.0.1; host HTTPS port is this value plus one. Caddy
+        still listens on container ports 80/443. --port overrides one invocation.
+        var/state.json retains installation/project names and image state.
+        An explicit .env local port overrides the saved port.
 
     CGIT_UPSTREAM, SEARXNG_UPSTREAM, CHAT_UPSTREAM
-        Proxy connection targets such as cgit:8080, searxng:8080, and chat:8080. These are
-        addresses, not upstream bind settings. The bundled images' internal 8080
-        listeners and health checks remain image contracts. Changing a target
-        to another host/port requires an actual service at that address.
+        Proxy targets, e.g. cgit:8080, searxng:8080, chat:8080. Not bind settings.
+        Bundled internal 8080 listeners and health checks remain image contracts.
+        A changed target needs an actual service at that host/port.
 
     CHAT_BIND, CHAT_ORIGIN
         Direct development socket and exact browser origin. Defaults:
-        127.0.0.1:9080 and http://127.0.0.1:9080. Direct development requires
-        loopback and an exact HTTP origin match. --bind overrides CHAT_BIND.
-        The container binds privately to 0.0.0.0:8080; its trusted origin comes
-        from CHAT_HOST/HTTPS_PORT or CHAT_LOCAL_HOST/LOCAL_HTTP_PORT instead.
-        Identity files pin their origin; editing these values does not migrate
-        encrypted identities or grant access on another origin.
+        127.0.0.1:9080 and http://127.0.0.1:9080. Require loopback and an exact
+        HTTP origin match. --bind overrides CHAT_BIND. Containers bind privately
+        to 0.0.0.0:8080; trusted origin comes from CHAT_HOST/HTTPS_PORT or
+        CHAT_LOCAL_HOST/LOCAL_HTTP_PORT. Identity files pin their origin.
+        Editing these settings neither migrates encrypted identities nor grants
+        access on another origin.
 
     BACKUP_RECIPIENT, BACKUP_PUBLIC_KEY
-        Public OpenPGP fingerprint and project-relative public key path used for
-        encrypted exports. --recipient and --key override them. The secret GnuPG
-        key and revocation certificate remain outside the project.
+        Public OpenPGP fingerprint and project-relative public key path for
+        encrypted exports. --recipient/--key override them. Keep the secret
+        GnuPG key and revocation certificate outside the project.
 
 PRIVATE SETTINGS
 
     SEARXNG_SECRET
-        Generated on first stack initialization. Existing values are preserved.
+        Generated at first stack initialization; existing values preserved.
 
     CHAT_SETUP_TOKEN
-        Generated by chat initialization or first stack startup. Used only to authorize first owner
-        registration, including a fresh registration after an explicit backend
-        reset. It cannot recover a lost owner private key.
+        Generated by chat initialization or first startup. Authorizes only
+        first owner registration, including after an explicit backend reset.
+        Cannot recover a lost owner private key.
 
 RENDER AND APPLY
 
-    Edit .env locally. Never commit or publish it. Inspect the commented example
-    for exact keys. Hostnames, ports, socket addresses, fingerprints, and paths
-    are validated before use. Diagnostic formatting never dumps the config map.
-    Invalid environment-file syntax is reported without echoing its raw contents.
+    Edit .env locally; never commit or publish it. See .env.example for exact
+    keys. Validate hostnames, ports, sockets, fingerprints, and paths before use.
+    Diagnostics never dump the config map or echo invalid .env contents.
 
     Render public deployment files without starting services:
 
         cargo stack config
         cargo stack config --production
 
-    Outputs are var/local/ or var/production/:
+    Output under var/local/ or var/production/:
 
         Caddyfile
         cgitrc
         web/
 
-    infra/Caddyfile, infra/Caddyfile.local, infra/containers/cgit/cgitrc, and the
-    first-party website HTML are templates using {{PUBLIC_KEY}} placeholders.
-    Do not run Caddy directly on an unrendered template. Podman mounts the generated
-    files. Public host/origin changes reach Caddy routes, www redirects, website
-    links, the cgit clone prefix, and the chat page's navigation. Local rendering
-    uses /git and /search paths and http://CHAT_LOCAL_HOST:LOCAL_HTTP_PORT for chat.
+    Templates use {{PUBLIC_KEY}} placeholders: infra/Caddyfile,
+    infra/Caddyfile.local, infra/containers/cgit/cgitrc, first-party website HTML.
+    Never run Caddy on unrendered templates. Podman mounts generated files.
+    Public host/origin changes reach routes, www redirects, website links, cgit
+    clone prefixes, and chat navigation. Local rendering uses /git, /search,
+    and http://CHAT_LOCAL_HOST:LOCAL_HTTP_PORT for chat.
 
-    To apply changes to the existing services:
+    Apply to existing local services:
 
         cargo stack up --local
 
-    Production uses its prebuilt management command and images:
+    Production uses prebuilt management command/images:
 
         ./bin/stack up --production
 
-    Rendered website files can be read by an already running file server, while
-    listeners, container environment, and loaded Caddy configuration require the
-    service update above. Restart the local chat server with cargo stack chat to
-    load its new bind, origin, or public navigation settings. Reopen your identity
-    file afterward, as with any chat restart.
+    Running file servers can read rendered website updates. Listener, container
+    environment, and loaded Caddy changes need the service update above.
+    Restart direct local chat with cargo stack chat for new bind/origin/navigation
+    settings. Reopen your identity file afterward, as after any chat restart.
 
 PUBLICATION AND LIMITS
 
-    The shared stack-config crate uses an explicit public allowlist for template
-    substitution. A {{CHAT_SETUP_TOKEN}} or other private/unknown placeholder
-    causes an error rather than publishing its value. Generated public pages and
-    proxy configuration never receive a full environment dump. Chat receives the public configuration allowlist plus CHAT_SETUP_TOKEN;
-    other containers receive only their declared service secrets. Caddy uses
-    rendered public configuration and does not need the .env or private tokens.
-
-    The root .env, runtime files, local render outputs, exports, and tool caches
-    remain ignored by Git. Source templates, the commented example, validated
-    defaults, and this configuration implementation are public. Full encrypted
-    backups include the single .env; source-only releases do not include it.
-
-    Personal content and attribution remain source content: copyright headers,
-    author names, canonical contact information, public key material/WKD hashes,
-    project repository metadata, and GNU license links. Changing a deployment
-    hostname does not create a new email identity or regenerate WKD keys.
-    Image digests, source hashes, and fixed crypto/protocol/resource bounds remain
-    reviewed reproducible code/configuration rather than private deployment knobs.
+    stack-config substitutes only explicitly allowlisted public values.
+    {{CHAT_SETUP_TOKEN}} and other private/unknown placeholders fail instead of
+    exposing values. Public pages/proxy config never receive a full environment
+    dump. Chat receives the public allowlist plus CHAT_SETUP_TOKEN; other
+    containers receive only declared secrets. Caddy needs rendered public config,
+    not .env or private tokens.
+
+    Git ignores .env, runtime files, local renders, exports, and tool caches.
+    Source templates, commented example, validated defaults, and configuration
+    implementation remain public. Full encrypted backups include the single
+    .env; source-only releases exclude it.
+
+    Personal content stays in source: copyright, author names, canonical contact,
+    public keys/WKD hashes, repository metadata, GNU license links. Changing a
+    hostname creates no new email identity and regenerates no WKD keys.
+    Image digests, source hashes, fixed crypto/protocol/resource bounds remain
+    reviewed reproducible code/config, not private deployment knobs.