felt: record docs work — versioning, cluster tree, rescued v2.0 plan

Three fibers from this session's docs work:
- docs-versioning: the versioned-site + switcher design (#738) and the
  recurring unexercised-path bit-rot pattern.
- docs-cluster-tree: the machine-specific clusters.md decision (#739) and why
  a single page beat a thin standalone general page.
- v2-run-plan: the v2.0 run wishlist rescued from the deleted
  work_flow_v2.0.md docs page before removal.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: cailmdaley

.felt/shapepipe/docs-cluster-tree/docs-cluster-tree.md

@@ -0,0 +1,8 @@
+---
+name: Machine-specific cluster docs tree + freshness pass
+tags:
+    - shapepipe
+    - docs
+created-at: 2026-05-31T22:15:20.539028984+02:00
+outcome: 'PR #739 (off develop): introduced a single clusters.md (general pattern + candide/CANFAR/ccin2p3 sections) under a ''Running on a cluster'' toctree caption — chosen over a standalone general page (too thin: shared content is ~3 paragraphs, submission models diverge) and over per-machine pages (canfar walkthrough would unbalance). Deleted obsolete canfar.md/pipeline_v2.0.md/work_flow_v2.0.md (planning rescued to [[shapepipe/v2-run-plan]]); kept pipeline_canfar.md as the linked deep CANFAR walkthrough. Rewrote dependencies.md against pyproject (SSOT framing, ngmix fork, dropped CDSclient); stripped removed rho-stats + dead prepare_tiles_for_final from post_processing/random_cat; cosmetics. Audit found install/container/testing/API pages already fresh. Local sphinx build green. Sequencing: candide section assumes #737''s SLURM scripts; publishability needs [[shapepipe/docs-versioning]] (#738).'
+---

.felt/shapepipe/docs-versioning/docs-versioning.md

@@ -0,0 +1,54 @@
+---
+name: Versioned docs site with a version switcher
+tags:
+    - shapepipe
+    - docs
+    - ci
+created-at: 2026-05-31T20:39:06.459699229+02:00
+outcome: 'PR #738 (off develop): docs site now versioned — stable@root (non-destructive to existing URLs), develop@/latest/, tags@/vX.Y.Z/, switcher.json drives the dropdown. Fixes that the site published only from master (~78 commits behind) so container.md/canfar.md were never published. CI green incl. real dev-image build + PR-preview artifact.'
+---
+
+## Why
+
+`cd.yml` published the Sphinx site only on push to `master`, which sits ~78
+commits behind `develop`. So the public docs described a stale release while
+everyone runs `develop`, and six pages written on `develop` — `container.md`,
+`canfar.md`, four others — had **never been published** (`container.html` →
+404). Surfaced when checking where the README's container link would land.
+
+## Design
+
+Versioned, not just "publish from develop." gh-pages layout is **additive**:
+`master`→ site **root** (stable; keeps every existing `/installation.html`-style
+URL working), `develop`→ `/latest/`, tags `v*`→ `/<tag>/`. A root `switcher.json`
+(tracked in `docs/`) drives the pydata/`sphinx-book-theme` dropdown;
+`DOCS_VERSION` (set by the workflow per ref) tells `conf.py` which entry to
+highlight. Each deploy uses `keep_files: true`, so it only writes its own slice
+and never clobbers siblings — every step is non-destructive, including the first
+`develop` run (adds `/latest/` + `switcher.json`, leaves root untouched).
+
+**Per-ref builds, not `sphinx-multiversion`.** autodoc imports `shapepipe`, so an
+old tag must build against *its own* deps. Multiversion uses one shared env
+across all refs → breaks autodoc on old tags. Building each ref in its own dev
+image at its own time sidesteps that entirely. PRs touching docs build + upload
+the HTML as an artifact but don't deploy → broken builds caught pre-merge,
+reviewers get a preview. `conf.py` version now comes from package metadata
+(killed the hand-maintained `1.0.1`, actual is `1.1.0`).
+
+## The recurring bit-rot pattern
+
+Same shape as [[shapepipe/mpi-hybrid]]: a path the repo's CI never exercises
+silently rots, and *enabling* it surfaces the breakage. Here, the docs build
+only ever ran on `master` (old flat layout), so `sphinx-apidoc … shapepipe`
+went stale when the package moved to src-layout (`src/shapepipe`); the first
+`develop` build failed `/app/shapepipe is not a directory`. Fixed to
+`src/shapepipe`. The lesson keeps repeating — unexercised paths (MPI, docs
+deploy) drift undetected; the fix is to *run them in CI*, which this PR now does
+for docs on every push and every docs-touching PR.
+
+## Follow-ups (not in PR)
+
+Seed `switcher.json` with the first real release entry when the next version is
+tagged; one-time `master` release to refresh root with current docs. Policy
+nod: the site now publishes `develop` as `latest`, so in-development docs are
+publicly visible — right for an active pipeline, but a conscious shift.

.felt/shapepipe/v2-run-plan/v2-run-plan.md

@@ -0,0 +1,30 @@
+---
+name: v2.0 ShapePipe run — workflow wishlist
+tags:
+    - shapepipe
+    - planning
+created-at: 2026-05-31T22:09:28.586302759+02:00
+outcome: Forward-looking design wishlist for a future 'v2.0' production run, rescued from the obsolete docs/source/work_flow_v2.0.md before deletion (it was an unrealized plan sitting in published docs). Not yet implemented.
+---
+
+## The wishlist (from work_flow_v2.0.md, 2020-era)
+
+A future "v2.0" run was sketched with these goals — none yet implemented; kept
+here so the intent isn't lost when the stale docs page is removed:
+
+- **Run per tile** — pipeline runs a single tile end-to-end, or to any
+  user-specified stopping point.
+- **Central exposure store** — used exposures stored once in a central place and
+  linked from each tile, rather than the current mix of per-patch central storage
+  and per-tile copies.
+- **Drop the patch organisation** — runs no longer organised into patches.
+- **Use `/scratch`** for processing speed.
+- **Smarter file layout** — ~20000 tiles and a few ×10⁴ single-HDU exposure files
+  need subdir bucketing, e.g. `tiles/123/123.456`, `exp/12/…`.
+- **Metadata over symlinks** — replace the symlink-based "used exposures per tile"
+  with a YAML (or DB) manifest.
+- **Update ngmix** (can come later).
+- **External detection catalogue** — replace SExtractor detection on tiles with an
+  external ASCII catalogue; still run SExtractor on exposures to identify stars.
+- **Remove spread-model (SM)** — note: `spread_model` still exists in the code as
+  of 2026-05, so this remains unrealized.