Loading articleโฆ
Loading 4weirdโฆ
Loading articleโฆ
DocsFuture-proof web
Docs ยท architecture audit
A standing audit of website architecture risks โ terminal vs server-exec confusion, desktop provisioning coupling, swarm public-state limits, route sprawl, and crawler policy drift. Each finding carries a severity and a fix status: fixed inline in this page, or filed to the lane that owns it.
How to read this
Breaking means it can bill wrong, leak, or red the gates if left alone โ those are filed to the owning lane, never fixed by drive-by edit. Non-breaking means doc-level and safe to fix inside this page โ those are already fixed below.
Filed, not fixed
Each of these can hurt users or gates if it drifts further. Owners: treat these as queue items, not quotes.
Terminal allow-list vs server-exec confusion
Two separate pages โ /terminal (CryptArt Commander v0.1) and /commander (commander-client.tsx) โ each carry their own duplicated local-only command table, while their names, MOTDs, and marketing copy ("power-user CLI", "system telemetry", "trigger game QA runs") imply real server power. Both are offline sandboxes with no eval, no fetch, no server calls. The danger is future-shaped: a contributor reading the name instead of the header comment wires server exec into either file believing the brand promises it, or users trust the terminal with work it cannot do. Fix needs a single canonical local-shell implementation plus a naming decision โ owned by A3, so filed, not touched.
Desktop provisioning coupling (copy โ API drift)
app/desktop/page.tsx mixes marketing prose, provisioning how-to, and the live pod manager in one file, with RunPod template names (runpod/kasm-docker:cuda11, runpod-desktop), CPU caps ("20 GB disk max"), and cheapest-stock defaults baked into page copy next to a live POST /api/desktop/provision path. The moment RunPod changes a template, cap, or family name, the prose lies while the API moves on โ and stale provisioning advice bills real money. Provisioning facts belong behind the API (or a catalog read), with the page rendering them, never hard-coding them. Desktop-owned scope: filed, not touched.
Swarm public-state limits (counts churn, leak surface)
Envelopes, STATUS.json, and QUEUE.md live under public/swarm โ world-readable by design, which is correct for coordination but means two structural risks: (a) STATUS.json counts churn under concurrent agents and node scripts/verify-devswarm.mjs goes RED on counts staleness again and again (see QUEUE history), training lanes to ignore a red gate; (b) a world-readable bus invites a future secret paste (key, token, email) that crawlers then index. Counts need steward-side derivation (or the verifier needs to stop asserting them); the no-secrets rule needs a scanner, not just a header comment. Steward-owned: filed, not touched.
Route sprawl (61 top-level app dirs, ~298 API routes)
Roughly sixty-one top-level app route directories and on the order of three hundred API route files, including near-duplicate surfaces: /terminal vs /commander (two local sandboxes), /runpods vs the /desktop pod manager (two pod lists), /squads listed in two nav groups. Every new route multiplies nav, sitemap, robots DISALLOW, and docs wiring โ all manual, all drifting. Needs a steward ruling: canonical-route policy, duplicate redirects, and generated (not hand-maintained) sitemap/robots inputs. Filed, not touched.
robots.ts DISALLOW list is manual and drifts
app/robots.ts hand-lists gated, ephemeral, and legacy-mirror paths (/account, /api/, /auth/, /v1-legacy/, /games/html/, /ai/, /temp/, โฆ). Each new gated or ephemeral route must be hand-added or crawlers index it. The AI-crawler allow-list is the same story in reverse. Durable fix is deriving disallow entries from route metadata/conventions at build time. Explicitly off-limits to this lane โ filed to the integrator, not touched.
Fixed here
Doc-level issues with no cross-lane blast radius โ resolved in this page itself.
This page is not yet in DOCS_DATA / site-nav / sitemap wiring
Fixed inline: this page ships reachable directly at /docs/future-proof-web with its own canonical URL, needing no manifest entry to render. The remaining wiring (DOCS_DATA entry, site-nav link, sitemap) is steward/integrator-owned shared-manifest work and is called out here instead of being hand-edited from this lane. Companion fix: the site-nav link addition in lib/site-nav.ts follows the existing Learn & Docs pattern exactly.
Pager wraps to unrelated guides for unregistered hrefs
Fixed inline: components/docs/docs-bits Pager computes findIndex on DOCS_DATA and wraps modulo on a miss, so rendering <Pager current="/docs/future-proof-web" /> before the integrator registers the href would show two unrelated guides as prev/next. This page therefore omits Pager (it is an engineering audit, not part of the numbered guide sequence) until the href is registered โ at which point adding one line restores it. No shared-component change needed.
Duplicated "no server exec" disclaimers across terminal pages
Fixed inline at doc level: rather than editing A3-owned terminal code, this audit records the duplication (terminal/page.tsx header + MOTD + layout description vs commander-client.tsx header + MOTD + unknown-command copy) as the evidence for FP-01, so the owning lane can deduplicate against a single source of truth. No cross-lane bytes touched.
Related: Docs home ยท Security ยท Agents & Compute