docs: consolidate historical records and verify public manual publication

docs/operations/public-docs-publication.md

@@ -0,0 +1,90 @@
+# Publishing the public manual
+
+This is an internal operator runbook. Publishing documentation must not recreate
+the ThothII application, Gitea, proxy, DWH or other documentation containers.
+
+## Three separate states
+
+1. `main` contains reviewed source and the public allowlist in `mkdocs.yml`.
+2. Gitea Actions builds and validates the generated `pages` branch. A successful
+   Actions run alone does **not** update the live site.
+3. The live [manual](https://git.tylconsulting.it/thothii-docs/) is served by the
+   dedicated `thothii-docs` nginx container on the host reached through the existing
+   trusted SSH alias `contabo`. Its Compose project/service are `thothii-docs`/`docs`.
+
+This procedure is manual. No timer, webhook, credential or automatic deployment
+has been added. Use the operator's existing SSH authorization and known host key;
+never disable host verification to make a publication work.
+
+## Build and stage
+
+From a clean ThothII `main` checkout already pushed to Gitea:
+
+```sh
+git status --short
+git rev-parse HEAD
+./scripts/build-docs.sh
+bash scripts/auth-docs-smoke.sh
+bash scripts/verify-dwh-auth-docs.sh
+bash scripts/test-auth-docs-smoke.sh
+bash scripts/test-verify-dwh-auth-docs.sh
+```
+
+The strict build also verifies the public boundary: exactly 20 navigation pages,
+five approved source assets, no internal pages/assets, and matching search entries.
+Theme-generated assets are separate from those five source assets.
+
+Choose a unique release identifier consisting of UTC timestamp and source SHA.
+Record the current symlink and container identity before proceeding:
+
+```sh
+ssh -oBatchMode=yes -oStrictHostKeyChecking=yes contabo \
+  'readlink /srv/thothii-docs/current; docker inspect --format "{{.Id}} {{.State.Health.Status}}" thothii-docs'
+```
+
+On the server, create `/srv/thothii-docs/releases/RELEASE/site` only if RELEASE
+does not exist. Copy the current `nginx.conf` unchanged into the new release.
+Transfer the local built `site/` into that new empty directory with rsync over
+the same verified SSH connection. Do not use `--delete` against `current`, and do
+not edit routing, TLS, network or authentication configuration.
+
+## Activate only this site
+
+Replace RELEASE below with the validated identifier, not a user-supplied path.
+Keep the previously recorded release for rollback.
+
+```sh
+cd /srv/thothii-docs
+test -f releases/RELEASE/site/index.html
+test -f releases/RELEASE/nginx.conf
+docker exec thothii-docs nginx -t
+ln -s releases/RELEASE current.next
+mv -Tf current.next current
+docker compose --project-name thothii-docs -f docker-compose.yml \
+  up -d --no-deps --force-recreate docs
+```
+
+Check that `current.next` does not already exist before creating it; stop if it
+does, because another publication or recovery may be in progress. Changing the
+symlink alone is insufficient: an existing Docker bind mount still resolves to
+the old release. The service recreation above remounts the new directory. It may
+briefly interrupt this manual only.
+
+## Verify, record, or roll back
+
+- Wait for `docker inspect` to report this container healthy; verify mounted
+  paths and nginx configuration. Stop after a bounded timeout (for example 60 s).
+- Without login/cookies, require HTTP 200 for home, search and both
+  `install/standalone-manual-it/` and `install/standalone-manual-en/`.
+- Compare live home and `search/search_index.json` checksums to the build. Search
+  must contain only the 20 approved pages, never plans, reports or architecture.
+- Require HTTP 404 for retired/internal paths, including `architecture/overview/`,
+  `plans/2026-09-08-memory-management/`, and `operations/compose-reference/`.
+- Record source SHA, release ID, previous release and checks in the cleanup/release
+  record. Do not call the publication complete solely because `pages` was pushed.
+
+If health or public verification fails, point `current` back to the recorded
+previous release using a fresh temporary symlink and the same atomic rename, then
+recreate **only** service `docs` with the same Compose command. Verify health and
+old site availability. Do not delete either release during recovery. Historical
+releases are retained; pruning them requires a separate retention decision.