---
title: "2026-08-06 infrastructure sources audit and wiki promotion"
description: "Audited the legacy sources/ tree claim-by-claim against the virdx repos, promoted what still held into wiki/ sops, deleted the rest, and added CI formatting enforcement."
image: "https://docs.virdx.dev/img/virdx-social-card.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.virdx.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 2026-08-06 infrastructure sources audit and wiki promotion

## Work Done

Goal: `sources/` was suspected stale. It was also load-bearing — `wiki/` pages
linked into it — so "clean up" meant audit, promote, relink, delete.

1. **Mechanical audit.** 31 docs under `sources/{guides,investigations,incidents}`
   were audited by parallel sub-agents (Sonnet 4.5), one JSON verdict per doc:
   every path/symbol/command/version/URL classified EXISTS / MOVED / GONE /
   UNVERIFIABLE with the command + output as evidence, checked against
   `origin/HEAD` of the real repos via the `librarian` checkout script.
   Verdicts: 8 CURRENT, 6 MOSTLY_CURRENT, 1 PARTLY_STALE, 8 STALE, 9 TIMELESS
   (lesson survives, code moved). The single most common cause of rot: the
   `virdx/data-platform` archive (2026-05-27) → `mono` (`apps/api` →
   `apps/vxdata-api`, `apps/worker` → `apps/vxdata-jobs`, `packages/client` →
   `packages/vxdata-sdk`).
2. **Promotion.** 10 new pages written from the surviving content with corrected
   paths: `infrastructure/sops/{vxdata-sdk-and-schema-model, vxdata-jobs-ingestion,
conda-packaging-and-releases, keel-auto-redeploy, coder-workspaces,
dashboard-histo-tile-serving, vxconvert-dicom-to-bids, phi-safe-data-handling}`,
   new `histo/sops/{histo-preprocessing-performance, viseg-inference}` (+ a
   `histo/sops/index.md`, the first one), and
   `infrastructure/self-hosted-inference.md`. Cluster/incident lessons were
   appended to the existing gotchas and executing-jobs SOPs instead of becoming
   new pages; the 12KB dashboard-metrics guide was compressed into the existing
   dashboard SOP.
3. **Deletion + relink.** `sources/{guides,investigations,incidents}` removed
   entirely; all inbound `wiki/` links rewritten to the new locations; every
   internal link in the repo re-verified from scratch. `sources/` now holds
   monthly reports only, and `index.md` says so.
4. **Formatting enforcement.** `.lefthook.yaml` (prettier 3.6.2 on staged
   markdown) already existed, but nothing told a new clone to run
   `lefthook install` and nothing caught `--no-verify`. Added
   `.github/workflows/format.yml` (`prettier --check "**/*.md"`, same pinned
   version) and a `lefthook install` line to the README setup.

## Lessons Learned: Pitfalls

- **`sources/` was not inert legacy — `wiki/` depended on it.** Six `wiki/`
  pages linked into it, including `virdx/index.md` pointing at the
  `sources/*/index.md` files as "where to look for more". Deleting the tree
  without the relink pass would have broken navigation from the top-level
  orientation page. Any future prune should start with
  `rg "sources/" wiki index.md`.
- **Stale docs were confidently specific, which is what made them dangerous.**
  `vxdata-sdk-and-local-dev.md` stated `1.0.x` / pin `>=1.0,<2` while both
  packages are at `2.1.0`; `vxdata-production-deployment.md` asserted an
  ownership split (`mono/apps/vxdata-api/deployments/k8s`) that no longer exists
  — `infra_k8s/current/vxdata-production/` owns all runtime manifests. Neither
  doc looked stale from the inside.
- **`type: Guide` + a plausible path is not evidence.** Only the per-claim
  re-check against the repos separated the 9 TIMELESS docs (keep the lesson,
  throw away the paths) from the 8 STALE ones (the machinery itself is gone:
  buildah workflows, the local registry mirror, the `ollama` deployment, VALIS).
- **A dev bearer token had been written into a guide.** The promoted page now
  points at `principals.example.json` instead. Worth grepping for token-shaped
  strings when promoting older material.

## Lessons Learned: Improvements

- **Record the `data-platform` → `mono` rename map once, prominently.** Nearly
  every stale path in the audit was mechanically derivable from three renames.
  It is now stated in the promoted pages; `wiki/workstreams/infrastructure/index.md`
  would be a better single home for it.
- **Date every claim that can rot.** The pages that survived intact were the
  ones with a version, PR number, or "verified <date>" attached; the ones that
  rotted silently had bare present-tense assertions. New wiki pages carry
  "verified 2026-08-06" markers on the volatile parts — keep that habit.
- **`sources/` should not be re-grown.** `index.md` now says episodic material
  goes to `inbox/` and durable knowledge to `wiki/`. If a future agent wants a
  point-in-time write-up, it belongs in `inbox/` until the dreamer synthesizes
  it.
- **Two things were deliberately left alone.** Monthly reports (point-in-time
  records that cannot go stale by definition) stay under `sources/`, and
  `raycast-pi-try-launcher.md` was deleted as personal tooling rather than VIRDX
  knowledge. Both are judgment calls a future maintainer may want to revisit.
- **The audit artifacts are reproducible, not saved.** Per-doc JSON verdicts
  lived in `/tmp/kb-audit/` and were not committed. If a periodic staleness
  sweep becomes routine, that JSON contract is the thing to formalize.

Source: https://docs.virdx.dev/knowledge/inbox/2026-08-06-infrastructure-sources-audit-and-wiki-promotion/index.mdx