Document VPS post-cutover invariants and taxonomy plan

2026-05-30 18:41:08 +02:00 · 2026-05-30 18:41:08 +02:00 · e7bfd3734f
commit e7bfd3734f
parent 40ca2880ea
2 changed files with 367 additions and 0 deletions
--- a/docs/ops/HYPERTWIST_PLATFORM_TAXONOMY_ALIAS_AND_RENAME_PLAN_2026-05-30.md
+++ b/docs/ops/HYPERTWIST_PLATFORM_TAXONOMY_ALIAS_AND_RENAME_PLAN_2026-05-30.md
@ -0,0 +1,169 @@
+# HyperTwist platform taxonomy alias and rename plan
+
+Created on `2026-05-30`.
+
+## Direct answer
+
+Yes. The current `scriptorium` / `scriptoriumai` umbrella naming can be changed.
+It is not impossible.
+
+The real question is not possibility. The real question is blast radius versus
+benefit.
+
+## What is actually named `scriptorium*` today
+
+The label is not confined to one folder. It currently spans:
+
+- server paths such as `/srv/scriptorium-stack`, `/srv/scriptorium-live`,
+  `/srv/scriptorium-app-api`, `/srv/backups/scriptorium`
+- config paths such as `/etc/scriptorium`
+- public hostnames such as `git.scriptoriumai.io` and `ci.scriptoriumai.io`
+- local automation under `C:\ScriptoriumAI\ops\ssh`
+- scheduled task names
+- log/state directories under `%LOCALAPPDATA%`
+- documentation language across multiple repos
+- Docker object names and compose roots
+- user-facing labels such as `scriptoriumai-new`
+
+So a true rename is a cross-system migration, not a cosmetic text replace.
+
+## Three viable strategies
+
+### Strategy A: keep internals, add human-facing aliases
+
+This changes human-facing labels without moving the internal substrate.
+
+Examples:
+
+- add neutral SSH aliases such as `platform-main-root`, `platform-main-dev`
+- rename scheduled-task display names to neutral labels
+- use neutral labels in docs, password manager entries, and operator checklists
+- add wrapper scripts with neutral names that call the existing `scriptorium*`
+  scripts underneath
+
+Risk:
+
+- low
+
+Operational result:
+
+- operators stop seeing `scriptorium*` everywhere
+- existing paths, services, and automation remain intact
+
+### Strategy B: partial rename of local-facing surfaces
+
+This changes local script names, launcher names, task names, and docs, while
+leaving server paths and public control-plane hostnames intact.
+
+Risk:
+
+- medium
+
+Operational result:
+
+- user-facing clutter drops materially
+- server-side migration blast radius stays limited
+
+### Strategy C: full internal rename
+
+This changes the underlying server paths, local script roots, Docker/compose
+roots, docs, and possibly public Git/CI hostnames.
+
+Risk:
+
+- high
+
+Operational result:
+
+- most aesthetically consistent
+- also the easiest way to break a working setup if even one path is missed
+
+## Recommendation
+
+If the goal is clarity for outsourced operators, Strategy A or B is the correct
+answer.
+
+If the goal is absolute naming purity, Strategy C is possible, but it should be
+treated as a dedicated migration packet with inventory, shim compatibility, and
+validation.
+
+That is the concrete answer to "can it be done or not":
+
+- yes, it can be done
+- no, it should not be done as an ad hoc text sweep
+- the sensible implementation is an alias-first cleanup unless the naming issue
+  is important enough to justify a second migration
+
+## How human-facing aliases work without breaking internals
+
+Human-facing aliases work by changing only the operator-facing entry points.
+
+Examples:
+
+1. SSH:
+   - keep the real target as `212.227.13.220`
+   - add new `Host` aliases in `~/.ssh/config`
+   - do not change the real server paths or accounts
+
+2. Scheduled tasks:
+   - display name can be neutral
+   - launcher script can be neutral
+   - underlying script can still call existing `scriptorium*` assets
+
+3. Docs:
+   - introduce a glossary:
+     - `Platform VPS` = current `scriptorium` control plane
+     - `Platform backups` = current `/srv/backups/scriptorium`
+   - keep exact path literals only where commands require them
+
+4. Wrapper scripts:
+   - `run-platform-remote-dev-seed.ps1`
+   - `run-platform-authorship-sync.ps1`
+   - internally call the current `scriptorium*` scripts
+
+5. Password manager / credential registry:
+   - relabel entries to neutral names
+   - keep the actual usernames, URLs, and paths unchanged
+
+This gives the clarity benefit without creating path churn.
+
+## Full rename blast radius inventory
+
+A full rename packet must account for all of these:
+
+1. server directory names
+2. local script roots and file names
+3. scheduled task names and launcher paths
+4. `%LOCALAPPDATA%` log/state paths
+5. docs across every affected repo
+6. Docker compose project names, container names, volume names, network names
+7. service environment variables and backup scripts
+8. public hostnames if Git/CI branding is also being renamed
+9. webhook, OAuth, and generated-link assumptions
+
+If even one category is skipped, the rename is incomplete.
+
+## If Strategy C is ever chosen
+
+The safe sequence is:
+
+1. freeze the current working state and record exact inventory
+2. create alias wrappers first so there is a rollback-friendly compatibility
+   layer
+3. rename local user-facing scripts and task names
+4. update docs and operator checklists
+5. rename server paths and compose roots only after the wrappers exist
+6. validate SSH, Forgejo, Woodpecker, cron, backups, Rider, and Visual Studio
+7. keep compatibility shims until at least one full backup cycle and one real
+   deployment cycle succeed
+
+## Practical conclusion
+
+The naming can be changed.
+
+The best low-risk implementation is:
+
+- keep the working internal substrate
+- add neutral human-facing aliases and labels
+- only perform a full internal rename if the aesthetics are worth paying for a
+  second real migration
--- a/docs/ops/HYPERTWIST_VPS_POST_CUTOVER_OPERATIONAL_INVARIANTS_2026-05-30.md
+++ b/docs/ops/HYPERTWIST_VPS_POST_CUTOVER_OPERATIONAL_INVARIANTS_2026-05-30.md
@ -0,0 +1,198 @@
+# HyperTwist VPS post-cutover operational invariants
+
+Created on `2026-05-30`.
+
+## Purpose
+
+This note records the operational rules that are now true on the new VPS after
+the DNS and TLS cutover. It exists so a later operator does not have to infer
+these constraints from shell history or chat fragments.
+
+## New VPS identity
+
+- host IPv4: `212.227.13.220`
+- DNS remains hosted at IONOS
+- browser-facing TLS is VPS-side `certbot` / Let's Encrypt, not the IONOS
+  certificate UI
+
+## Root account invariant
+
+The migration sequence preserved the original root login identity.
+
+Confirmed invariant:
+
+- the Linux superuser name remains `root`
+- the existing root password was **not** rotated during this migration
+- SSH key access was added to `root`
+- `dev` and `deploy` were added as additive operational users only
+
+Operational rule:
+
+- do **not** change the `root` username
+- do **not** rotate the root password inside this migration lane as an
+  incidental cleanup step
+- if credential rotation is ever wanted, treat it as a dedicated follow-up
+  operation with explicit validation of SSH, Rider, Visual Studio, cron, and
+  recovery procedures
+
+Reason:
+
+- earlier environment changes around root access created avoidable operator
+  friction
+- the current lane depends on preserving known-good recovery access while the
+  new VPS stabilizes
+
+## New additive users
+
+Current additive users on the new VPS:
+
+- `dev`
+- `deploy`
+
+Current role:
+
+- both are additive convenience accounts for remote development and service
+  operations
+- neither replaces `root` as the recovery anchor for this lane
+
+## Current public HTTPS state
+
+As of `2026-05-30`, these hostnames are live on the new VPS with working public
+HTTPS:
+
+- `scriptoriumai.io`
+- `www.scriptoriumai.io`
+- `app.scriptoriumai.io`
+- `git.scriptoriumai.io`
+- `ci.scriptoriumai.io`
+- `verticaltension.com`
+- `www.verticaltension.com`
+- `app.verticaltension.com`
+- `api.verticaltension.com`
+- `hypertwist.app`
+- `www.hypertwist.app`
+- `vectorshell.com`
+- `www.vectorshell.com`
+
+The current VPS certificate set is:
+
+- `scriptoriumai.io` + `www.scriptoriumai.io`
+- `app.scriptoriumai.io` + `api.scriptoriumai.io`
+- `git.scriptoriumai.io` + `ci.scriptoriumai.io`
+- `verticaltension.com` + `app.verticaltension.com` +
+  `www.verticaltension.com`
+- `api.verticaltension.com`
+- `hypertwist.app` + `www.hypertwist.app`
+- `vectorshell.com` + `www.vectorshell.com`
+
+## Forgejo and Woodpecker auth state
+
+The migrated control plane was preserved as an authenticated service surface.
+
+Forgejo current state:
+
+- `ROOT_URL = https://git.scriptoriumai.io/`
+- `DOMAIN = git.scriptoriumai.io`
+- `SSH_DOMAIN = git.scriptoriumai.io`
+- `SSH_PORT = 2222`
+- `DISABLE_REGISTRATION = true`
+- `REQUIRE_SIGNIN_VIEW = true`
+- existing accounts/data were copied; no passwordless public access was enabled
+
+Woodpecker current state:
+
+- `WOODPECKER_HOST = https://ci.scriptoriumai.io`
+- `WOODPECKER_GITEA_URL = https://git.scriptoriumai.io`
+- `WOODPECKER_ADMIN = scriptoriumadmin`
+- `WOODPECKER_OPEN = true`
+
+Operational implication:
+
+- Forgejo still expects authenticated use
+- Git push auth is still the normal Forgejo model: SSH key or HTTPS credential
+- Woodpecker open mode is inherited from the old stack and should be revisited
+  later if tighter enrollment is desired
+
+## Remote-development seed state
+
+The current VPS remote-development corpus is seeded under:
+
+- `/home/dev/src`
+
+Current seeded top-level trees:
+
+- `HyperTwist`
+- `NyxOS`
+- `ScriptoriumAI`
+- `VectorShell`
+- `VerticalTension`
+- `Workspaces`
+- `visual_studio_solutions/multi_project`
+
+## Reverse-sync lane
+
+The local reverse-sync scaffolding now exists here:
+
+- `C:\ScriptoriumAI\ops\ssh\run-vps-remote-dev-reverse-sync.ps1`
+- `C:\ScriptoriumAI\ops\ssh\install-vps-remote-dev-reverse-sync-task.ps1`
+- scheduled task: `VPS-Remote-Dev-Reverse-Sync`
+
+Current design:
+
+- nightly at `03:30`
+- changed-file reverse sync from `/home/dev/src`
+- conservative excludes for obviously rebuildable artifacts
+- no second full local mirror root by default; it syncs back into the existing
+  local project paths
+
+Current safety rule:
+
+- the task refuses to overwrite a dirty local Git worktree by default
+- that safeguard currently matters because several local repos are dirty
+
+## VerticalTension git/ci alias stance
+
+Canonical Git/CI hostnames remain:
+
+- `git.scriptoriumai.io`
+- `ci.scriptoriumai.io`
+
+Safe incorporation path for:
+
+- `git.verticaltension.com`
+- `ci.verticaltension.com`
+
+is to treat them as branded aliases that redirect to the canonical ScriptoriumAI
+control-plane hosts, not as a second canonical Forgejo/Woodpecker identity.
+
+Why:
+
+- Forgejo `ROOT_URL` and Woodpecker `HOST` are already anchored to the
+  ScriptoriumAI hostnames
+- dual-canonical hostnames create link, callback, and webhook ambiguity without
+  adding real capability
+
+Current prep state:
+
+- the new VPS already has HTTP redirect vhost coverage staged for both alias
+  hosts
+- after their DNS `A` records are moved to `212.227.13.220`, the remaining
+  step is VPS-side certificate issuance for those two hostnames
+
+## IONOS SSL posture
+
+The current deployment does not depend on paid IONOS SSL products.
+
+Operational rule:
+
+- do not use the IONOS SSL UI to manage the public certificates for these VPS
+  hostnames
+- the live browser certificate is the one NGINX presents from the VPS
+- the current setup is already using Certbot successfully for the public HTTPS
+  surface
+
+## Follow-up packaging
+
+Once the cross-project remote-development and backup lane is settled, the VPS
+runbook should be copied into the other project documentation surfaces where it
+is actually relevant.