diff --git a/.claude/visibility b/.claude/visibility
new file mode 100644
index 0000000..a48cf0d
--- /dev/null
+++ b/.claude/visibility
@@ -0,0 +1 @@
+public
diff --git a/CLAUDE.md b/CLAUDE.md
index 1eeb40b..8fddd39 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -186,93 +186,37 @@ ssh m1 'cd /Users/airvine/Projects/repo/fresh && Rscript -e "
 <!-- BEGIN SOUL CONVENTIONS — DO NOT EDIT BELOW THIS LINE -->
 
 
-# Cartography
+# CI Monitoring
 
-## Style Registry
+When this repo has GitHub Actions workflows, scan recent runs on session start. Catches failed pkgdown deploys, broken vignette builds, and stale citation regenerations that would otherwise linger until the user manually checks.
 
-Use the `gq` package for all shared layer symbology. Never hardcode hex color values when a registry style exists.
+## On Session Start
 
-```r
-library(gq)
-reg <- gq_reg_main()  # load once per script — 51+ layers
-```
-
-**Core pattern:** `reg$layers$lake`, `reg$layers$road`, `reg$layers$bec_zone`, etc.
-
-### Translators
-
-| Target | Simple layer | Classified layer |
-|--------|-------------|-----------------|
-| tmap | `gq_tmap_style(layer)` → `do.call(tm_polygons, ...)` | `gq_tmap_classes(layer)` → field, values, labels |
-| mapgl | `gq_mapgl_style(layer)` → paint properties | `gq_mapgl_classes(layer)` → match expression |
-
-### Custom styles
-
-For project-specific layers not in the main registry, use a hand-curated CSV and merge:
-
-```r
-reg <- gq_reg_merge(gq_reg_main(), gq_reg_read_csv("path/to/custom.csv"))
+```bash
+gh run list --limit 5 --json status,conclusion,name,createdAt,databaseId \
+  --jq '.[] | select(.conclusion == "failure")'
 ```
 
-Install: `pak::pak("NewGraphEnvironment/gq")`
-
-## Map Targets
-
-| Output | Tool | When |
-|--------|------|------|
-| PDF / print figures | `tmap` v4 | Bookdown PDF, static reports |
-| Interactive HTML | `mapgl` (MapLibre GL) | Bookdown gitbook, memos, web pages |
-| QGIS project | Native QML | Field work, Mergin Maps |
+If any failures since the last visit, surface to the user before starting other work:
 
-## Key Rules
+> Workflow `<name>` failed `<time>` ago (run `<id>`). Investigate with `gh run view <id> --log-failed`. Fix or proceed with current task?
 
-- **`sf_use_s2(FALSE)`** at top of every mapping script
-- **Compute area BEFORE simplify** in SQL
-- **No map title** — title belongs in the report caption
-- **Legend over least-important terrain** — swap legend and logo sides when it reduces AOI occlusion. No fixed convention for which side.
-- **Four-corner rule** — legend, logo, scale bar, keymap each get their own corner. Never stack two in the same quadrant.
-- **Bbox must match canvas aspect ratio** — compute the ratio from geographic extents and page dimensions. Mismatch causes white space bands.
-- **Consistent element-to-frame spacing** — all inset elements should have visually equal margins from the frame edge
-- **Map fills to frame** — basemap extends edge-to-edge, no dead bands. Use near-zero `inner.margins` and `outer.margins`.
-- **Suppress auto-legends** — build manual ones from registry values
-- **ALL CAPS labels appear larger** — use title case for legend labels (gq `gq_tmap_classes()` handles this automatically via `to_title()` fallback)
+User decides; do not auto-fix.
 
-## Self-Review (after every render)
+## Particular Failures Worth Naming
 
-Read the PNG and check before showing anyone:
+- **pkgdown** — docs site on GitHub Pages broken
+- **R-CMD-check** — package may not install
+- **Vignette / build-vignettes** — vignette docs incomplete
+- **update-citation-cff** — CITATION.cff stale
 
-1. Correct polygon/study area shown? (verify source data, not just the bbox)
-2. Map fills the page? (no white/black bands)
-3. Keymap inside frame with spacing from edge?
-4. No element overlap? (each in its own corner)
-5. Legend over least-important terrain?
-6. Consistent spacing across all elements?
-7. Scale bar breaks appropriate for extent?
+## Why This Matters
 
-See the `cartography` skill for full reference: basemap blending, BC spatial data queries, label hierarchy, mapgl gotchas, and worked examples.
+Without this scan, post-merge workflow failures linger until someone (often the user) notices a stale docs site or a missing vignette. The session-start sweep catches them on the first re-entry into the repo.
 
-## Land Cover Change
+## Pairs with `/gh-pr-merge`
 
-Use [drift](https://github.com/NewGraphEnvironment/drift) and [flooded](https://github.com/NewGraphEnvironment/flooded) together for riparian land cover change analysis. flooded delineates floodplain extents from DEMs and stream networks; drift tracks what's changing inside them over time.
-
-**Pipeline:**
-
-```r
-# 1. Delineate floodplain AOI (flooded)
-valleys <- flooded::fl_valley_confine(dem, streams)
-
-# 2. Fetch, classify, summarize (drift)
-rasters   <- drift::dft_stac_fetch(aoi, source = "io-lulc", years = c(2017, 2020, 2023))
-classified <- drift::dft_rast_classify(rasters, source = "io-lulc")
-summary    <- drift::dft_rast_summarize(classified, unit = "ha")
-
-# 3. Interactive map with layer toggle
-drift::dft_map_interactive(classified, aoi = aoi)
-```
-
-- Class colors come from drift's shipped class tables (IO LULC, ESA WorldCover)
-- For production COGs on S3, `dft_map_interactive()` serves tiles via titiler — set `options(drift.titiler_url = "...")`
-- See the [drift vignette](https://www.newgraphenvironment.com/drift/articles/neexdzii-kwa.html) for a worked example (Neexdzii Kwa floodplain, 2017-2023)
+The skill watches workflows triggered by a fresh merge in real time — that's the targeted catch. This convention is the backstop for failures that landed when no one was watching (merges via web UI, scheduled triggers, manually-triggered workflows).
 
 
 # Code Check Conventions
@@ -287,6 +231,16 @@ Add new checks here when a bug class is discovered — they compound over time.
 - `"echo '${VAR}'"` — if VAR contains `'`, shell syntax breaks
 - Use `printf '%s\n' "$VAR" | command` to pipe values safely
 - Heredocs: unquoted `<<EOF` expands variables locally, `<<'EOF'` does not — know which you need
+- Pass-through-ssh args: `printf '%q'` escapes per-arg so workload paths with spaces / quotes / metacharacters survive the local-shell → ssh-argv → remote-shell round-trip. Without it, `ssh host 'cmd' "$path"` joins args with spaces on remote and re-parses, losing argument boundaries.
+
+### Heredoc precedence in pipelines
+- `cmd1 | cmd2 <<EOF` — the heredoc binds to `cmd2` (the rightmost simple command). If you intended `cmd1` to receive it, put `<<EOF` on cmd1 explicitly: `cmd1 <<EOF | cmd2`.
+- Symptom when wrong: ssh body silently echoed by tee/cat/etc, ssh side gets empty stdin, exits 0 (or near-0) without doing anything. Caught the hard way 2026-05-01 in cypher_restore-fwapg.sh.
+
+### pipefail with ssh+tee
+- `set -eu` does NOT propagate exit codes through pipelines. `ssh ... | tee log` returns tee's exit (always 0 for healthy tee), masking ssh failure.
+- Use `set -euo pipefail` for any script that pipes a meaningful command into tee/cat/grep/etc. Or check `${PIPESTATUS[0]}` explicitly.
+- Symptom when wrong: task notifications report "exit 0 / completed" while remote work was actually skipped or errored.
 
 ### Paths
 - Hardcoded absolute paths (`/Users/airvine/...`) break for other users
@@ -309,13 +263,43 @@ Add new checks here when a bug class is discovered — they compound over time.
 - Must be pure ASCII — em dashes, curly quotes, arrows cause silent parse failure
 - Check with: `perl -ne 'print "$.: $_" if /[^\x00-\x7F]/' file.yaml`
 
+### YAML flow-mapping in runcmd
+- Any runcmd item containing both `{` and `:` is at risk of being parsed as a YAML flow-mapping (dict), not a literal string. Cloud-init's shellify hits a non-string and throws TypeError, **aborting all subsequent runcmd steps silently** while `final_message` still fires.
+- Don't write: `- test -s /file || { echo "FATAL: ..." }` — the `:` inside braces makes YAML see a dict.
+- Do write: use `- |` block scalar with explicit `if/then/fi`:
+  ```yaml
+  - |
+    if [ ! -s /file ]; then
+      echo "FATAL: ..." >&2
+      exit 1
+    fi
+  ```
+- Validate post-edit: `python3 -c "import yaml; runcmd=yaml.safe_load(open('cloud-init.yaml').read().split(chr(10),1)[1])['runcmd']; print([type(x).__name__ for x in runcmd if not isinstance(x,str)] or 'all strings')"`. If the output is anything other than `all strings`, the runcmd will fail.
+
 ### State
 - `cloud-init clean` causes full re-provisioning on next boot — almost never what you want before snapshot
 - Use `tailscale logout` not `tailscale down` before snapshot (deregister vs disconnect)
+- Wipe `/var/lib/tailscale/*` before snapshot too — `tailscale logout` deauthorizes server-side but local node identity blob persists in tailscaled.state. Snapshot restored elsewhere inherits prior key material until `tailscale up` runs again.
+- Wipe `/etc/ssh/ssh_host_*` before snapshot — otherwise droplets spawned from the same image share host identity.
 
 ### Template Variables
 - Secrets rendered via `templatefile()` are readable at `169.254.169.254` metadata endpoint
 - Acceptable for ephemeral machines, document the tradeoff
+- Heredocs in runcmd that write secrets: `<<'EOF'` (quoted) prevents bash from re-expanding `$X` sequences in already-substituted credential strings. AWS keys rarely contain `$` but base64-padded secrets might.
+
+### Repo + key install ordering
+- `apt-key adv --keyserver` is deprecated on Ubuntu 24.04 noble — silently fails AND APT ignores resulting keyring. Use `gpg --dearmor` + `signed-by=` keyring file pattern.
+- Repo .list files in `write_files:` trigger the implicit `package_update` BEFORE runcmd installs the keyring → first apt-get update fails with NO_PUBKEY. Put the repo line in runcmd alongside the key install, not in write_files.
+
+### Cloud-init users vs DO SSH key injection
+- DO injects `ssh_key_ids` only into `/root/.ssh/authorized_keys` (cloud-init's `cc_ssh` module). Cloud-init `users:` block with `ssh_authorized_keys: []` does NOT pick those up.
+- Non-root users that need SSH access must copy from root's keys in runcmd:
+  ```yaml
+  - mkdir -p /home/<user>/.ssh
+  - cp /root/.ssh/authorized_keys /home/<user>/.ssh/authorized_keys
+  - chown -R <user>:<user> /home/<user>/.ssh
+  ```
+- Guard with `test -s /root/.ssh/authorized_keys` to fail loudly if `cc_ssh` hasn't run before runcmd (rare race).
 
 ## OpenTofu / Terraform
 
@@ -327,7 +311,50 @@ Add new checks here when a bug class is discovered — they compound over time.
 ### Destructive Operations
 - Validate resource IDs before destroy: `[ -n "$ID" ] || exit 1`
 - `tofu destroy` without `-target` destroys everything including reserved IPs
-- Snapshot ID extraction: use `--resource droplet` and `grep -F` for exact match
+- Snapshot ID extraction by name: use `awk -v n="$NAME" '$2 == n {print $1}'` (exact match on column 2). `grep -F "$NAME"` is substring-match and can grab a stale snapshot whose name contains the new name as a substring.
+
+## DigitalOcean
+
+### Snapshot disk-size constraint
+- DO snapshots include the source droplet's disk size. New droplets from a snapshot must have disk **>=** snapshot disk. Resize **up** is fine; resize **down** below the snapshot disk is impossible without rebuilding.
+- Build the snapshot at the smallest droplet size you'd ever want to spin from it. Sizes vs disks at writing: `g-4vcpu-16gb` = 50 GB, `g-8vcpu-32gb` / `m-4vcpu-32gb` = 100 GB, `m-8vcpu-64gb` = 200 GB.
+- If your workload requires X GB RAM minimum, your snapshot floor is whatever droplet has X GB AND the smallest disk class.
+
+### Reserved IP detach behavior
+- Targeted destroy (`tofu destroy -target=module.droplet -target=...assignment...`) preserves the reserved IP at $4/mo. Full `tofu destroy` releases it (next apply gets a NEW IP).
+
+### Reserved IP assignment race (rtj#55, rtj#85)
+- DO returns 422 "Droplet already has a pending event" when reserved IP assignment fires immediately after droplet+firewall creation. The droplet's internal event queue takes time to drain.
+- **Every DO droplet module that uses a reserved IP MUST have:**
+  1. `time_sleep` resource between droplet creation and IP assignment, with `create_duration ≥ 60s` (10s and 30s have both been observed to race; 60s has more headroom)
+  2. `depends_on = [time_sleep.<name>]` on the `digitalocean_reserved_ip_assignment` resource
+  3. A retry fallback in the wrapping shell script (`up.sh` style) that detects the 422 in tofu output and uses `doctl compute reserved-ip-action assign <ip> <droplet-id>` to recover. Tofu doesn't retry; it leaves state half-applied (assignment recorded but DO didn't actually attach).
+- **Snapshot-based spins are MORE prone to the race** than first-boot from blank Ubuntu (more startup events compete for the droplet's event queue).
+- **Audit existing modules:** `grep -L 'time_sleep' env/do/*/<host>/main.tf` finds modules missing the gate. As of 2026-05-02, openclaw and geoserv have no `time_sleep` — they will race eventually.
+
+## Docker / Postgres
+
+### Postgis init time
+- `imresamu/postgis` (and similar postgis images) on first cold start (empty data volume) take **5-12 min** to install all extensions — varies with disk IO and noisy-neighbor lottery on cloud hosts. Health-wait scripts must allow 15 min minimum, ideally with hard-fail + log dump on timeout.
+
+### Tuning vs host RAM
+- fresh's `docker/docker-compose.yml` defaults are tuned for a 128 GB host (`shared_buffers=32GB`, `shm_size=36gb`). On smaller hosts, postgres OOMs at startup with "could not map anonymous shared memory".
+- 32 GB host floor: use the M1/cypher 32 GB-host preset (`scripts/fwapg/compose.override.m1.yml`) which sets `shared_buffers=8GB, shm_size=12gb`.
+- Below 32 GB: postgres can technically start with smaller `shared_buffers` but fwapg work becomes painful. Don't run fwapg pipelines on <32 GB hosts.
+
+### `search_path` is data, not config
+- `ALTER DATABASE <db> SET search_path TO ...` is a database-level setting **stored in the postgres data dir**. Wiped with `docker compose down -v`. Must be re-applied on every restore.
+- Codify in your restore script, not in cloud-init or compose env (those don't apply to db-level settings).
+
+## Tailscale
+
+### ACL "users" semantics
+- Tailscale SSH ACL `"users": ["autogroup:nonroot"]` for `tag:compute` blocks `ssh root@<node>` over the tailnet. Use `ssh <user>@<node>` + sudo for root operations.
+- For SSH-as-root from off-tailnet (regular OpenSSH on the public IP), the ACL doesn't apply — but you need the SSH key registered on the node.
+
+### Reusable + ephemeral auth keys
+- Cypher-style ephemeral compute droplets need both flags on the auth key: **Reusable** (same key works across destroy/recreate) + **Ephemeral** (tailnet entries auto-clean when offline >5 min).
+- Tag the key (e.g. `tag:compute`) at creation time. Nodes joining with that key inherit the tag automatically — no `--advertise-tags` needed at `tailscale up` time.
 
 ## Security
 
@@ -358,72 +385,91 @@ Add new checks here when a bug class is discovered — they compound over time.
 
 ## General
 
+### Adopting Existing Config
+
+When importing config from one location into a canonical one (legacy `~/.bash_profile` → dotfiles repo, old script's env → repo, another project's `settings.json` → soul):
+
+- **Verify every referenced path/binary exists.** Dead PATH exports, missing interpreters, stale env vars should be cut, not codified.
+  Shell paths: `for p in $(echo "$PATH" | tr ':' ' '); do [ -d "$p" ] || echo "DEAD: $p"; done`
+- **Ask before dropping a reference** — it may be something the user forgot to reinstall on this machine, not something to delete.
+- **Curated subset, not verbatim copy.** The diff should reflect what you verified, not the whole source.
+
 ### Documentation Staleness
 - Moving/renaming scripts: update CLAUDE.md, READMEs, usage comments
 - New variables: update .tfvars.example
 - New workflows: update relevant README
 
 
-# Communications Conventions
+# Comms Conventions
 
-Standards for external communications across New Graph Environment.
+This repo has a `comms/` directory — you're in the cross-repo Claude-to-Claude messaging system. Full protocol in `comms/README.md`. Peer list (who to scan) in `soul/conventions/comms_peers.md` (internal-only). Load-bearing behaviors below.
 
-[compost](https://github.com/NewGraphEnvironment/compost) is the working repo for email drafts, scripts, contact management, and Gmail utilities. These conventions capture the universal principles; compost has the implementation details.
+## On Session Start
 
-## Tone
+1. **Inbound scan.** `<this-repo>/comms/*/` — files with `status: open` and mtime newer than your last `comms/` commit are mail for you.
+2. **Outbound scan.** For each peer in `comms_peers.md`, check `<peer>/comms/<this-repo>/*.md` — files with `from: <this-repo>, status: open` are your un-answered sent mail.
 
-Three levels. Default to casual unless context dictates otherwise.
+If either surfaces open threads, raise to the user before starting other work.
 
-| Level | When | Style |
-|-------|------|-------|
-| **Casual** | Established working relationships | Professional but warm. Direct, concise. No slang. |
-| **Very casual** | Close collaborators with rapport | Colloquial OK. Light humor. Slang acceptable. |
-| **Formal** | New contacts, senior officials, formal requests | Full sentences, no contractions, state purpose early. |
+## Commit Prefix
 
-**Collaborative, not directive.** Acknowledge their constraints:
+- `comms(→peer):` — you committed a file in peer's repo (outbound)
+- `comms(←peer):` — you committed a file in your own repo (inbound reply)
+- `comms:` — meta (close, reopen, rename, README update)
 
-- **Avoid:** "Work these in as makes sense for your lab"
-- **Better:** "If you're able to work these in when it fits your schedule that would be really helpful"
+Arrow points to the repo whose `comms/` contains the file you committed.
 
-## Email Workflow
+## Non-negotiables
 
-Draft in markdown, convert to HTML at send time via gmailr. See compost for script templates, OAuth setup, and `search_gmail.R`.
+- One commit per appended message.
+- **Push immediately.** Un-pushed comms is invisible to the other Claude.
+- Code + comms = separate commits.
+- Status flips bundle with the triggering message.
+- **Use `git commit --only <file>`** for any commit in a peer's repo (thread files). Immune to index races from parallel sessions.
 
-**File naming:** `YYYYMMDD_recipient_topic_draft.md` + `YYYYMMDD_recipient_topic.R`
+## Propagation: soul publishes, peers pull
 
-**Key gotchas** (documented in detail in compost):
-- Gmail strips `<style>` blocks — use inline styles for tables
-- `gm_create_draft()` does NOT support `thread_id` — only `gm_send_message()` can reply into threads. Drafts land outside the conversation.
-- Always use `test_mode` and `create_draft` variables for safe workflows
+Soul is the source of truth for `comms/README.md`. Peers sync by running `/comms-init` in their own repo, from their own Claude session. **Do not push README updates into a peer's repo from another session** — cross-session index races can bundle unrelated staged files into misleading commits.
 
-## Data in Emails
+Within your own session, the only things you commit into a peer's repo are **thread files** (hosted in the receiver's repo per the receiver-hosts rule). Everything else — README syncs, infra — the peer-Claude pulls itself.
 
-- **Never manually type data into tables** — generate programmatically from source files
-- **Link to canonical sources** (GitHub repos, public reports) rather than embedding raw data
-- **Provide both CSV and Excel** when sharing tabular data
-- **Document ID codes** — when using compressed IDs (e.g., `id_lab`), include a reference sheet so recipients can decode
+### Cross-repo thread commits: which branch?
 
-## What Not to Expose Externally
+Commit on peer's **current branch** — whatever they've got checked out. Don't stash, switch, or force main.
 
-- Internal QA info (blanks, control samples, calibration data)
-- Internal tracking codes or SRED references
-- Draft status or revision history
-- Internal project management details
+If peer isn't on main, surface to the user: _"thread landing on `<peer>`:`<branch>`, won't hit main until PR merges. Continue or hold?"_ If peer has complicated local state (mid-rebase, partial merge), defer to the user.
 
-Keep client-facing communications focused on deliverables and technical content.
 
-## Signature
+# NGE Feature Workflow
 
-```
-Al Irvine B.Sc., R.P.Bio.
-New Graph Environment Ltd.
+For non-trivial issue-driven work, follow this checklist. Each step exists for a reason — skipping leads to rework, broken builds, and avoidable bugs that we've hit repeatedly.
 
-Cell: 250-777-1518
-Email: al@newgraphenvironment.com
-Website: www.newgraphenvironment.com
-```
+## The Sequence
+
+1. **Start with `/planning-init <N>`** — given an issue number, enters plan mode for codebase exploration, presents a phase breakdown for user approval, then scaffolds branch + PWF baseline with the approved phases. One command replaces the manual issue → explore → plan → branch → scaffold dance.
+2. **Write robust tests first** — failing tests that reproduce the issue or document the new behavior. Tests are the contract; they fail until the work makes them pass.
+3. **Name with intent** — functions, parameters, internal helpers carry the naming style of the package they live in. Look at existing exports as the guide; consistency over cleverness. (Per-package naming convention TBD — see soul issue tracking.)
+4. **Examples that run** — every exported function gets a runnable `@examples` block. Pkgdown renders them; CI executes them. An example that doesn't run is documentation rot.
+5. **Code-check before each commit** — `/code-check` on staged diff. Catches what tests miss: edge cases, hard-coded paths, unguarded variables, security issues.
+6. **Atomic commits** — each commit bundles code change + checkbox flip in `task_plan.md`. The diff and the progress live in the same commit; `git log -- planning/` tells the full story.
+7. **`/planning-archive` when complete** — moves PWF to `archive/YYYY-MM-issue-N-slug/`, creates a fresh `active/`. Then `/gh-pr-push` opens the PR; `/gh-pr-merge` handles the release bookkeeping.
+
+## When to Skip
+
+For one-line typo fixes, version-bump-only PRs, or trivial documentation edits, the full workflow is overhead. Use judgment. The threshold is roughly: **multi-step issue, multi-file change, or anything that requires scoping** → use the workflow.
 
-In HTML emails, use `<br>` tags between lines.
+## Skills That Slot In
+
+- `/planning-init <N>` — start
+- `/planning-update` — sync checkboxes mid-session
+- `/code-check` — before every commit
+- `/planning-archive` — when issue closes
+- `/gh-pr-push` — open the PR
+- `/gh-pr-merge` — merge with release bookkeeping
+
+## Why This Exists
+
+We've hit snags repeatedly when half-doing this — branches that mix concerns, tests bolted on after, code-check skipped (and then a bug ships in the diff), examples that fail in pkgdown. Each step is small; the cumulative reliability gain is real. The convention is here so it becomes the default expectation, not a thing the user has to remind every session about.
 
 
 # LLM Behavioral Guidelines
@@ -497,151 +543,6 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
 **These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
 
 
-# New Graph Environment Conventions
-
-Core patterns for professional, efficient workflows across New Graph Environment repositories.
-
-## Ecosystem Overview
-
-Five repos form the governance and operations layer across all New Graph Environment work:
-
-| Repo | Purpose | Analogy |
-|------|---------|---------|
-| [compass](https://github.com/NewGraphEnvironment/compass) | Ethics, values, guiding principles | The "why" |
-| [soul](https://github.com/NewGraphEnvironment/soul) | Standards, skills, conventions for LLM agents | The "how" |
-| [compost](https://github.com/NewGraphEnvironment/compost) | Communications templates, email workflows, contact management | The "who" |
-| [rtj](https://github.com/NewGraphEnvironment/rtj) (formerly awshak) | Infrastructure as Code, deployment | The "where" |
-| [gq](https://github.com/NewGraphEnvironment/gq) | Cartographic style management across QGIS, tmap, leaflet, web | The "look" |
-
-**Adaptive management:** Conventions evolve from real project work, not theory. When a pattern is learned or refined during project work, propagate it back to soul so all projects benefit. The `/claude-md-init` skill builds each project's `CLAUDE.md` from soul conventions.
-
-**Cross-references:** [sred-2025-2026](https://github.com/NewGraphEnvironment/sred-2025-2026) tracks R&D activities across repos. Compost cross-cuts all projects as the centralized communications workflow — email drafts, contact registry, and tone guidelines live there and are copied to individual project `communications/` folders as needed.
-
-## Issue Workflow
-
-### Before Creating an Issue (non-negotiable)
-
-1. **Check for duplicates:** `gh issue list --state open --search "<keywords>"` -- search before creating
-2. **Link to SRED:** If work involves infrastructure, R&D, tooling, or performance benchmarking, add `Relates to NewGraphEnvironment/sred-2025-2026#N` (match by repo name in SRED issue title)
-3. **One issue, one concern.** Keep focused.
-
-### Professional Issue Writing
-
-Write issues with clear technical focus:
-
-- **Use normal technical language** in titles and descriptions
-- **Focus on the problem and solution** approach
-- **Add tracking links at the end** (e.g., `Relates to Owner/repo#N`)
-
-**Issue body structure:**
-```markdown
-## Problem
-<what's wrong or missing>
-
-## Proposed Solution
-<approach>
-
-Relates to #<local>
-Relates to NewGraphEnvironment/sred-2025-2026#<N>
-```
-
-### GitHub Issue Creation - Always Use Files
-
-The `gh issue create` command with heredoc syntax fails repeatedly with EOF errors. ALWAYS use `--body-file`:
-
-```bash
-cat > /tmp/issue_body.md << 'EOF'
-## Problem
-...
-
-## Proposed Solution
-...
-EOF
-
-gh issue create --title "Brief technical title" --body-file /tmp/issue_body.md
-```
-
-## Closing Issues
-
-**DO:** Close issues via commit messages. The commit IS the closure and the documentation.
-
-```
-Fix broken DEM path in loading pipeline
-
-Update hardcoded path to use config-driven resolution.
-
-Fixes #20
-Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
-```
-
-**DON'T:** Close issues with `gh issue close`. This breaks the audit trail — there's no linked diff showing what changed.
-
-- `Fixes #N` or `Closes #N` — auto-closes and links the commit to the issue
-- `Relates to #N` — partial progress, does not close
-- Always close issues when work is complete. Don't leave stale open issues.
-
-## Commit Quality
-
-Write clear, informative commit messages:
-
-```
-Brief description (50 chars or less)
-
-Detailed explanation of changes and impact.
-
-Fixes #<issue> (or Relates to #<issue>)
-Relates to NewGraphEnvironment/sred-2025-2026#<N>
-
-Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
-```
-
-**When to commit:**
-- Logical, atomic units of work
-- Working state (tests pass)
-- Clear description of changes
-
-**What to avoid:**
-- "WIP" or "temp" commits in main branch
-- Combining unrelated changes
-- Vague messages like "fixes" or "updates"
-
-## LLM Agent Conventions
-
-Rules learned from real project sessions. These apply across all repos.
-
-- **Install missing packages, don't workaround** — if a package is needed, ask the user to install it (e.g. `pak::pak("pkg")`). Don't write degraded fallback code to avoid the dependency.
-- **Never hardcode extractable data** — if coordinates, station names, or metadata can be pulled from an API or database at runtime, do that. Don't hardcode values that have a programmatic source.
-- **Close issues via commits, not `gh issue close`** — see Closing Issues above.
-- **Cite primary sources** — see references conventions.
-
-## Naming Conventions
-
-**Pattern: `noun_verb-detail`** -- noun first, verb second across all naming:
-
-| What | Example |
-|------|---------|
-| Skills | `claude-md-init`, `gh-issue-create`, `planning-update` |
-| Scripts | `stac_register-baseline.sh`, `stac_register-pypgstac.sh` |
-| Logs | `20260209_stac_register-baseline_stac-dem-bc.txt` |
-| Log format | `yyyymmdd_noun_verb-detail_target.ext` |
-
-Scripts and logs live together: `scripts/<module>/logs/`
-
-## Projects vs Milestones
-
-- **Projects** = daily cross-repo tracking (always add to relevant project)
-- **Milestones** = iteration boundaries (only for release/claim prep)
-- Don't double-track unless there's a reason
-
-| Content | Project |
-|---------|---------|
-| R&D, experiments, SRED-related | **SRED R&D Tracking (#8)** |
-| Data storage, sqlite, postgres, pipelines | **Data Architecture (#9)** |
-| Fish passage field/reporting | **Fish Passage 2025 (#6)** |
-| Restoration planning | **Aquatic Restoration Planning (#5)** |
-| QGIS, Mergin, field forms | **Collaborative GIS (#3)** |
-
-
 # Planning Conventions
 
 How Claude manages structured planning for complex tasks using planning-with-files (PWF).
@@ -662,10 +563,11 @@ Skip planning for single-file edits, quick fixes, or tasks with obvious next ste
    - `task_plan.md` — Phases with checkbox tasks
    - `findings.md` — Research, discoveries, technical analysis
    - `progress.md` — Session log with timestamps and commit refs
-3. **Commit the plan** — Commit the planning files before starting implementation. This is the baseline.
-4. **Work in atomic commits** — Each commit bundles code changes WITH checkbox updates in the planning files. The diff shows both what was done and the checkbox marking it done.
-5. **Code check before commit** — Run `/code-check` on staged diffs before committing. Don't mark a task done until the diff passes review.
-6. **Archive when complete** — Move `planning/active/` to `planning/archive/` via `/planning-archive`. Write a README.md in the archive directory with a one-paragraph outcome summary and closing commit/PR ref — future sessions scan these to catch up fast.
+3. **Plan-review with the Plan agent before committing the plan** — After scaffolding `task_plan.md` but BEFORE the baseline commit, spawn the Plan subagent (`Agent({subagent_type: "Plan", prompt: "..."}`) and ask it to critically review the task_plan against the issue body + actual codebase. Categorize findings as Blocker / Gap / Ordering / Assumption / Scope / Acceptance. Address each before committing. The agent reads files fresh — it catches what you miss when you've been thinking about the design too long. Real example: caught 21 issues including hardcoded literals across 4 files not listed in the plan, untested DB column mismatches, unfixable test-literal-string assertions, and a baseline-cache-shadow that would have produced a 6-second no-op run. Cost: ~5 min agent. Saves: hours of mid-implementation rework.
+4. **Commit the plan** — After Plan-agent review + fixes. This is the baseline.
+5. **Work in atomic commits** — Each commit bundles code changes WITH checkbox updates in the planning files. The diff shows both what was done and the checkbox marking it done.
+6. **Code check before commit** — Run `/code-check` on staged diffs before committing. Don't mark a task done until the diff passes review.
+7. **Archive when complete** — Move `planning/active/` to `planning/archive/` via `/planning-archive`. Write a README.md in the archive directory with a one-paragraph outcome summary and closing commit/PR ref — future sessions scan these to catch up fast.
 
 ## Atomic Commits (Critical)
 
@@ -757,6 +659,24 @@ test structure, hex sticker, etc.).
 - Prefix column name vectors with `cols_` for discoverability in the
   environment pane: `cols_all`, `cols_carry`, `cols_split`, `cols_writable`.
   Same principle for other grouped vectors (`params_`, `tbl_`, etc.)
+- For SQL DDL+INSERT pairs that share a schema, use a single named
+  vector as the source of truth. Both `CREATE TABLE` and
+  `INSERT (cols) SELECT cols` derive their column lists from the same
+  `cols_*` vector. Avoids drift between table shape and write
+  projection — when columns change, you edit one place. Example:
+  ```r
+  cols_streams <- c(
+    id_segment           = "integer NOT NULL",
+    watershed_group_code = "varchar(4) NOT NULL",
+    geom                 = "geometry(MultiLineStringZM, 3005)"
+    # …
+  )
+  # CREATE TABLE consumes both names + types
+  ddl_body <- paste(names(cols_streams), unname(cols_streams), sep = " ",
+                    collapse = ", ")
+  # INSERT consumes names only
+  proj <- paste(names(cols_streams), collapse = ", ")
+  ```
 
 ## Package Structure
 
@@ -904,7 +824,7 @@ exclusions: list(
      Link to the pkgdown reference page for details — don't duplicate it.
    - Don't list every function; the pkgdown reference page is the single
      source of truth for what's in the package.
-2. Bump version in `DESCRIPTION` (e.g., `0.0.0.9000` → `0.1.0`)
+2. Bump version in `DESCRIPTION` (e.g., `0.0.0.9000` → `0.1.0`) — as the **final** commit of the branch, after verification numbers/tests are final. Mid-branch bumps are premature and churn: additional code changes end up bundled inside a "release" that already claimed the version.
 3. Commit as "Release vX.Y.Z"
 4. Tag: `git tag vX.Y.Z && git push && git push --tags`
 
@@ -1097,50 +1017,3 @@ Always verify downloads: `file paper.pdf` should say "PDF document", not HTML.
 - NEVER write abstracts manually — if CrossRef has no abstract, leave blank
 - NEVER cite specific numbers without verifying from the source PDF via ragnar search
 - NEVER paraphrase equations — copy exact notation and cite page/section
-
-
-# SRED Conventions
-
-How SR&ED tracking integrates with New Graph Environment's development workflows.
-
-## The Claim: One Project
-
-All SRED-eligible work across NGE falls under a **single continuous project**:
-
-> **Dynamic GIS-based Data Processing and Reporting Framework**
-
-- **Field:** Software Engineering (2.02.09)
-- **Start date:** May 2022
-- **Fiscal year:** May 1 – April 30
-- **Consultant:** Boast Capital (prepares final technical report)
-
-**Do not fragment work into separate claims.** Each fiscal year's work is structured as iterations within this one project. Internal tracking (experiment numbers in `sred-2025-2026`) maps to iterations — Boast assembles the final narrative.
-
-## Tagging Work for SRED
-
-### Commits
-
-Use `Relates to NewGraphEnvironment/sred-2025-2026#N` in commit messages when work is SRED-eligible.
-
-### Time entries (rolex)
-
-Tag hours with `sred_ref` field linking to the relevant `sred-2025-2026` issue number.
-
-### GitHub issues
-
-Link SRED-eligible issues to the tracking repo: `Relates to NewGraphEnvironment/sred-2025-2026#N`
-
-## What Qualifies as SRED
-
-**Eligible (systematic investigation to overcome technological uncertainty):**
-- Building tools/functions that don't exist in standard practice
-- Prototyping new integrations between systems (GIS ↔ reporting ↔ field collection)
-- Testing whether an approach works and documenting why it did/didn't
-- Iterating on failed approaches with new hypotheses
-
-**Not eligible:**
-- Standard configuration of known tools
-- Routine bug fixes in working systems
-- Writing reports using the framework (that's service delivery)
-
-**The test:** "Did we try something we weren't sure would work, and did we learn something from the attempt?" If yes, it's likely eligible.
diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml
index 9d02733..4e0ae31 100644
--- a/docker/docker-compose.yml
+++ b/docker/docker-compose.yml
@@ -33,6 +33,9 @@ services:
         -c max_parallel_workers_per_gather=8
         -c max_parallel_workers=14
         -c max_worker_processes=16
+        -c random_page_cost=1.1
+        -c effective_io_concurrency=200
+        -c temp_buffers=64MB
     volumes:
       - ./postgres-data:/var/lib/postgresql/data
     ports:
diff --git a/docker/tuning.md b/docker/tuning.md
index 336e61d..007f1e8 100644
--- a/docker/tuning.md
+++ b/docker/tuning.md
@@ -21,6 +21,26 @@ Tuning notes for the local Docker fwapg instance. Settings in `docker-compose.ym
 | `max_parallel_workers` | 14 | Leave 2 cores for OS/Docker |
 | `max_worker_processes` | 16 | Match core count |
 | `shm_size` | 36gb | Must exceed shared_buffers (Docker constraint) |
+| `random_page_cost` | 1.1 | SSD: random reads ≈ sequential. Default 4.0 (spinning rust) over-prices index scans, biases planner toward seq scans |
+| `effective_io_concurrency` | 200 | SSD/NVMe: hundreds of concurrent requests. Default 1 under-issues prefetch on bitmap heap scans |
+| `temp_buffers` | 64MB | Per-session temp-table memory. Default 8MB spills working tables (per-WSG segments, breaks, scratch) to disk gratuitously on a 128 GB box |
+
+## SSD assumption
+
+All NewGraph hosts run on SSD (M4 NVMe, M1 Colima virtiofs over APFS,
+cypher DO block storage). The `random_page_cost`,
+`effective_io_concurrency`, and `temp_buffers` defaults above bias the
+planner toward index scans for segment-keyed lookups (the
+`WHERE blue_line_key = … AND drm <= …` against `streams_breaks` hot
+path in link's pipeline). Out-of-the-box PostgreSQL defaults (4.0 / 1
+/ 8MB) are calibrated for spinning rust and are wrong for any modern
+host. Don't lower these without a spinning-disk reason.
+
+**M1/cypher hosts use a docker-compose override file.** Compose merges
+override `command:` lists by **replacing** the base, not by appending —
+so any `-c` flags added here must also be added to the M1/cypher
+override (tracked in the rtj repo). Forgetting this silently leaves
+the 32 GB hosts on PostgreSQL defaults.
 
 ## Scaling for other machines
 
diff --git a/planning/active/findings.md b/planning/active/findings.md
index af27e05..6a4865f 100644
--- a/planning/active/findings.md
+++ b/planning/active/findings.md
@@ -1,63 +1,85 @@
-# Findings — fresh#158
+# Findings — pg tuning: SSD planner-cost defaults (#199)
 
-## Diagnosis (2026-05-01)
+## Issue context
 
-bcfishpass's per-species rear rule has an inline OR clause:
+### Problem
 
-```sql
-(cw.channel_width >= t.rear_channel_width_min OR
- (s.stream_order_parent >= 5 AND s.stream_order = 1))
-```
+`fresh/docker/docker-compose.yml` doesn't set `random_page_cost` or
+`effective_io_concurrency`, so postgres falls through to PostgreSQL
+defaults of `4.0` and `1` — both calibrated for spinning rust. All
+NewGraph hosts run on SSD (M4 NVMe, M1 Colima virtiofs over APFS,
+cypher DO block storage). With `random_page_cost=4`, the planner
+systematically biases away from index scans for segment-keyed lookups
+in link's pipeline (`WHERE blue_line_key = … AND drm <= …` against
+`streams_breaks` is the hot path).
 
-at [`bcfishpass/model/02_habitat_linear/sql/load_habitat_linear_bt.sql`](https://github.com/smnorris/bcfishpass/blob/main/model/02_habitat_linear/sql/load_habitat_linear_bt.sql) lines 89–96 (BT — same pattern in CH/CO/ST/WCT). Direct order-1 tributaries of order-5+ mainstems get credited as rearing **even when cw < rear_min**.
+Verified on M4 + M1 + cypher today (2026-05-04) — all three show
+`random_page_cost=4`, `effective_io_concurrency=1`, `temp_buffers=8MB`.
 
-Biology: small tribs of large rivers support juvenile rearing despite small FWA-measured channel width — parent supplies flow / temperature / access; cool tributary water mixes at confluence; backwater + off-channel habitat near the mouth is high-value.
+### Proposed
 
-fresh has no implementation. link's `dimensions.csv::rear_stream_order_bypass = no` for all species in both bundles (correctly anticipating fresh has nothing to read). Provincial parity baseline (link 0.20.1) shows this gap on HORS / COLR / KHOR / CLRH / etc — Class B in `link/research/provincial_parity_2026_05_01.md`.
+Add to the `db.command` block in base `docker-compose.yml`:
 
-## Function design (per issue body)
+```yaml
+-c random_page_cost=1.1
+-c effective_io_concurrency=200
+-c temp_buffers=64MB
+```
 
-`frs_order_child(conn, table, habitat, species, label = "rearing", parent_order_min = 5, child_order_min = NULL, child_order_max = NULL, distance_max = NULL)`
+Document in `fresh/docker/tuning.md` alongside the existing memory
+rationale: SSD cost values, why they matter for link's segment-heavy
+SQL.
 
-Post-classification UPDATE:
+### Verification
 
-```sql
-UPDATE habitat
-SET <label> = TRUE
-FROM streams s
-WHERE habitat.id_segment = s.id_segment
-  AND habitat.species_code = '<species>'
-  AND habitat.accessible = TRUE
-  AND habitat.<label> IS NOT TRUE
-  AND s.stream_order = s.stream_order_max         -- direct child
-  AND s.stream_order_parent >= <parent_order_min> -- of large river
-  AND s.stream_order >= <child_order_min>         -- if set
-  AND s.stream_order <= <child_order_max>         -- if set
-  AND (<distance_max> IS NULL OR
-       s.downstream_route_measure <= <distance_max>);
-```
+Post-merge, M4 reruns one of link's provincial-style runs. Compare
+per-WSG wall times in `data-raw/logs/<TS>_per_wsg_times.csv` against
+today's baseline (2026-05-04 `default_extrabreaks` run,
+`data-raw/logs/provincial_default_extrabreaks/<TS>_per_wsg_times.csv`).
+Acceptance: median per-WSG wall reduced by ≥ 10 % at unchanged segment
+count.
+
+### Cross-ref
+
+Companion rtj issue for the M1/cypher override file — the override's
+`command:` list REPLACES the base under docker-compose's merge
+semantics, so settings added here don't propagate to the 32 GB hosts.
+Same change must land in both.
 
-Direct-child filter: `s.stream_order = s.stream_order_max` ensures we stop at the order-change point (once the segment's order would exceed `stream_order_max`, you're no longer on the direct-child reach). Captures "small tributary directly into a large parent."
+## Setting-by-setting rationale
 
-`accessible = TRUE` guard: never adds rearing on segments above a definite barrier.
+### `random_page_cost = 1.1`
 
-`<label> IS NOT TRUE` guard: idempotent + additive — already-classified segments untouched.
+PostgreSQL default is `4.0` — the cost ratio for a random vs
+sequential page read on spinning rust (~4× slower for random I/O).
+On SSD, random reads are nearly as cheap as sequential. PostgreSQL
+docs and tuning consensus recommend `1.1` to `1.5` for SSD. With the
+default, the planner systematically over-prices index scans and
+prefers seq scans even when an index would be faster — exactly the
+wrong bias for segment-keyed lookups.
 
-## Pre vs post cluster — design decision (post-cluster wins)
+### `effective_io_concurrency = 200`
 
-bcfishpass embeds the bypass in the rule predicate (pre-cluster). Issue body's analysis: post-cluster is cleaner because:
-- Bypassed segments don't need to pass connectivity (they're connected to the large parent by definition; the biology of the bypass IS the connectivity)
-- `accessible = TRUE` already gates barrier-blocked reaches
-- Post-cluster matches the parametric form (function takes WSG/species and applies, not a rule predicate that needs SQL grammar in fresh)
-- Same end-state numbers as bcfp on the BCFP-parity caller-side defaults
+PostgreSQL default is `1`. This setting tells the planner how many
+concurrent I/O requests the storage can usefully serve, used to drive
+prefetch on bitmap heap scans. SSDs (especially NVMe) handle hundreds
+of concurrent requests trivially — `200` is the standard recommendation
+for SSD. Value of `1` causes the planner to under-issue prefetches and
+underestimate bitmap-scan throughput.
 
-## Caller defaults (link side, separate PR)
+### `temp_buffers = 64MB`
 
-- bcfishpass bundle: `frs_order_child(species, parent_order_min = 5)` (defaults) for BT/CH/CO/ST/WCT
-- default bundle: methodology-pending. Could ship same as bcfp first, tune later
+PostgreSQL default is `8MB` — per-session memory for temporary tables.
+Bumping to `64MB` lets short-lived temp/working tables live in RAM
+instead of spilling to disk. fresh/link pipelines build per-WSG temp
+tables (segments, breaks, working scratch) that are read repeatedly
+within a session; spilling these to disk is gratuitous on a dev box
+with 128 GB RAM.
 
-## Versions at start
+## Repo state
 
-- fresh main: 253abf2 (0.26.0)
-- link main: 9643be5 (0.21.0)
-- bcfishpass: 440bc1e
+- `docker/docker-compose.yml:21-35` — current `db.command` block has
+  memory + parallelism flags but no I/O cost flags
+- `docker/tuning.md` — has "Settings rationale" table and a "Scaling
+  for other machines" recipe; new flags are global (not RAM-scaled),
+  no scaling change needed
diff --git a/planning/active/progress.md b/planning/active/progress.md
index 0d7f2a5..04dea56 100644
--- a/planning/active/progress.md
+++ b/planning/active/progress.md
@@ -1,7 +1,21 @@
-# Progress — fresh#158
+# Progress — pg tuning: SSD planner-cost defaults (#199)
 
-## Session 2026-05-01
+## Session 2026-05-04
 
-- Branch `158-frs-order-child` from main HEAD `253abf2` (post-fresh#191 release).
-- PWF baseline.
-- Next: write `R/frs_order_child.R` per issue body spec, mock SQL tests.
+- Plan-mode exploration — phases approved by user
+- Archived stale top-level planning files (#177) and stale active/ (#158)
+  with outcome READMEs in commit `80170b4`
+- Created branch `199-pg-tuning-ssd-planner-cost-defaults` off main (HEAD `80170b4`)
+- Scaffolded PWF baseline from issue #199 with approved phases
+- Phase 1 complete: added `random_page_cost=1.1`, `effective_io_concurrency=200`,
+  `temp_buffers=64MB` to `db.command`. Restarted local DB; all three values
+  verified live via `SHOW`.
+- Phase 2 complete: added three rows to the Settings rationale table in
+  `docker/tuning.md`, plus an "SSD assumption" section noting the
+  M1/cypher override-file caveat (override `command:` replaces base, so
+  same flags must land in the rtj-tracked override).
+- Phase 3 complete: pushed branch, opened PR #200 with `Closes #199`.
+  Manual code-check on the docker/ diff — clean (pure ASCII in the YAML
+  block, no secrets, indentation matches surrounding `-c` flags, DB
+  came up after restart and live `SHOW` confirmed all three values).
+- Next: merge, archive PWF, companion rtj-side change (separate work).
diff --git a/planning/active/task_plan.md b/planning/active/task_plan.md
index 7301d8f..a1fd85d 100644
--- a/planning/active/task_plan.md
+++ b/planning/active/task_plan.md
@@ -1,45 +1,46 @@
-# Task Plan — fresh#158: frs_order_child
-
-## Phase 1: Setup
-- [x] Branch `158-frs-order-child` from main (HEAD `253abf2`)
-- [ ] PWF baseline (task_plan, findings, progress)
-
-## Phase 2: Code change — fresh-side
-- [ ] New `R/frs_order_child.R` exporting `frs_order_child(conn, table, habitat, species, label = "rearing", parent_order_min = 5, child_order_min = NULL, child_order_max = NULL, distance_max = NULL)`
-- [ ] SQL per the [issue spec](https://github.com/NewGraphEnvironment/fresh/issues/158): post-classification UPDATE that adds `<label> = TRUE` to segments where `accessible IS TRUE`, `<label> IS NOT TRUE`, `s.stream_order = s.stream_order_max`, `s.stream_order_parent >= parent_order_min`, optionally bounded by `child_order_min/max` and `distance_max`
-- [ ] roxygen docstring with parameters, examples, biology rationale
-- [ ] `devtools::document()` clean
-
-## Phase 3: Tests
-- [ ] `tests/testthat/test-frs_order_child.R`: SQL shape (mock `.frs_db_execute`)
-  - default invocation emits the canonical SQL with parent_order_min=5
-  - `child_order_min/max` bounds appear when set
-  - `distance_max` adds `downstream_route_measure <= ...` clause
-  - `accessible IS TRUE` and `<label> IS NOT TRUE` guards always present
-  - `species` substituted correctly
-- [ ] `devtools::test(filter = "frs_order_child")` clean
-
-## Phase 4: Code-check
-- [ ] `/code-check` on staged diff
-
-## Phase 5: Release
-- [ ] DESCRIPTION: 0.26.0 → 0.27.0
-- [ ] NEWS.md: 0.27.0 entry
-- [ ] PR with `Fixes #158`
-- [ ] Merge, tag
-
-## Phase 6: Link follow-up
-- [ ] Bump fresh dep 0.26.0 → 0.27.0
-- [ ] dimensions.csv: flip `rear_stream_order_bypass = yes` for BT/CH/CO/ST/WCT in bcfishpass bundle
-- [ ] Default-bundle TBD per methodology decision (issue mentions parametric `distance_max` could differ)
-- [ ] `lnk_rules_build` already emits `channel_width_min_bypass` field but fresh doesn't read it yet — wire to call `frs_order_child` per-species after classify
-- [ ] Verify HORS BT closes from -7.68% to within ±1%
-- [ ] 15-WSG distributed re-run
-
-## Verification
-
-- HORS BT rearing_stream: -7.68% → expected within ±1%
-- HORS CH/CO/ST: similar closure expected
-- COLR/KHOR/CLRH WCT: similar closure expected (provincial Class B)
-- bcfishpass-bundle other WSGs: bit-identical (function only fires where `rear_stream_order_bypass: yes` is set)
-- default-bundle: TBD per methodology
+# Task: pg tuning — SSD planner-cost defaults in docker-compose.yml (#199)
+
+`docker/docker-compose.yml` doesn't set `random_page_cost` or
+`effective_io_concurrency`, so postgres falls through to PostgreSQL
+defaults of `4.0` and `1` — both calibrated for spinning rust. All
+NewGraph hosts run on SSD (M4 NVMe, M1 Colima virtiofs over APFS,
+cypher DO block storage). With `random_page_cost=4`, the planner
+systematically biases away from index scans for segment-keyed lookups
+in link's pipeline (`WHERE blue_line_key = … AND drm <= …` against
+`streams_breaks` is the hot path).
+
+Verified on M4 + M1 + cypher (2026-05-04) — all three show
+`random_page_cost=4`, `effective_io_concurrency=1`, `temp_buffers=8MB`.
+
+## Phase 1: Add SSD planner-cost flags to docker-compose.yml
+- [x] Append to `db.command` block in `docker/docker-compose.yml`:
+  - `-c random_page_cost=1.1`
+  - `-c effective_io_concurrency=200`
+  - `-c temp_buffers=64MB`
+- [x] Restart local Docker DB (`docker compose down && docker compose up -d db`)
+- [x] Verify via `SHOW random_page_cost; SHOW effective_io_concurrency; SHOW temp_buffers;`
+  (verified live: `random_page_cost=1.1`, `effective_io_concurrency=200`, `temp_buffers=64MB`)
+
+## Phase 2: Document in tuning.md
+- [x] Add three rows to the "Settings rationale" table
+  (`random_page_cost`, `effective_io_concurrency`, `temp_buffers`) with
+  SSD justification per setting
+- [x] Add a short "SSD assumption" note: all NewGraph hosts run on SSD
+  (M4 NVMe, M1 Colima virtiofs over APFS, cypher DO block storage),
+  these defaults bias the planner toward index scans for segment-keyed
+  lookups in link's pipeline
+- [x] Cross-reference the companion rtj issue for the M1/cypher override
+  file — override `command:` REPLACES base under docker-compose merge
+  semantics; same change must land in both
+
+## Phase 3: Verify and PR
+- [x] `/code-check` on the diff (manual; clean)
+- [x] Push branch, open PR with `Closes #199` (PR #200)
+- [x] Note benchmark verification is a post-merge step (≥10% median
+  per-WSG wall reduction at unchanged segment count) — owner runs from
+  M4 against `data-raw/logs/provincial_default_extrabreaks/<TS>_per_wsg_times.csv`
+  baseline (2026-05-04). Documented in PR test-plan.
+
+## Validation
+- [ ] PWF checkboxes match landed work
+- [ ] `/planning-archive` on completion
diff --git a/planning/archive/2026-04-issue-177-frs-habitat-overlay-format/README.md b/planning/archive/2026-04-issue-177-frs-habitat-overlay-format/README.md
new file mode 100644
index 0000000..2274fc3
--- /dev/null
+++ b/planning/archive/2026-04-issue-177-frs-habitat-overlay-format/README.md
@@ -0,0 +1,7 @@
+## Outcome
+
+Dropped `format` and `long_value_col` parameters from `frs_habitat_overlay()`. Function now accepts a single canonical shape (row-per-(segment × species) with per-habitat indicator columns), parameterized by `species_col`, `by`, and `habitat_types`. Callers with non-canonical sources transform first (SQL view, R pivot, or link's `lnk_ingest_bcfishpass()`). Bridge mode retained.
+
+## Closed By
+
+PR #176.
diff --git a/planning/findings.md b/planning/archive/2026-04-issue-177-frs-habitat-overlay-format/findings.md
similarity index 100%
rename from planning/findings.md
rename to planning/archive/2026-04-issue-177-frs-habitat-overlay-format/findings.md
diff --git a/planning/progress.md b/planning/archive/2026-04-issue-177-frs-habitat-overlay-format/progress.md
similarity index 100%
rename from planning/progress.md
rename to planning/archive/2026-04-issue-177-frs-habitat-overlay-format/progress.md
diff --git a/planning/task_plan.md b/planning/archive/2026-04-issue-177-frs-habitat-overlay-format/task_plan.md
similarity index 100%
rename from planning/task_plan.md
rename to planning/archive/2026-04-issue-177-frs-habitat-overlay-format/task_plan.md
diff --git a/planning/archive/2026-05-issue-158-frs-order-child/README.md b/planning/archive/2026-05-issue-158-frs-order-child/README.md
new file mode 100644
index 0000000..e6f89a1
--- /dev/null
+++ b/planning/archive/2026-05-issue-158-frs-order-child/README.md
@@ -0,0 +1,7 @@
+## Outcome
+
+Added `frs_order_child()` — post-classification UPDATE that flags direct-children of large-order parent streams (`stream_order = stream_order_max` AND `stream_order_parent >= parent_order_min`). Wired into the rules YAML via `channel_width_min_bypass` block so per-species rearing classifiers can opt in. Closes the BT/CO/CH/ST/WCT rearing-stream gap on bcfishpass-bundled WSGs (HORS, COLR, KHOR, CLRH, etc.).
+
+## Closed By
+
+PR #193 (initial impl), with follow-ups #195 and #196 (SQL fixes for the missing/restored `stream_order_max` column via CTE).
diff --git a/planning/archive/2026-05-issue-158-frs-order-child/findings.md b/planning/archive/2026-05-issue-158-frs-order-child/findings.md
new file mode 100644
index 0000000..af27e05
--- /dev/null
+++ b/planning/archive/2026-05-issue-158-frs-order-child/findings.md
@@ -0,0 +1,63 @@
+# Findings — fresh#158
+
+## Diagnosis (2026-05-01)
+
+bcfishpass's per-species rear rule has an inline OR clause:
+
+```sql
+(cw.channel_width >= t.rear_channel_width_min OR
+ (s.stream_order_parent >= 5 AND s.stream_order = 1))
+```
+
+at [`bcfishpass/model/02_habitat_linear/sql/load_habitat_linear_bt.sql`](https://github.com/smnorris/bcfishpass/blob/main/model/02_habitat_linear/sql/load_habitat_linear_bt.sql) lines 89–96 (BT — same pattern in CH/CO/ST/WCT). Direct order-1 tributaries of order-5+ mainstems get credited as rearing **even when cw < rear_min**.
+
+Biology: small tribs of large rivers support juvenile rearing despite small FWA-measured channel width — parent supplies flow / temperature / access; cool tributary water mixes at confluence; backwater + off-channel habitat near the mouth is high-value.
+
+fresh has no implementation. link's `dimensions.csv::rear_stream_order_bypass = no` for all species in both bundles (correctly anticipating fresh has nothing to read). Provincial parity baseline (link 0.20.1) shows this gap on HORS / COLR / KHOR / CLRH / etc — Class B in `link/research/provincial_parity_2026_05_01.md`.
+
+## Function design (per issue body)
+
+`frs_order_child(conn, table, habitat, species, label = "rearing", parent_order_min = 5, child_order_min = NULL, child_order_max = NULL, distance_max = NULL)`
+
+Post-classification UPDATE:
+
+```sql
+UPDATE habitat
+SET <label> = TRUE
+FROM streams s
+WHERE habitat.id_segment = s.id_segment
+  AND habitat.species_code = '<species>'
+  AND habitat.accessible = TRUE
+  AND habitat.<label> IS NOT TRUE
+  AND s.stream_order = s.stream_order_max         -- direct child
+  AND s.stream_order_parent >= <parent_order_min> -- of large river
+  AND s.stream_order >= <child_order_min>         -- if set
+  AND s.stream_order <= <child_order_max>         -- if set
+  AND (<distance_max> IS NULL OR
+       s.downstream_route_measure <= <distance_max>);
+```
+
+Direct-child filter: `s.stream_order = s.stream_order_max` ensures we stop at the order-change point (once the segment's order would exceed `stream_order_max`, you're no longer on the direct-child reach). Captures "small tributary directly into a large parent."
+
+`accessible = TRUE` guard: never adds rearing on segments above a definite barrier.
+
+`<label> IS NOT TRUE` guard: idempotent + additive — already-classified segments untouched.
+
+## Pre vs post cluster — design decision (post-cluster wins)
+
+bcfishpass embeds the bypass in the rule predicate (pre-cluster). Issue body's analysis: post-cluster is cleaner because:
+- Bypassed segments don't need to pass connectivity (they're connected to the large parent by definition; the biology of the bypass IS the connectivity)
+- `accessible = TRUE` already gates barrier-blocked reaches
+- Post-cluster matches the parametric form (function takes WSG/species and applies, not a rule predicate that needs SQL grammar in fresh)
+- Same end-state numbers as bcfp on the BCFP-parity caller-side defaults
+
+## Caller defaults (link side, separate PR)
+
+- bcfishpass bundle: `frs_order_child(species, parent_order_min = 5)` (defaults) for BT/CH/CO/ST/WCT
+- default bundle: methodology-pending. Could ship same as bcfp first, tune later
+
+## Versions at start
+
+- fresh main: 253abf2 (0.26.0)
+- link main: 9643be5 (0.21.0)
+- bcfishpass: 440bc1e
diff --git a/planning/archive/2026-05-issue-158-frs-order-child/progress.md b/planning/archive/2026-05-issue-158-frs-order-child/progress.md
new file mode 100644
index 0000000..0d7f2a5
--- /dev/null
+++ b/planning/archive/2026-05-issue-158-frs-order-child/progress.md
@@ -0,0 +1,7 @@
+# Progress — fresh#158
+
+## Session 2026-05-01
+
+- Branch `158-frs-order-child` from main HEAD `253abf2` (post-fresh#191 release).
+- PWF baseline.
+- Next: write `R/frs_order_child.R` per issue body spec, mock SQL tests.
diff --git a/planning/archive/2026-05-issue-158-frs-order-child/task_plan.md b/planning/archive/2026-05-issue-158-frs-order-child/task_plan.md
new file mode 100644
index 0000000..7301d8f
--- /dev/null
+++ b/planning/archive/2026-05-issue-158-frs-order-child/task_plan.md
@@ -0,0 +1,45 @@
+# Task Plan — fresh#158: frs_order_child
+
+## Phase 1: Setup
+- [x] Branch `158-frs-order-child` from main (HEAD `253abf2`)
+- [ ] PWF baseline (task_plan, findings, progress)
+
+## Phase 2: Code change — fresh-side
+- [ ] New `R/frs_order_child.R` exporting `frs_order_child(conn, table, habitat, species, label = "rearing", parent_order_min = 5, child_order_min = NULL, child_order_max = NULL, distance_max = NULL)`
+- [ ] SQL per the [issue spec](https://github.com/NewGraphEnvironment/fresh/issues/158): post-classification UPDATE that adds `<label> = TRUE` to segments where `accessible IS TRUE`, `<label> IS NOT TRUE`, `s.stream_order = s.stream_order_max`, `s.stream_order_parent >= parent_order_min`, optionally bounded by `child_order_min/max` and `distance_max`
+- [ ] roxygen docstring with parameters, examples, biology rationale
+- [ ] `devtools::document()` clean
+
+## Phase 3: Tests
+- [ ] `tests/testthat/test-frs_order_child.R`: SQL shape (mock `.frs_db_execute`)
+  - default invocation emits the canonical SQL with parent_order_min=5
+  - `child_order_min/max` bounds appear when set
+  - `distance_max` adds `downstream_route_measure <= ...` clause
+  - `accessible IS TRUE` and `<label> IS NOT TRUE` guards always present
+  - `species` substituted correctly
+- [ ] `devtools::test(filter = "frs_order_child")` clean
+
+## Phase 4: Code-check
+- [ ] `/code-check` on staged diff
+
+## Phase 5: Release
+- [ ] DESCRIPTION: 0.26.0 → 0.27.0
+- [ ] NEWS.md: 0.27.0 entry
+- [ ] PR with `Fixes #158`
+- [ ] Merge, tag
+
+## Phase 6: Link follow-up
+- [ ] Bump fresh dep 0.26.0 → 0.27.0
+- [ ] dimensions.csv: flip `rear_stream_order_bypass = yes` for BT/CH/CO/ST/WCT in bcfishpass bundle
+- [ ] Default-bundle TBD per methodology decision (issue mentions parametric `distance_max` could differ)
+- [ ] `lnk_rules_build` already emits `channel_width_min_bypass` field but fresh doesn't read it yet — wire to call `frs_order_child` per-species after classify
+- [ ] Verify HORS BT closes from -7.68% to within ±1%
+- [ ] 15-WSG distributed re-run
+
+## Verification
+
+- HORS BT rearing_stream: -7.68% → expected within ±1%
+- HORS CH/CO/ST: similar closure expected
+- COLR/KHOR/CLRH WCT: similar closure expected (provincial Class B)
+- bcfishpass-bundle other WSGs: bit-identical (function only fires where `rear_stream_order_bypass: yes` is set)
+- default-bundle: TBD per methodology