fix: validate deployment rollback and server topology

docs/install/server-workspace-registry.md

@@ -18,6 +18,20 @@ first startup. Keep storage separated:
 /srv/thothii/operator/            # untracked operator files, setgid mode 2770
 ```
 
+After cloning the source and before the first render/start, initialize the empty Pi-state root with
+the repository setup command:
+
+```sh
+sudo /srv/thothii/source/ThothII/scripts/prepare-server-pi-state.sh \
+  /srv/thothii/pi-state 10001 10001
+```
+
+The active server profile mounts that writable parent at `/home/thoth/.pi` and overlays three
+read-only files beneath `agent/`. The setup command atomically creates the required hidden regular
+targets with runtime ownership without copying secret or tracked file contents into writable
+state. Rerun it after a restore and before Compose or `thothctl` startup; it is idempotent and does
+not overwrite existing targets.
+
 Permit outbound TCP only to approved Git/Gitea, DWH, vector, embedding, and bastion endpoints.
 Allow inbound traffic only from the reverse proxy/Docker network. Do not give the runtime service
 account Gitea administration, database-superuser rights, or a shell in the Git host.
@@ -171,6 +185,10 @@ THT_WORKSPACE_BINDINGS_ENV_FILE=/srv/thothii/operator/workspace-bindings.env
 THT_CONNECTOR_OVERRIDE=/srv/thothii/operator/connector-secrets.server.yaml
 THTCTL=/srv/thothii/operator/thothctl
 INSTALLATION=/srv/thothii/operator/thothii-installation.yaml
+sudo "$THT_SOURCE_ROOT/scripts/prepare-server-pi-state.sh" /srv/thothii/pi-state 10001 10001
+"$THT_SOURCE_ROOT/scripts/compose-with-preflight.sh" --env-file "$THT_OPERATOR_ENV" \
+  -f "$THT_SOURCE_ROOT/compose.yaml" -f "$THT_SOURCE_ROOT/deploy/compose.server.yaml" \
+  -f "$THT_SOURCE_ROOT/deploy/compose.session-server.yaml.example" config --quiet
 "$THT_SOURCE_ROOT/scripts/generate-connector-secrets-override.sh" \
   --bindings-env "$THT_WORKSPACE_BINDINGS_ENV_FILE" \
   --operator-env "$THT_OPERATOR_ENV" --output "$THT_CONNECTOR_OVERRIDE"

docs/install/server.md

@@ -184,8 +184,17 @@ sudo -u thothii git -c core.autocrlf=false clone \
 cd /srv/thothii/source/ThothII
 sudo -u thothii git config --local core.autocrlf false
 bash scripts/verify-line-endings.sh
+sudo /srv/thothii/source/ThothII/scripts/prepare-server-pi-state.sh \
+  /srv/thothii/pi-state 10001 10001
 ```
 
+The last command is a mandatory clean-install and restore preflight. The server profile bind-mounts
+the writable Pi-state root and then overlays protected `auth.json` plus tracked `models.json` and
+`settings.json` read-only below it. Docker requires those three hidden target files to exist under
+the host parent bind before startup. The initializer creates them atomically with UID/GID 10001,
+mode `0600`, rejects symlink roots or targets, and never overwrites existing contents. It is safe to rerun
+after restoring `pi-state`; run it before any `thothctl start`, Compose render/start, or Pi update.
+
 Copy the path-only server environment and installation descriptor:
 
 ```sh
@@ -414,6 +423,11 @@ sudo test -d "$RESTORE/workspace-registry/repo"
 sudo test -d "$RESTORE/workspace-registry/snapshots"
 ```
 
+After placing the restored `pi-state` tree and before the first start, rerun
+`sudo /srv/thothii/source/ThothII/scripts/prepare-server-pi-state.sh /srv/thothii/pi-state 10001 10001`.
+It validates or recreates only the hidden regular mount targets; it does not alter restored Pi
+state or any protected configuration source.
+
 During the reviewed restore window, move each old tree to a timestamped sibling, move the matching
 restored tree into `/srv/thothii`, restore the PostgreSQL session backup from the same recovery
 point, and keep the proxy closed. Run `update --check-only`, `start`, `doctor`, `pi test`, registry