site/GOTCHAS.md

site/ — gotchas

Hand-authored static tree for silentmode.st. No build step. Served by Angie (nginx fork) 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.

Keep it short, and generate the page from it. Since 2026-10-22 the manifest holds only recent versions (5 Theseus, 2 of everything else; the policy table is in scripts/releases-page.mjs) and releases/index.html's release blocks are generated from it. After adding a release to the manifest:

node scripts/releases-page.mjs      # trims the manifest, rewrites the blocks

then scp releases/index.html + the manifest (both VPS paths) + the generated releases/dl-index.html → /opt/silent-mode/dl/index.html (the dl host has no shared.css, so that copy uses absolute links). Do not hand- edit the blocks; the next run overwrites them. Consumers (Theseus + Ariadne + Hermes updaters, dl-latest.sh) read only the first entry per product id, so trimming never changes what they see. Older builds live on Sia under dl-archive/ and every old checksum is in git history.

Ship to dl FROM the repo manifest, never the other way round. On 2026-10-24 a session wrote its product's entries straight into /opt/silent-mode/dl/releases-manifest.json from a stale base and silently dropped four newer Theseus and two Ariadne entries — the auto-updater served 0.3.106 while 0.3.110 was on the host. Merge into site/releases-manifest.json first (union by id+version+platform), run the script, then scp.

Prune the VPS with scripts/dl-vps-archive.sh (all products, --dry-run first). Its keep table must match KEEP in releases-page.mjs, or the page links installers the host no longer has. /latest/ redirects are generated on the VPS by /opt/silent-mode/bin/dl-latest.sh (cron, 5 min), tracked at VPS/SilentMode/dl-latest.sh; a new product needs a row there too.

Check links after editing pages: node scripts/site-linkcheck.mjs.

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

Angie 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 — Angie 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 Angie vhost (location ~ ^/(deviant|sirius-x|theseus-x|…) in VPS/SilentMode/silentmode-st.angie.conf) 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 imported 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 vhost on the VPS is Angie at /etc/angie/http.d/silentmode-st.conf (nginx is installed but dead there; /etc/nginx/sites-enabled/silentmode-st is ignored). It is tracked at VPS/SilentMode/silentmode-st.angie.conf; deploy with scp + angie -t && systemctl reload angie. It 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 vhost 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".