docs: adopt clean PSD replacement model

docs/superpowers/specs/2026-08-21-psd-clean-replacement-design.md

@@ -0,0 +1,86 @@
+# PSD Clean ThothII Replacement Design
+
+**Date:** 2026-08-21
+**Status:** Approved by the owner
+
+## Decision
+
+The existing PSD ThothII installation is disposable. Its sessions, settings, Pi state, derived
+artifacts, indexes, images, source checkout, and application data are not migration inputs for the
+new installation. They remain present only until the replacement has passed the real Aritmolab
+journey; this temporary retention is a cutover safeguard, not a legacy-support requirement.
+
+The replacement does not create a host `thothii` user or group. The image keeps its internal
+UID/GID `10001:10001`. Host bind trees that the container must write may use that numeric ownership
+without corresponding `/etc/passwd` or `/etc/group` entries. Source and operator-controlled files
+remain owned by the existing operator `admlocforn1` (UID 1013) and the existing `chirone` group
+(GID 1006).
+
+## Boundaries
+
+The following old ThothII resources become deletion candidates only after Project B human
+acceptance proves the production Aritmolab route:
+
+- containers `thothii-core-1` and `thothii-frontend-1`;
+- images `thothii-core:local` and `thothii-frontend:local`, after proving no other container uses
+  their immutable IDs;
+- checkout `/home/chirone/ThothII`;
+- application bind tree `/home/chirone/thothii-data`.
+
+The following resources are shared and are never deletion candidates in the ThothII cleanup:
+
+- Docker networks `omics_portal_omics_network` and `localllm_default`;
+- `/home/chirone/chirone/etl/docs/evidence` and the ETL project;
+- Omics Portal/Aritmolab source, Nginx, web, worker, sidebar, and capability configuration;
+- LocalLLM API and vLLM services;
+- `dwh-auth`, its credential registry, and the `/dwh/` Nginx route;
+- Supabase/DWH, Authentik, Superset, and their data or configuration.
+
+No global Docker prune, network removal, broad recursive deletion, or Compose volume deletion is
+permitted. Cleanup resolves and revalidates every exact target immediately before removal.
+
+## Sequence
+
+1. Project A preparation creates a distinct installation under `/srv/thothii`; it does not reuse
+   `/home/chirone/thothii-data`.
+2. Immediately before creating bind roots, verify that UID and GID 10001 still have no host account
+   mapping. A newly observed mapping is a stop condition requiring owner review.
+3. Project A may stop the old containers only under its separate mutation authorization. The old
+   source, data, containers, and images remain intact while the new private stack is tested.
+4. Project B changes the production integration and proves the complete path:
+   `Aritmolab -> sidebar -> Nginx/load balancer -> ThothII`, including frontend assets, API, SSE,
+   authentication, and a completed workflow.
+5. Only after the Project B automated report, human report, and owner decision are PASS may the
+   exact old ThothII resources be deleted.
+
+If Project A fails, stop the new private stack and restart the still-present old containers. If
+Project B fails, close the new ingress and restore the prior route while the old resources still
+exist. After Project B PASS and legacy deletion there is deliberately no promise to restore old
+ThothII sessions or state.
+
+## Host ownership model
+
+No command may call `useradd`, `groupadd`, `usermod`, or modify the host identity databases.
+
+- `/srv/thothii/source` and `/srv/thothii/operator`: `1013:1006`.
+- `/srv/thothii/data`, `/srv/thothii/pi-state`, and `/srv/thothii/workspace-registry`:
+  numeric `10001:10001`.
+- protected files mounted read-only by the core: operator-owned with a narrowly selected numeric
+  group/owner mode that permits UID/GID 10001 to read only the required file.
+- `/srv/thothii-backups`: operator/root protected and outside the runtime write boundary.
+
+Numeric ownership does not create or preserve a host user. It is confined to the new installation
+tree and exists solely to match the non-root identity already embedded in the container image.
+
+## Acceptance
+
+The design is satisfied only when evidence proves all of the following:
+
+- no host account or group was created for 10001;
+- the new core runs non-root and can write only its intended runtime trees;
+- the shared networks and external Evidence tree remain unchanged;
+- Project A and Project B pass their independent automated and human gates;
+- Aritmolab no longer resolves production traffic to `thothii-core` or `thothii-frontend` legacy
+  containers before those containers are removed;
+- the cleanup inventory contains only exact legacy ThothII targets and excludes every shared
+  resource listed above.