diff --git 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 new file mode 100644 index 0000000..e3d9d68 --- /dev/null +++ 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 diff --git 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 new file mode 100644 index 0000000..f6a0d15 --- /dev/null +++ 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.