feat: add AI catalog description generation

README.md

@@ -17,6 +17,8 @@ From a fresh clone, run these commands from the repository root:
 
 ```sh
 cp deploy/env/local.env.example deploy/env/local.env
+# Copy docs/install/examples/thothii-installation.local.yaml to a protected operator path,
+# replace its placeholders, chmod it 600, and set that exact THT_INSTALLATION_CONFIG_SOURCE.
 # Edit deploy/env/local.env, including PI_AUTH_FILE, THT_SECRETS_FILE, and external endpoints.
 ./scripts/run-stack.sh
 ```
@@ -29,7 +31,8 @@ application rollout:
 
 ```sh
 cp deploy/env/server.env.example deploy/env/server.env
-# Edit all absolute storage, Pi/secret/session files, and endpoint paths.
+# Prepare a mode-600 thothii-installation.yaml from the server example and set its exact
+# path as THT_INSTALLATION_CONFIG_SOURCE. Edit all remaining storage/secret/endpoint paths.
 sudo scripts/prepare-server-pi-state.sh /srv/thothii/pi-state 10001 10001
 docker compose --env-file deploy/env/server.env \
   -f compose.yaml -f deploy/compose.server.yaml \
@@ -293,6 +296,31 @@ Copy `deploy/secrets/thothii.secrets.example` to a protected host file, include
 keys, and set its absolute path as `THT_SECRETS_FILE` in the operator env. Keep Pi's native
 provider auth in the separate protected file named by `PI_AUTH_FILE`.
 
+Description Generation is configured independently in the protected installation descriptor under
+`metadataGeneration`. Set `THT_INSTALLATION_CONFIG_SOURCE` to that exact host file; Compose mounts
+it read-only into `core` and supplies the fixed runtime `THT_INSTALLATION_CONFIG_FILE` path. Each
+keyed model stores only an audited `apiKeyEnv` reference. The referenced value stays in the secret
+bundle; a model may omit `apiKeyEnv` only when it declares an explicit endpoint that accepts
+unauthenticated requests. The browser receives only model IDs, labels, and the configured default.
+Configuration changes take effect after restart and do not use Pi settings or workspace
+`llm_policy`.
+
+Before enabling Description Generation, approve the selected model provider for bounded source-data
+disclosure. A request may send up to five real source rows and up to five representative distinct,
+non-null example values for relevant columns. Samples are transient and are not stored in generation
+runs, run logs, application logs, API responses, or catalog metadata; prompt and sample snapshots are
+not retained. Automated Sensitive Data Policy filtering and anonymization are not currently provided.
+A future Sensitive Data Policy is required to classify protected fields and exclude or anonymize
+their values before model calls.
+
+Description Generation is an interactive Database Management operation, not a user-facing CLI.
+The installation runs at most one sequential generation at a time. The run drawer exposes safe
+ordered events through SSE with polling fallback, Stop terminates the current helper while keeping
+already stored results, and Run history retains terminal runs for inspection. A backend restart
+marks queued or running work interrupted instead of resuming it; use Generate Missing to continue.
+Unlock is reserved for a stale recorded run and is rejected while a local start, worker, or helper
+is still live.
+
 The bundle is mounted read-only as `/run/secrets/thothii.secrets` and must be mode `0600` or
 `0400` on the host. Docker's runtime `0444` mode is accepted only beneath `/run/secrets`; see
 [`deploy/secrets/README.md`](deploy/secrets/README.md). A PEM CA chain is deliberately not a