docs: clarify external services and embedded pi

docs/superpowers/specs/2026-08-04-unified-compose-deployment-design.md

@@ -22,9 +22,9 @@ the complete service definitions.
 ```text
 Browser -> frontend container -> core container
                                   |-> Git workspace registry
-                                  |-> configured DWH
-                                  |-> configured VectorDB
-                                  |-> configured embedding/LLM services
+                                  |-> configured external DWH endpoint
+                                  |-> configured external VectorDB endpoint
+                                  |-> configured external embedding/LLM endpoints
                                   `-> configured session persistence
 ```
 
@@ -88,6 +88,39 @@ frontend host port needed by a generic reverse proxy. Examples for Nginx and Cad
 forwarded identity, websocket/SSE behavior, and timeouts, but neither proxy is embedded into or
 required by the core architecture.
 
+## Product boundary and external services
+
+DWH, VectorDB, and embedding services are always external to the ThothII product boundary and
+Compose lifecycle. The mandatory ThothII stack neither defines nor starts them, never uses
+`depends_on` for them, and does not assume their implementation, installation path, container
+name, Docker network, or host. The same rule applies when all services happen to run on the same
+physical server: from ThothII's perspective they remain independently operated services reached
+through configurable addresses, ports, URLs, TLS settings, credentials, database/schema names,
+and vector collections.
+
+An operator may address a co-resident service through a routable host address, a DNS name, a
+documented host-gateway alias, or an explicitly configured external Docker network. None of these
+becomes a product default. In particular, `127.0.0.1` inside `core` always means the core container,
+not the Docker host; the installation guides must show the correct Mac/Windows Docker Desktop and
+Linux server alternatives.
+
+LLM endpoints follow the same configurable external-service model, while the Pi coding-agent
+runtime itself is part of ThothII as described below.
+
+## Embedded Pi runtime
+
+Pi is an internal runtime dependency of ThothII and is installed at a pinned version while building
+the `core` image. The backend starts the image-bundled Pi executable; it never searches for or
+bind-mounts a Pi installation from the host. Therefore a clean Windows PC, Mac, Linux workstation,
+or server needs only Docker, Docker Compose, and Git to build and run ThothII.
+
+Pi configuration and provider credentials are supplied to the container through the documented
+ThothII configuration and secret-file contracts. Pi writable state may use the ThothII-managed
+`/home/thoth/.pi` volume, but the binary and package installation remain immutable image content.
+Upgrading Pi requires changing the pinned build argument, rebuilding the image, and passing the
+normal ThothII regression and image-smoke gates. The container health/smoke test verifies that Pi
+exists in the image and can be invoked without any host executable.
+
 ## Persistence
 
 Named volumes are the portable default for workstation installations. Server documentation shows
@@ -139,7 +172,7 @@ include a local default and may be overridden with a release version or digest.
 
 Build inputs exclude `.git`, worktrees, local `.env` files, secrets, test output, caches, and
 workspace runtime data through `.dockerignore`. Builds must work from macOS, Windows/WSL2, and
-Linux without host-language runtimes beyond Docker, Compose, and Git.
+Linux without host-language runtimes or a host Pi installation beyond Docker, Compose, and Git.
 
 ## Migration from the current deployment
 
@@ -180,8 +213,9 @@ consumed without installing ThothII there.
 Automated gates cover Compose rendering for local/server plus each Git transport, LF enforcement,
 Docker builds, container health, frontend-to-core same-origin routing, registry bootstrap and
 offline fallback, secret non-disclosure, and absence of PSD/Chirone/portal dependencies in active
-deployment files. Existing backend, frontend, harness, registry, and installation-document tests
-remain required.
+deployment files. Image tests also prove that the pinned Pi executable is available inside `core`
+and that no host Pi path is mounted or required. Existing backend, frontend, harness, registry, and
+installation-document tests remain required.
 
 Manual acceptance covers a clean macOS build, a clean Windows Docker Desktop/WSL2 build from a
 GitHub clone, a Linux server deployment behind a generic proxy, an update after `git pull`, volume
@@ -190,7 +224,7 @@ persistence, and restoration from backup.
 ## Non-goals
 
 - Bundling a DWH, production VectorDB, embedding server, LLM server, or reverse proxy into the
-  mandatory ThothII stack.
+  mandatory ThothII stack, even when those services are co-resident on the same physical host.
 - Making PSD, Chirone, or `omics_portal` supported product profiles.
 - Synchronizing local filesystem sessions between installations without shared session storage.
 - Implementing persistent runtime SSH tunnels for workspace connectors in this migration.