docs: document one-command Docker installation

deploy/secrets/README.md

@@ -1,55 +1,45 @@
-# Runtime secrets and private CA
+# Runtime secrets
 
-Secret values in this directory are ignored by Git and remain local to the cloned `ThothII`
-directory. This self-contained layout is the default installation documented in
-`docs/installazione-docker-4-contesti.md`; an enterprise deployment may point the same
-`*_SECRET_FILE` variables at an external secret-manager materialization instead.
-
-Compose mounts each file read-only beneath `/run/secrets`. The core process runs as UID 10001;
-the mounted files must be readable by that UID. Docker Compose file-backed secrets are normally
-mounted read-only with mode `0444`. This mode is accepted only for runtime paths beneath
-`/run/secrets`, where the container mount is read-only and scoped to services that declare the
-secret. Source files on the host must have no group/other bits (`0600` or `0400`). Verify with:
+The canonical deployment secret is the single local file
+`deploy/secrets/thothii.secrets`. Copy the tracked template and protect the copy:
 
 ```sh
-docker compose -f compose.yaml -f deploy/compose.production.yaml \
-  --profile external run --rm core sh -c 'id && test -r /run/secrets/thoth_ca.pem'
+cp deploy/secrets/thothii.secrets.example deploy/secrets/thothii.secrets
+chmod 600 deploy/secrets/thothii.secrets
 ```
 
-The CA file should contain only the public PEM certificate chain. API-key files should contain
-one value with no surrounding quotes.
+The file uses strict `KEY=VALUE` lines (comments and blank lines are allowed). The supported
+keys are `THT_MODEL_API_KEY`, `THT_DWH_API_KEY`, `THT_VEC_API_KEY`,
+`THT_VEC_WRITE_API_KEY`, and the four `THT_VECTOR_*_PASSWORD` role passwords. Values must be
+non-empty and contain no whitespace. Do not put secrets in the root `.env`, workspace YAML,
+URLs, logs, or `docker compose config` output.
 
-`THT_MODEL_API_KEY_SECRET_FILE` supplies one generic hosted-model key to the core. The backend
-reads it afresh for each Pi child and maps it to the selected provider's native environment name;
-the generic path/value is not placed in settings, health output, argv, or logs. Supported hosted
-providers include Anthropic, OpenAI, Google/Gemini, DeepSeek, Z.AI, Groq, Mistral, OpenRouter,
-xAI, and Cerebras. Local Ollama/LM Studio providers require no file. Compound providers such as
-Bedrock, Azure OpenAI Responses, and Cloudflare Workers AI/Gateway fail closed because they
-require multiple credential/configuration values. Unknown hosted providers fail closed until an
-explicit mapping is added.
-
-## Rotating the initialized local-vector bootstrap password
-
-Replacing `THT_VECTOR_BOOTSTRAP_PASSWORD_SECRET_FILE` or changing its contents does **not** rotate
-an initialized PostgreSQL cluster. Use the supported workflow against the running local-vector
-project:
+Compose mounts the bundle read-only as `/run/secrets/thothii.secrets`. The host file must be a
+regular non-symlink file with mode `0600` or `0400`; Docker's normal `0444` mode is accepted
+only for the runtime mount beneath `/run/secrets`. The core runs as UID 10001. Verify the mount
+without printing its contents:
 
 ```sh
-./scripts/vector-rotate-bootstrap-password.sh \
-  deploy/secrets/vector_bootstrap_password \
-  deploy/secrets/vector_bootstrap_password.next
+docker compose run --rm core sh -c 'id && test -r /run/secrets/thothii.secrets'
 ```
 
-The command authenticates using the current file, changes only the authenticated bootstrap role,
-verifies a new login, and only then atomically replaces the current deployment secret file. If old
-authentication or new-login verification fails, it exits without changing the deployment file;
-verification failure also attempts to restore the old database password over the still-open
-authenticated connection. After success, run the printed `vector-reconcile`/migration/core command.
+A private CA PEM chain is not a bundle value: PEM whitespace is rejected by the strict parser.
+Keep it in the host or secret manager and add a reviewed Compose override that mounts it at
+`/run/secrets/ca-chain.pem` and sets `THT_SSL_CA` (or the adapter-specific setting). The base
+Compose files intentionally do not create this mount.
 
-`THT_VECTOR_BOOTSTRAP_USER` is authoritative for database initialization, reconciliation, and
-rotation; non-default bootstrap role names are supported. Bootstrap, migrator, reader, and writer
-secret files must be non-empty and contain no whitespace (including trailing newlines). Rotation
-rejects invalid files before contacting PostgreSQL or staging a deployment-file replacement.
+## Migration from separate secret files
 
-Keep the staged new file on the same trusted host, mode `0600`, and retain a secure backup until the
-post-rotation reconciliation and application health checks pass.
+Older installations used `THT_*_SECRET_FILE` variables and one file per value. Migrate by
+copying each value to its bundle key, validating with `docker compose config --quiet`, and only
+then deleting the old files. The old variables remain a compatibility path for staged upgrades,
+but the documented and tested default is `THT_SECRETS_FILE=deploy/secrets/thothii.secrets`.
+
+The local-vector bootstrap rotation helper still accepts an old/new password file as its
+maintenance interface. Run it only with files protected by `0600`, then copy the resulting
+password into `THT_VECTOR_BOOTSTRAP_PASSWORD` in the bundle before restarting
+`vector-reconcile`/the application. The helper never prints password contents.
+
+Hosted Pi providers must use a single provider key. Compound providers (Bedrock, Azure OpenAI
+Responses, Cloudflare Workers AI/Gateway) fail closed until a provider-specific credential
+adapter is implemented.