site/GOTCHAS.md

# site/ — gotchas

Hand-authored static tree for **silentmode.st**. No build step. Served by nginx
from `/opt/silent-mode/site/` on the VPS (ssh alias `silentmode`), and mirrored
to Sia (`s3://bns/silentmode/` → `silentmode.bch`) by the
`silentmode-sia-sync.timer` on the VPS every 5 minutes. Anything that lands in
`/opt/silent-mode/site/` reaches the `.bch` mirror on its own; you do not need to
run `sia-upload.js` for site files any more.

## Never `rsync --delete` (or blanket-overwrite) `site/` → the VPS

`/opt/silent-mode/site/` holds far more than this folder: `sirius-x/`,
`deviant/` (the full Deviant site incl. `wallet/`, `artemision/`, `katalogos/`,
`agora/`), `apps/`, `code/`. Those are deployed from **other repos**. In
particular `site/deviant/` here is a **stale Aug-31 copy**; the canonical
source is `D:\Dev\Deviant\site\deviant\` and the VPS already carries the newer
Sep-1 pages. Pushing this folder wholesale would roll them back.

Ship **individual files**: `scp site/<path> silentmode:/opt/silent-mode/site/<path>`.

## The release manifest lives in three places

- `https://dl.silentmode.st/releases-manifest.json` — canonical
  (`/opt/silent-mode/dl/`), what `releases.silentmode.bch` points at.
- `/opt/silent-mode/site/releases-manifest.json` — what `tools/index.html`
  links as `../releases-manifest.json`, and what the Sia mirror syncs.
- `site/releases-manifest.json` — the committed source of both.

The ship checklist (`Ship Theseus …` commits) must scp it to **both** VPS
paths. It was missed for `site/` from 0.3.4 through 0.3.16 (found 2026-09-07):
the HTML pages were current while the JSON next to them still said 0.3.3.

## Old Theseus builds fill the VPS disk

`scripts/theseus-vps-archive.sh <version>` moves everything older than N-1 to
Sia and deletes it from `/opt/silent-mode/dl/`. Run it after every ship; when
it is skipped the 48 GB disk climbs ~245 MB per release.

## Bump `shared.css?v=` whenever shared.css changes

nginx sends no `Cache-Control` for `.css`, so browsers cache `shared.css`
heuristically (10% of its age since `Last-Modified`; it sat unchanged for
weeks, so returning visitors kept the old copy for days). When the logo rule
was added on 2026-09-07 every page except Hephaestus (inline nav CSS) showed
the brand wrapped onto its own row for anyone with a cached sheet. Every page
now links `shared.css?v=YYYYMMDD`; change the value on every page (one `sed`)
each time the file changes. Same applies to the Sia mirror via the gateway.

## URLs have no trailing slash; links are site-root-relative

Since 2026-09-20 the canonical URL of every silentmode.st page is `/tools`,
`/sirius`, `/choose/free` — nginx 301s `/tools/` → `/tools` and serves
`/tools/index.html` from it. Consequences for authors:

- A page at `/x/index.html` is viewed at `/x`, so the browser's directory is `/`.
  Write links **relative to the site root**: `sirius`, `theseus/img/foo.png`,
  `shared.css?v=…`, `favicon.svg`, and `./` for home. Never `../sirius/` (goes
  above the root) and never `img/foo.png` (resolves to `/img/`).
- Site-root-relative also works under the BNS gateway, which injects
  `<base href="/bns/silentmode.bch/">` on every page. Root-absolute (`/sirius`)
  breaks there, so use it only for the sub-sites listed below.
- Nested pages (`choose/free`…) use root-absolute links without a trailing slash.
- `scripts/serve-site.mjs` applies the same rules locally; check with
  `node scratch/linkcheck` logic: resolve each link from `/` and require a file,
  `<path>.html`, or `<path>/index.html`.

**Sub-sites deployed from other repos keep their trailing-slash URLs** because
their asset paths are relative: `deviant/`, `sirius-x/`, `theseus-x/`,
`hephaestus.x/`, `fly.x/`, `code/`. The list lives in the nginx vhost
(`location ~ ^/(deviant|sirius-x|theseus-x|…)`) and in `serve-site.mjs`; add
any new foreign mirror to both.

## `/theseus` vs `/theseus-x/` (and `/sirius` vs `/sirius-x/`)

`/theseus` and `/sirius` are silentmode.st pages with the shared header that
link out to the sovereign sites. The sovereign sites' VPS mirrors are
`/theseus-x/` and `/sirius-x/`, deployed by `scripts/mirror-bcnr-site.sh` from
`site-theseus-x/` and `site-sirius-x/`. Do not mirror a sovereign site onto
`/theseus/` or `/sirius/` again — that is what made the nav tabs swap headers.
`/tools` is the overview/docs page (sites, sovereign twins, other clients,
endpoints); Theseus downloads live on `/theseus`.

## Pages that are not silentmode.st pages

`hephaestus.x/` is the landing for the `.x` name and is served from Sia via the
gateway (`navigate.st/bns/hephaestus.x/`); the copy under `/opt/silent-mode/site/`
is just parity. `choose/` has no top nav on purpose.

## CORS on `/js/*.js` — required for BCNR pages

The shared bundles (`bns-register.js`, `libauth.js`, `wizardconnect.js`) live
under `silentmode.st/js/` and are `import`ed cross-origin by pages served on
their own origin: `sirius.x`, `theseus.x`, any BCNR-served site opened in
Theseus (origin `bns://<name>`). Without CORS the browser refuses to load the
module and every wallet/register/mint flow silently breaks — the launcher
click does nothing.

The nginx block on VPS (`/etc/nginx/sites-enabled/silentmode-st`) MUST carry:

```
location ~ ^/js/.*\.js$ {
  add_header Cache-Control "no-cache, must-revalidate" always;
  add_header Access-Control-Allow-Origin "*" always;
  add_header Access-Control-Allow-Methods "GET, OPTIONS" always;
}
```

Added 2026-09-08 after Theseus reported "CORS blocked" from origin
`bns://sirius.x`. If a future nginx-config rebuild drops the `add_header
Access-Control-*` lines, every non-silentmode.st page that imports the bundle
starts failing again with "No 'Access-Control-Allow-Origin' header".