Docs-site restructure — vault mirror (2026-10-14)

Young: "rebuild just to have Docs and Pulse similar to Vault structure. Cleanup and remove the rest." Executed end-to-end; all routes verified live.

The new site = two sections, exact vault mirror

• / now redirects to /pulse (the flight-desk redirect is retired).
• nuxt.config.ts.bak-…restructure + old content archived at content.pre-restructure-20261014/ + content.port-era-final/ (rollback = swap dirs + restore bak config).
• Follow-ups captured for their lanes (not executed): path-romanization for future polish (02-architecture → architecture), M365/domain pricing variables in Mira's model — no; that's Mira's domain. Nav labels in LAB vault landings (Docs/index.md, Pulse/index.md) drive the site nav; vault edits automatically propagate next rebuild.

Mechanics (registered for the fleet)

• Forge: build_site.py runs on LAB (near sources), converts vault md+mdx → /tmp/site_build/{Docs,Pulse} (479 files: Docs 195, Pulse 284 + 63 dir landings = 537 installed), resolves wikilinks/admonitions/MDX via the convert() from the old port, emits site-map.json, tars, then installs at prod.
• port.py is retired — neutralized at the top (SystemExit(0) guard; port.py.bak-20261014-portera preserved) because sync-docus.sh calls it and it stomped my first install (log timestamped the stomp: it re-ported the then-live old-tree sources). Root cause of first-attempt rollback.
• Migration note: investing/property mdx now canonical at LAB vault/Docs/{investing,properties}/ — pulled from the old prod tree, pushed through the LAB vault, committed with the vault sync chain (root landings Docs/index.md, Pulse/index.md included).
• Skip rule: 05-archive/reference-tree (1,461 files, legacy) excluded; 66 non-ref archive .md files kept under SolOSV3.
• nitro build ~30–35 min for 537 files on the Oracle ARM node — background-job discipline (tracked process, wait for completion, don't parallelise).

Post-state

• Old-era content dirs kept (not deleted): content.pre-restructure-20261014/, content.port-era-final/ — rollback-ready.
• Scripts saved: LAB /tmp/build_site.py, prod /tmp/site_build.tgz — persist to the template repo (next lane item: version the forge + onboarding script).
• Future content flow: write in LAB vault → build_site.py → tar → prod install → sync-docus.sh (build only, port is retired) → verify routes → commit docs-site repo.

2026-10-21 — the delivery end was never built (Sol, card t_e27193cc)

The flow described above still ended at "tar → prod install". When the prod vault was retired on 2026-10-18, the delivery end was removed and never replaced: prod-vault-removal.md recorded the intended replacement ("LAB vault → git push (solos-docs repo) → prod git pull → sync-docus.sh build → nginx") but only the design was written. The prod crontab entry was commented out and no timer was installed.

Consequence measured 2026-10-20: docs.youngle.au served content from 2026-10-18 13:31 while the vault had moved on — 2,316 files never reached the site, including the Marketing/Social add-on pricing ruling and the EVE customer-service design.

What was actually broken (both halves):

Findings worth keeping:

• The solos-docs repo is public, so prod needs no GitHub credentials to git pull — git fetch works as the plain ubuntu user. (An earlier read of the empty ~/.git-credentials suggested the git lane was impossible; the live probe showed otherwise. The git lane is the right choice and needs no new secrets.)
• git reset --hard origin/main, not git pull. The Nuxt build mutates a tracked file (.data/content/contents.sqlite changes on every build), so the prod working tree is never clean and a plain pull conflicts. A reset gives an exact mirror of what LAB published.
• A commit failure must abort the publish. The first version of docs-publish.sh ran git commit without checking its exit status. With no git identity configured in the clone the commit silently did nothing and the script went on to log "pushed " — a false success. It now aborts on commit failure and verifies origin/main actually moved to the new commit.
• Docs/Kanban/*.kanban are excluded from the publish. The board projector rewrites them every minute (they change on every cycle), and Nuxt Content cannot parse them anyway (".kanban files are not supported" at build time; /docs/kanban/docker-vhost 404s). Publishing them would rebuild the site ~96×/day for content the site never renders. fleet-board.md is a real .md doc and is published.
• The 2026-10-20 delivery attempt left a live regression: it deleted content/Pulse/ on prod (318 files) and rebuilt from it, so /pulse 404'd while the site was otherwise up. Restored from HEAD and re-verified 200.
• Proof of a working lane is a live URL, not a file on disk. A probe file written into the vault was live at /docs/projects/vhost/implementation/publish-lane-probe-2026-10-21 with no human in the loop, and a different agent's new doc (resend-notification-provider-2026-10-20) was published and served 200 by the same unattended run.

Reconciliation check (which vault files have not reached the site): /home/lab/.solos/operation/ops/reconcile_publish.py → 0 vault Docs files unpublished.

Related: [prod-vault-removal](prod-vault-removal), [HANDOFF-nova-docs-nav](handoff-nova-docs-nav).