# HyperTwist Website Runtime Configuration Guide

Created on `2026-06-22`.

Updated on `2026-07-03`:

- public marketing pages should not expose raw preview, placeholder, fallback, or
  developer-posture language as the primary visitor experience
- incomplete launch items stay in roadmap and protected/operator diagnostics,
  while anonymous public pages use user-facing early-access, account, release,
  download, and support language
- account creation or sign-in is the intended boundary before protected desktop
  package delivery
- subscription purchase and entitlement authority stay on the website/dashboard
  through Paddle-backed billing; the downloadable consumes account/desktop-link
  authority instead of becoming a checkout or password island
- public anonymous release manifests must not expose raw package URLs
- the browser version is the public/protected access, documentation, account,
  pricing, notices, billing, support, and pairing shell; it is deliberately less
  powerful than the downloadable simulator
- the desktop app remains the primary simulator surface for recognition, replay,
  coaching, higher-dimensional runtime execution, diagnostics, package proof, and
  serious training sessions

## Purpose

This note records the recommended production runtime posture for the first-party
`website/` and `website/server/` lane that powers `hypertwist.app`.

It exists because the source tree now has:

- a real public website
- a real browser auth/dashboard surface
- explicit runtime diagnostics that can distinguish local, mixed, and public posture

## Recommended public posture

For the simplest honest public deployment, prefer same-origin browser and auth
posture:

- frontend public origin: `https://hypertwist.app`
- backend public origin: `https://hypertwist.app`
- frontend route prefix: `/`
- auth API base path: `/auth`
- auth website base path: `/auth`

Recommended server env posture:

- `API_DOMAIN=https://hypertwist.app`
- `WEBSITE_DOMAIN=https://hypertwist.app`
- `PORT=3011` on the current shared VPS, because the live host already has a
  FamiliarOS auth process occupying `3001`
- `API_BASE_PATH=/auth`
- `WEBSITE_BASE_PATH=/auth`
- `COOKIE_SECURE=true`
- `SERVE_STATIC_WEBSITE=true` when the auth server owns same-origin public delivery
- optional `ORCID_CLIENT_ID` and `ORCID_CLIENT_SECRET` when ORCID browser sign-in is intentionally enabled
- optional `ORCID_IS_SANDBOX=true` for sandbox-only ORCID rehearsal instead of the production ORCID authority
- real `PADDLE_WEBHOOK_SECRET`
- real `PADDLE_PRODUCT_PLAN_MAP` and/or `PADDLE_PRICE_PLAN_MAP`

Recommended frontend env posture:

- `VITE_SUPERTOKENS_API_DOMAIN=https://hypertwist.app`
- `VITE_SUPERTOKENS_WEBSITE_DOMAIN=https://hypertwist.app`
- `VITE_AUTH_API_BASE_URL=https://hypertwist.app`
- real `VITE_WINDOWS_DOWNLOAD_URL`
- real `VITE_PADDLE_CHECKOUT_URL_OPERATOR`
- real `VITE_PADDLE_CHECKOUT_URL_STUDIO`
- real `VITE_MPL_SOURCE_URL`
- real `VITE_OPEN_SOURCE_REPO_URL`

The repo now carries two distinct env-template families:

- `website/.env.example` and `website/server/.env.example` for local development
- `website/.env.production.example` and `website/server/.env.production.example` for public-posture scaffolding
- `website/.env.preview.example` and `website/server/.env.preview.example` for
  the current honest live-preview posture on `https://hypertwist.app`

The production examples intentionally include `replace-me` placeholder values so
the readiness command still fails until real launch values are inserted.
They now also carry the explicit static-serving control variables for the
same-origin lane.
The preview examples intentionally do the opposite: they keep checkout,
download, release, and webhook fields honestly empty where the current live
preview lane is not yet launch-complete, while still carrying the real public
origin, source, docs, and release-notes values.

Current same-family follow-up on `2026-06-27`:

- HyperTwist now treats ORCID as a real bounded shared-auth provider lane
  rather than a client-only extension point
- the same-origin bundle renderer now emits matching frontend plus server ORCID
  env values from the authoritative manifest whenever both ORCID credentials
  are present
- runtime diagnostics now also warn when ORCID is only partially configured, so
  a half-wired provider cannot silently masquerade as launch-ready auth posture

That expectation is now proven two ways in the repo itself:

- the real `check-runtime-readiness` CLI is exercised against the checked-in production example files and must fail until placeholders are replaced
- the auth-server bootstrap lane is exercised from production-shaped same-origin env into live `/health`, `/api/auth/health`, and built-shell serving
- the live deployment probe now also checks anonymous `/api/releases/manifest`
  posture and the first-party root-shell marker so the command can explicitly
  distinguish the real same-origin website/auth-server lane from the older
  placeholder rollout page

## Why same-origin is the clean default

The current first-party browser lane already supports exact-origin checks,
dashboard-side launch-readiness visibility, and same-origin auth fallback.

That means same-origin public deployment is the least ambiguous posture for:

- auth cookies
- protected dashboard access
- browser-to-desktop token issuance
- public download gating
- billing webhook and entitlement reflection

The current first-party server can now also own that same-origin shell directly
when a built website bundle exists:

- default bundle pickup: `website/server -> ../dist`
- override with `WEBSITE_DIST_PATH` when deployment layout differs
- set `SERVE_STATIC_WEBSITE=false` to keep api-only mode explicit
- set `SERVE_STATIC_WEBSITE=true` to require bundle presence instead of silently staying api-only
- the readiness verifier now warns when same-origin public posture leaves this static-serving mode ambiguous
- the repo now also carries first-party `systemd` and `nginx` handoff templates
  under `website/deploy/` plus a same-origin deployment cutover guide
- the website package now also ships `npm run render:same-origin-deployment`
  so operators can emit resolved deployment files for the real checkout path
- the website package now also ships `npm run render:same-origin-bundle` so a
  single manifest can own the exact public origin and emit validated frontend
  env, server env, `systemd`, and `nginx` outputs before installation
- the website package now also ships `npm run run:vps-same-origin-live-deploy`
  so the same manifest/bundle lane can execute the bounded root-owned
  checkout/env/build/systemd/nginx replacement flow and then validate the live
  public origin automatically

## Preview-tier rehearsal posture

For non-public rehearsal on the shared VPS, the first-party bundle/readiness
lane now also supports an explicit preview tier:

- set `deploymentTier: "preview"` in the bundle manifest or
  `VITE_PUBLIC_DEPLOYMENT_TIER=preview` plus `DEPLOYMENT_TIER=preview` in env
- honest empty operator checkout, Windows download, release-manifest
  version/build/checksum/published-at, and `PADDLE_WEBHOOK_SECRET` values now
  downgrade to warnings instead of failures
- placeholder strings such as `replace-me-*` still fail in preview posture
- live same-origin preview proof may report `runtime.mode: mixed` when
  `public_origin_ready: true` and the only remaining runtime warning is the
  loopback SuperTokens-core notice
- the staging helper can validate either committed `HEAD` or the in-progress
  local packet through `--archive-source worktree`

## If a split-host auth topology is chosen later

That is allowed, but it should not be the unexamined default.

If a split-host topology is used:

- keep all public-facing auth origins on `https`
- keep `COOKIE_SECURE=true`
- ensure `VITE_AUTH_API_BASE_URL` and `VITE_SUPERTOKENS_API_DOMAIN` still point at the same backend
- ensure dashboard health reports `public auth origin ready: yes`
- ensure launch-readiness warnings are empty before public launch

## Preview-tier staging diagnostics that are acceptable before launch

Before public launch values are fully available, a non-public preview-tier
proof on the shared VPS is still considered healthy when:

- runtime mode is `mixed` or `public`
- `public auth origin ready: yes`
- runtime config errors are empty
- the remaining warnings are limited to the loopback SuperTokens-core notice
  and the expected preview-tier launch-readiness gaps
- the anonymous release manifest returns `configured=false` and
  `download_available=false` for unreleased platforms

## Current diagnostics that must be green

Before public launch, the current runtime and dashboard surfaces should show:

- runtime mode: `public`
- `public auth origin ready: yes`
- no runtime config errors
- no runtime config warnings that indicate loopback, insecure `http`, or partial GitHub/Google/ORCID OAuth setup
- dashboard launch-readiness issues cleared for download/check-out/source configuration
- the deployed website root includes the first-party shell marker rather than
  the old rollout placeholder page
- the live anonymous `GET /api/releases/manifest` route returns JSON with
  public metadata only and no raw download URLs

The current first-party external verification command is:

```bash
cd /home/dev/src/HyperTwist/website
npm run check:runtime-readiness -- --frontend-env .env --server-env server/.env --health-url https://hypertwist.app
```

Use `--skip-live-health` when a deployed endpoint is not reachable yet and only
env-file posture should be checked.

For non-public preview rehearsal, add `--deployment-tier preview` when the
rendered env or manifest has not already set the tier explicitly.

The repo now also keeps that command honest by testing it directly against the
checked-in production example files.
The repo now also keeps the live preview lane reproducible through the checked-in
preview example pair and the convenience command:

```bash
cd /home/dev/src/HyperTwist/website
npm run check:runtime-readiness:preview-live
```

Current live evidence on `2026-06-22`:

- the shared VPS also already had FamiliarOS bound to `*:3001`, so the
  HyperTwist same-origin lane now defaults to `3011` for host-safe deployment
- the root-owned same-origin cutover is now live on `https://hypertwist.app`
  instead of the earlier placeholder rollout page
- `https://hypertwist.app/health` now returns
  `{"ok":true,"service":"hypertwist-auth-server"}`
- `https://hypertwist.app/api/auth/health` now returns `ok: true`,
  `runtime.mode: mixed`, `public_origin_ready: true`, and
  `webhookSecretConfigured: false`
- `https://hypertwist.app/api/releases/manifest` now returns the public
  preview-tier JSON with no anonymous raw download URLs and all platforms still
  `configured=false`
- the checked-in preview example env pair now passes
  `npm run check:runtime-readiness:preview-live` against the live origin
- the repo now also carries a matching preview bundle example at
  `website/deploy/hypertwist.same-origin.preview.bundle.example.json`, while the
  launch bundle example still intentionally fails until real checkout, download,
  source, and webhook values replace its placeholders

This means the remaining public-launch gap is launch-tier checkout/download/
webhook completion and related release-value application, not missing
first-party website/auth-server ownership or live host cutover.

The same host-state conclusion is now strengthened by an isolated VPS-local
staging proof on `3011` that successfully served `/health`, `/api/auth/health`,
`/api/releases/manifest`, and the first-party root shell from a temporary
HyperTwist checkout on the real shared host.

That proof set is now wider than the original launch-like rehearsal: a later
`2026-06-22` scripted proof also passed in preview tier while staging the live
local worktree through `--archive-source worktree`, with honest empty operator
checkout, Windows download, release-manifest version/build/checksum/published
fields, and `PADDLE_WEBHOOK_SECRET`, while `/api/auth/health` still reported
`runtime.mode: mixed`, `public_origin_ready: true`, and only the loopback
SuperTokens-core warning.

## Related authorities

- `website/README.md`
- `website/server/README.md`
- `website/deploy/README.md`
- `docs/ops/HYPERTWIST_PUBLIC_WEBSITE_AUTH_BILLING_AND_DISTRIBUTION_PACKET_2026-06-22.md`
- `docs/ops/HYPERTWIST_WEBSITE_SAME_ORIGIN_DEPLOYMENT_HANDOFF_2026-06-22.md`
- `docs/ops/HYPERTWIST_WEBSITE_VPS_PRECUTOVER_HOST_STATE_2026-06-22.md`
- `docs/v6_5_deep_manual_pack/HyperTwist/ROADMAP.md`
- `docs/v6_5_deep_manual_pack/HyperTwist/FEATURE_REGISTRY.md`
- `docs/ops/HYPERTWIST_VPS_TLS_CERTIFICATE_AND_IONOS_SEPARATION_GUIDE_2026-05-30.md`
