diff --git a/.gitignore b/.gitignore
index cc0b0d7..ab70af3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,3 +6,5 @@ inst/doc
 docs
 /doc/
 /Meta/
+*.html
+Rplots.pdf
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..c617b04
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,1409 @@
+# flooded
+
+Portable floodplain delineation from DEM and stream network using the Valley Confinement Algorithm (VCA). Built on `terra` and `sf` for R-native raster processing. Bring your own DEM and streams; works anywhere.
+
+## Repository Context
+
+**Repository:** NewGraphEnvironment/flooded
+**Primary Language:** R (package)
+**Version:** 0.1.0
+**License:** MIT
+
+## Ecosystem
+
+`flooded` is the floodplain-delineation engine in a family of packages:
+
+- **[drift](https://github.com/NewGraphEnvironment/drift)** — fetch, classify, and summarize lateral habitat using flooded output
+- **[fly](https://github.com/NewGraphEnvironment/fly)** — interactive mapping and layer toggle for drift/flooded results
+- **[diggs](https://github.com/NewGraphEnvironment/diggs)** — Shiny app front-end for fly
+
+Pipeline flow: `flooded` (delineate) → `drift` (classify) → `fly` (map) → `diggs` (Shiny UI)
+
+## Architecture
+
+```
+R/
+  fl_valley_confine.R   — top-level wrapper (one-call delineation)
+  fl_flood_model.R      — bankfull regression → flood depth
+  fl_flood_surface.R    — cost-distance flood surface
+  fl_flood_assemble.R   — combine flood + slope masks
+  fl_flood_trim.R       — remove disconnected patches
+  fl_valley_poly.R      — raster → sf polygon conversion
+  fl_cost_distance.R    — weighted cost-distance from streams
+  fl_mask*.R            — slope/distance masking helpers
+  fl_patch*.R           — patch connectivity and removal
+  fl_stream_rasterize.R — burn streams into DEM grid
+vignettes/
+  valley-confinement.Rmd — full walkthrough with bundled test data
+  stac-dem.Rmd           — fetch DEM from STAC catalog
+tests/testthat/          — unit tests for each fl_* function
+```
+
+## Key Patterns
+
+- All exported functions prefixed `fl_`
+- `terra::rast` and `sf::st_read` for spatial I/O
+- `terra::terraOptions(threads = N)` for parallel raster ops
+- Bankfull regression requires both `upstream_area` (ha) and `precip` (mm)
+- Optional `whitebox` dependency for advanced hydro operations
+
+<\!-- BEGIN SOUL CONVENTIONS — DO NOT EDIT BELOW THIS LINE -->
+
+# Agent Teams Orchestration
+
+Checklist for effectively running Claude Code agent teams. Agent teams coordinate multiple Claude Code instances working in parallel with shared tasks and inter-agent messaging.
+
+**Source:** [code.claude.com/docs/en/agent-teams](https://code.claude.com/docs/en/agent-teams)
+
+**Status:** Experimental. Disabled by default.
+
+## Before You Start
+
+- [ ] **Enable the feature flag** in `settings.json` or environment:
+  ```json
+  { "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }
+  ```
+- [ ] **Choose display mode** — `in-process` (default, any terminal) or split panes (requires tmux or iTerm2). Set `teammateMode` in `settings.json` or pass `--teammate-mode`.
+- [ ] **Install tmux** if using split panes (`brew install tmux`). Not supported in VS Code terminal, Windows Terminal, or Ghostty.
+- [ ] **Pre-approve common permissions** in your permission settings before spawning teammates — permission prompts bubble up to the lead and create friction.
+
+## When to Use Teams (vs. Subagents)
+
+Use agent teams when teammates need to **talk to each other** — research debates, competing hypotheses, cross-layer coordination. Use subagents when you just need focused workers that report back results.
+
+**Good fit:** parallel code review (security + performance + tests), investigating competing bug hypotheses, new modules that don't share files, research from multiple angles.
+
+**Bad fit:** sequential tasks, edits to the same file, simple work where coordination overhead exceeds benefit.
+
+## Starting a Team
+
+- [ ] **Give enough context in the spawn prompt** — teammates don't inherit the lead's conversation history. Include file paths, architecture context, and specific focus areas.
+- [ ] **Size tasks right** — too small = overhead wasted, too large = risk of divergence. Aim for self-contained units with clear deliverables. 5-6 tasks per teammate keeps everyone productive.
+- [ ] **Specify models explicitly** if you want cost control (e.g., "Use Sonnet for each teammate").
+- [ ] **Ensure teammates own different files** — two teammates editing the same file leads to overwrites.
+
+## During Execution
+
+- [ ] **Use delegate mode** (Shift+Tab) to prevent the lead from implementing tasks itself instead of waiting for teammates.
+- [ ] **Monitor and steer** — check progress, redirect approaches that aren't working. Don't let a team run unattended too long.
+- [ ] **Message teammates directly** — Shift+Up/Down in in-process mode, click pane in split mode. Give additional instructions or ask follow-ups.
+- [ ] **If the lead starts coding instead of delegating**, tell it: "Wait for your teammates to complete their tasks before proceeding."
+
+## Quality Gates
+
+- [ ] **Require plan approval** for risky work — teammates plan in read-only mode until the lead approves. Give criteria: "only approve plans that include test coverage."
+- [ ] **Use hooks** for automated enforcement:
+  - `TeammateIdle` — exit code 2 sends feedback and keeps the teammate working
+  - `TaskCompleted` — exit code 2 prevents completion and sends feedback
+
+## Cleanup (Critical)
+
+- [ ] **Shut down all teammates first** — ask the lead: "Ask the researcher teammate to shut down." Teammates finish their current action before stopping.
+- [ ] **Then clean up the team** — tell the lead: "Clean up the team." This removes shared resources. Cleanup fails if teammates are still running.
+- [ ] **Always clean up via the lead** — teammates should never run cleanup (their team context may not resolve correctly).
+- [ ] **Check for orphaned tmux sessions** after cleanup:
+  ```bash
+  tmux ls
+  tmux kill-session -t <session-name>
+  ```
+
+## Known Limitations
+
+- **No session resumption** — `/resume` and `/rewind` don't restore in-process teammates. After resuming, tell the lead to spawn new teammates.
+- **Task status can lag** — teammates sometimes fail to mark tasks complete, blocking dependents. Manually check and update if stuck.
+- **One team per session** — clean up before starting a new team.
+- **No nested teams** — only the lead can manage the team.
+- **Lead is fixed** — can't promote a teammate or transfer leadership.
+- **Permissions set at spawn** — all teammates inherit the lead's mode. Change individually after spawning if needed.
+
+## Quick Reference
+
+| Action | How |
+|--------|-----|
+| Cycle teammates | Shift+Up/Down |
+| View teammate session | Enter on selected teammate |
+| Interrupt teammate | Escape while viewing |
+| Toggle task list | Ctrl+T |
+| Enable delegate mode | Shift+Tab |
+| Force in-process mode | `claude --teammate-mode in-process` |
+
+# Bookdown Conventions
+
+Standards for bookdown report projects across New Graph Environment.
+
+## Template Repos
+
+These are the canonical references. Child repos inherit their structure and patterns.
+
+- [mybookdown-template](https://github.com/NewGraphEnvironment/mybookdown-template) — General-purpose bookdown starter
+- [fish_passage_template_reporting](https://github.com/NewGraphEnvironment/fish_passage_template_reporting) — Fish passage reporting template
+
+When in doubt, match what the template does. When the template and production repos disagree, production wins — update the template.
+
+## Project Structure
+
+```
+project/
+├── index.Rmd                # Master config, YAML params, setup chunks
+├── _bookdown.yml            # book_filename, output_dir: "docs"
+├── _output.yml              # Gitbook, pagedown, pdf_book config
+├── 0100-intro.Rmd           # Chapter numbering: 4-digit, 100s increment
+├── 0200-background.Rmd
+├── 0300-methods.Rmd
+├── 0400-results.Rmd
+├── 0500-*.Rmd               # Discussion/recommendations
+├── 0800-appendix-*.Rmd      # Appendices (site-specific in fish passage)
+├── 2000-references.Rmd      # Auto-generated from .bib
+├── 2090-report-change-log.Rmd  # Auto-generated from NEWS.md
+├── 2100-session-info.Rmd    # Reproducibility
+├── NEWS.md                  # Changelog (semantic versioning)
+├── scripts/
+│   ├── packages.R           # Package loading (renv-managed)
+│   ├── functions.R          # Project-specific functions
+│   ├── staticimports.R      # Auto-generated from staticimports pkg
+│   ├── setup_docs.R         # Build helper
+│   └── run.R                # Local build (gitbook + PDF)
+├── fig/                     # Figures (organized by chapter or type)
+├── data/                    # Project data
+├── docs/                    # Rendered output (GitHub Pages)
+├── renv.lock                # Locked dependencies
+└── .Rprofile                # Activates renv
+```
+
+## Setup Chunk Pattern
+
+Every `index.Rmd` follows this setup sequence. Order matters.
+
+```r
+# 1. Gitbook vs PDF switch
+gitbook_on <- TRUE
+
+# 2. Knitr options
+knitr::opts_chunk$set(
+  echo = identical(gitbook_on, TRUE),  # Show code only in gitbook
+  message = FALSE, warning = FALSE,
+  dpi = 60, out.width = "100%"
+)
+options(scipen = 999)
+options(knitr.kable.NA = '--')
+options(knitr.kable.NAN = '--')
+
+# 3. Source in order: packages → static imports → functions → data
+source('scripts/packages.R')
+source('scripts/staticimports.R')
+source('scripts/functions.R')
+```
+
+Responsive settings by output format:
+
+```r
+# Gitbook
+photo_width <- "100%"; font_set <- 11
+
+# PDF (paged.js)
+photo_width <- "80%"; font_set <- 9
+```
+
+## YAML Parameters
+
+Parameters live in `index.Rmd` frontmatter (not a separate file). Child repos override by editing these values.
+
+```yaml
+params:
+  repo_url: 'https://github.com/NewGraphEnvironment/repo_name'
+  report_url: 'https://www.newgraphenvironment.com/repo_name/'
+  update_packages: FALSE
+  update_bib: TRUE
+  gitbook_on: TRUE
+```
+
+Fish passage repos add project-specific params (`project_region`, `model_species`, `wsg_code`, update flags for forms). These are project-specific — don't add them to the general template.
+
+## Chunk Naming
+
+Embed context and purpose in chunk names. The principle is universal; the codes are project-specific.
+
+**Pattern:** `{type}-{system}-{description}`
+
+| Type | Examples |
+|------|---------|
+| Tables | `tab-kln-load-int-yr`, `tab-sites-sum`, `tab-wshd-196332` |
+| Figures | `plot-wq-kln-quadratic`, `map-interactive`, `map-196332` |
+| Photos | `photo-196332-01`, `photo-196332-d01` (dual layout) |
+
+## Cross-References
+
+Bookdown auto-prepends `fig:` or `tab:` to chunk names.
+
+- **Tables:** `Table \@ref(tab:chunk-name)`
+- **Figures:** `Figure \@ref(fig:chunk-name)`
+
+No `fig:` or `tab:` prefix in the chunk label itself — bookdown adds it.
+
+## Table Caption Workaround
+
+Interactive tables (DT) can't use standard bookdown captions. Use the `my_tab_caption()` function from `staticimports.R`.
+
+**Pattern:** Separate `-cap` chunk from table chunk.
+
+```r
+# Caption chunk — must use results="asis"
+{r tab-sites-sum-cap, results="asis"}
+my_caption <- "Summary of fish passage assessment procedures."
+my_tab_caption()
+```
+
+```r
+# Table chunk — renders the DT
+{r tab-sites-sum}
+data |> my_dt_table(page_length = 20, cols_freeze_left = 0)
+```
+
+`my_tab_caption()` auto-grabs the chunk label via `knitr::opts_current$get()$label` and wraps it in HTML caption tags that bookdown can cross-reference.
+
+## Photo Layout
+
+Separate prep chunk (find the file) from display chunk (render it).
+
+```r
+# Prep — find the photo
+{r photo-196332-01-prep}
+my_photo1 <- fpr::fpr_photo_pull_by_str(str_to_pull = 'ds_typical_1_')
+my_caption1 <- paste0('Typical habitat downstream of PSCIS crossing ', my_site, '.')
+```
+
+```r
+# Gitbook — full width
+{r photo-196332-01, fig.cap=my_caption1, out.width=photo_width, eval=gitbook_on}
+knitr::include_graphics(my_photo1)
+```
+
+```r
+# PDF — side by side with 1% spacer
+{r photo-196332-d01, fig.show="hold", out.width=c("49.5%","1%","49.5%"), eval=identical(gitbook_on, FALSE)}
+knitr::include_graphics(my_photo1)
+knitr::include_graphics("fig/pixel.png")
+knitr::include_graphics(my_photo2)
+```
+
+## Bibliography
+
+**`references.bib` is auto-generated — never edit it manually.** On each build, `rbbt::bbt_write_bib()` scans all `.Rmd` files for `@citekey` references, pulls the BibTeX from Zotero's Better BibTeX, and overwrites `references.bib`. Any manual additions will be lost on the next build.
+
+To add a reference: add it to the shared Zotero group library, use its BBT citation key (`@key`) in the `.Rmd` text, and build. rbbt handles the rest.
+
+```yaml
+bibliography: "`r rbbt::bbt_write_bib('references.bib', overwrite = TRUE)`"
+biblio-style: apalike
+link-citations: no
+```
+
+When `update_bib: FALSE` in params, the build uses the existing `references.bib` without regenerating — useful for offline builds or CI where Zotero isn't running.
+
+Auto-generate package citations:
+
+```r
+knitr::write_bib(c(.packages(), 'bookdown', 'knitr', 'rmarkdown'), 'packages.bib')
+```
+
+Use `nocite:` in YAML to include references not cited in text.
+
+## Acknowledgement & AI Disclosure
+
+`index.Rmd` contains two separate front-matter sections after the setup chunks:
+
+### Acknowledgement {.front-matter .unnumbered}
+
+Three parts, in order:
+
+1. **Personal connection to land** (template-level, same across all reports):
+   > At New Graph Environment, we understand our well-being as inseparable from the health of the land and waters we work within. When we care for ecosystems, we care for ourselves and for the communities connected to them. This relationship is not metaphorical — it is the foundation of our practice.
+
+2. **Colonial acknowledgement** (template-level):
+   > Modern civilization has a long journey ahead to acknowledge and address the historic and ongoing impacts of colonialism...
+
+3. **Territorial acknowledgement** (project-specific, must be edited per report): Name the Nations, governance systems, watersheds, and species relevant to the project. Do not use a generic office-location acknowledgement — tie it to the territory where the work happens. See the Wedzin Kwa chinook example for the pattern.
+
+4. **Funding and partners** (project-specific).
+
+### AI Disclosure
+
+Do not use a `#` heading for the disclosure — this creates a separate chapter page in gitbook. Instead, add it to the YAML `date:` field so it renders in the title block:
+
+```yaml
+date: |
+ |
+ | Version X.X.X DRAFT `r format(Sys.Date(), "%Y-%m-%d")`
+ |
+ | *Claude Sonnet 4.6 (Anthropic) assisted with literature synthesis, drafting, and technical writing. All scientific interpretation, data analysis, and conclusions are the responsibility of the authors.*
+```
+
+**Wording principle:** Be accurate about what the LLM did. It assisted with drafting and synthesis — it did not make scientific interpretations or conclusions. Do not say "independently verified by the authors" (redundant) or attribute "ecological assessments" to the LLM.
+
+For regulatory/EGBC-stamped work, use the extended disclaimer from `soul/research/20260212_ai_disclosure_research.md`. See NewGraphEnvironment/mybookdown-template#89.
+
+## Conditional Rendering (Gitbook vs PDF)
+
+A single boolean `gitbook_on` controls output format throughout.
+
+```r
+# Show only in gitbook
+{r map-interactive, eval=gitbook_on}
+
+# Show only in PDF
+{r fig-print-only, eval=identical(gitbook_on, FALSE)}
+
+# Conditional inline content
+`r if(identical(gitbook_on, FALSE)) knitr::asis_output("This report is available online...")`
+
+# Page breaks for PDF only
+`r if(gitbook_on){knitr::asis_output("")} else knitr::asis_output("\\pagebreak")`
+```
+
+## Versioning and Changelog
+
+Reports use MAJOR.MINOR.PATCH versioning with a `NEWS.md` changelog.
+
+**Version in `index.Rmd` YAML:**
+```yaml
+date: |
+ |
+ | Version 1.1.0 DRAFT `r format(Sys.Date(), "%Y-%m-%d")`
+```
+
+**NEWS.md format:**
+```markdown
+## 1.1.0 (2026-02-17)
+
+- Add feature X
+- Fix issue Y ([Issue #N](https://github.com/Org/repo/issues/N))
+```
+
+**Auto-append as appendix** via `my_news_to_appendix()` in `staticimports.R`:
+```r
+news_to_appendix(md_name = "NEWS.md", rmd_name = "2090-report-change-log.Rmd")
+```
+
+**Convention:**
+- Bump version in `index.Rmd` and add NEWS entry for every commit to main that changes report content
+- Tag releases: `git tag -a v1.1.0 -m "v1.1.0: Brief description"`
+- MAJOR: structural changes, new chapters, methodology changes
+- MINOR: new content, figures, tables, discussion sections
+- PATCH: prose fixes, corrections, formatting
+
+## COG Viewer Embedding
+
+Always use `ngr::ngr_str_viewer_cog()` — never hardcode viewer iframes.
+
+```r
+knitr::asis_output(ngr::ngr_str_viewer_cog("https://bucket.s3.us-west-2.amazonaws.com/ortho.tif"))
+```
+
+The function includes a cache-busting `?v=` parameter. Bump `v` in the function default when `viewer.html` has breaking changes.
+
+## Dependency Management
+
+Use `renv` for reproducible package management:
+- `.Rprofile` activates renv on startup
+- `renv::restore()` installs from lockfile
+- `renv::snapshot()` updates lockfile after adding packages
+- Use `pak::pak("pkg")` to install (not `install.packages`)
+
+## Known Drift
+
+Production repos (2024-2025) have drifted from templates in these areas. When working in a child repo, match what that repo does, not the template:
+
+- **Script naming in `02_reporting/`** — older repos use `tables.R`, `0165-read-sqlite.R`; newer repos use numbered `0130-tables.R`. Follow the repo you're in.
+- **Removed packages** — `elevatr`, `rayshader`, `arrow` removed from production but still in template.
+- **`staticimports::import()` call** — some repos skip it and source `staticimports.R` directly.
+- **Hardcoded vs parameterized years** — older repos hardcode years in file paths; newer repos use `params$project_year`. Prefer parameterized.
+
+# Cartography
+
+## Style Registry
+
+Use the `gq` package for all shared layer symbology. Never hardcode hex color values when a registry style exists.
+
+```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"))
+```
+
+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 |
+
+## Key Rules
+
+- **`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)
+
+## Self-Review (after every render)
+
+Read the PNG and check before showing anyone:
+
+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?
+
+See the `cartography` skill for full reference: basemap blending, BC spatial data queries, label hierarchy, mapgl gotchas, and worked examples.
+
+## Land Cover Change
+
+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)
+
+# Code Check Conventions
+
+Structured checklist for reviewing diffs before commit. Used by `/code-check`.
+Add new checks here when a bug class is discovered — they compound over time.
+
+## Shell Scripts
+
+### Quoting
+- Variables in double-quoted strings containing single quotes break if value has `'`
+- `"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
+
+### Paths
+- Hardcoded absolute paths (`/Users/airvine/...`) break for other users
+- Use `REPO_ROOT="$(cd "$(dirname "$0")/<relative>" && pwd)"`
+- After moving scripts, verify `../` depth still resolves correctly
+- Usage comments should match actual script location
+
+### Silent Failures
+- `|| true` hides real errors — is the failure actually safe to ignore?
+- Empty variable before destructive operation (rm, destroy) — add guard: `[ -n "$VAR" ] || exit 1`
+- `grep` returning empty silently — downstream commands get empty input
+
+### Process Visibility
+- Secrets passed as command-line args are visible in `ps aux`
+- Use env files, stdin pipes, or temp files with `chmod 600` instead
+
+## Cloud-Init (YAML)
+
+### ASCII
+- Must be pure ASCII — em dashes, curly quotes, arrows cause silent parse failure
+- Check with: `perl -ne 'print "$.: $_" if /[^\x00-\x7F]/' file.yaml`
+
+### 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)
+
+### Template Variables
+- Secrets rendered via `templatefile()` are readable at `169.254.169.254` metadata endpoint
+- Acceptable for ephemeral machines, document the tradeoff
+
+## OpenTofu / Terraform
+
+### State
+- Parsing `tofu state show` text output is fragile — use `tofu output` instead
+- Missing outputs that scripts need — add them to main.tf
+- Snapshot/image IDs in tfvars after deleting the snapshot — stale reference
+
+### 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
+
+## Security
+
+### Secrets in Committed Files
+- `.tfvars` must be gitignored (contains tokens, passwords)
+- `.tfvars.example` should have all variables with empty/placeholder values
+- Sensitive variables need `sensitive = true` in variables.tf
+
+### Firewall Defaults
+- `0.0.0.0/0` for SSH is world-open — document if intentional
+- If access is gated by Tailscale, say so explicitly
+
+### Credentials
+- Passwords with special chars (`'`, `"`, `$`, `!`) break naive shell quoting
+- `printf '%q'` escapes values for shell safety
+- Temp files for secrets: create with `chmod 600`, delete after use
+
+## R / Package Installation
+
+### pak Behavior
+- pak stops on first unresolvable package — all subsequent packages are skipped
+- Removed CRAN packages (like `leaflet.extras`) must move to GitHub source
+- PPPM binaries may lag a few hours behind new CRAN releases
+
+### Reproducibility
+- Branch pins (`pkg@branch`) are not reproducible — document why used
+- Pinned download URLs (RStudio .deb) go stale — document where to update
+
+## General
+
+### Diff Hygiene
+- Every changed line should trace to the task — no drive-by cleanups
+- New files need: are they gitignored if sensitive? executable if scripts?
+- Deleted files: check for references in other files, docs, READMEs
+
+### Documentation Staleness
+- Moving/renaming scripts: update CLAUDE.md, READMEs, usage comments
+- New variables: update .tfvars.example
+- New workflows: update relevant README
+
+# Communications Conventions
+
+Standards for external communications across New Graph Environment.
+
+[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.
+
+## Tone
+
+Three levels. Default to casual unless context dictates otherwise.
+
+| 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. |
+
+**Collaborative, not directive.** Acknowledge their constraints:
+
+- **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"
+
+## Email Workflow
+
+Draft in markdown, convert to HTML at send time via gmailr. See compost for script templates, OAuth setup, and `search_gmail.R`.
+
+**File naming:** `YYYYMMDD_recipient_topic_draft.md` + `YYYYMMDD_recipient_topic.R`
+
+**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
+
+## Data in Emails
+
+- **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
+
+## What Not to Expose Externally
+
+- Internal QA info (blanks, control samples, calibration data)
+- Internal tracking codes or SRED references
+- Draft status or revision history
+- Internal project management details
+
+Keep client-facing communications focused on deliverables and technical content.
+
+## Signature
+
+```
+Al Irvine B.Sc., R.P.Bio.
+New Graph Environment Ltd.
+
+Cell: 250-777-1518
+Email: al@newgraphenvironment.com
+Website: www.newgraphenvironment.com
+```
+
+In HTML emails, use `<br>` tags between lines.
+
+# LLM Behavioral Guidelines
+
+<!-- Source: https://github.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md -->
+<!-- Last synced: 2026-02-06 -->
+<!-- These principles are hardcoded locally. We do not curl at deploy time. -->
+<!-- Periodically check the source for meaningful updates. -->
+
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+---
+
+**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" |
+| [awshak](https://github.com/NewGraphEnvironment/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.
+
+- **Cite primary sources** — when a review paper references an older study, trace back to the original and cite it. Don't attribute findings to the review when the original exists.
+- **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.
+
+## 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)** |
+
+# PR Review Automation
+
+Automated PR review and interactive Claude mentions using Claude Code GitHub Action.
+
+## Setup (per repo)
+
+1. **Install the Claude Code GitHub App** via `/install-github-app`
+   - Sets `CLAUDE_CODE_OAUTH_TOKEN` as a repo secret automatically
+   - Uses Max subscription (flat $200/mo, not per-token)
+
+2. **Enable the workflow** via `/claude-review-enable`
+   - Choose mode: **review** (auto PR review + @claude mentions) or **mention** (@claude only)
+   - Pushes the workflow template to `.github/workflows/claude.yml`
+
+3. **Ensure CLAUDE.md exists** in the repo — the action reads it automatically.
+   Use `/claude-md-init` to set up if missing.
+
+## What It Does
+
+### Automatic PR Review (Haiku)
+On every PR open/update, Claude reviews the diff and posts:
+- **Inline comments** on specific lines with issues
+- **Summary comment** with overall assessment
+- Uses Haiku for speed and cost (~$0.01-0.05 per review)
+
+### Interactive @claude Mentions (Sonnet)
+Comment `@claude <request>` on any issue or PR. Claude can:
+- Answer questions about the codebase
+- Create branches and open PRs from issue descriptions
+- Fix code and push commits
+- Run slash commands: `@claude /review`
+- Uses Sonnet for deeper reasoning
+
+## Model Selection
+
+| Job | Model | Why |
+|-----|-------|-----|
+| Auto-review | Haiku 4.5 | Fast, cheap, good enough for style/lint/bug checks |
+| Interactive | Sonnet 4.5 | Needs reasoning for code changes, PR creation |
+
+To override, edit `claude_args` in the workflow:
+```yaml
+claude_args: |
+  --model claude-sonnet-4-5-20250929
+```
+
+Available models (use exact IDs):
+- `claude-haiku-4-5-20251001` — cheapest, fastest
+- `claude-sonnet-4-5-20250929` — balanced
+- `claude-opus-4-6` — most capable, expensive
+
+## Interactive Examples
+
+```
+@claude what does the validate_crossing function do?
+@claude fix the failing lintr checks and open a PR
+@claude /review — focus on the database query performance
+@claude add tests for the new helper functions in R/utils.R
+```
+
+## Bot Workflow (for OpenClaw bots opening PRs)
+
+When a bot opens a PR, it should:
+
+1. **Push the PR** and wait for the Claude review action to complete
+2. **Read review comments** via `gh pr view --comments`
+3. **Fix no-brainers** automatically: lint issues, typos, missing imports
+4. **Ask humans** for judgment calls: architecture, logic changes, scope
+5. **Push fix commits** to re-trigger the review
+6. **Stop after 3 rounds** — if still failing, tag a human reviewer
+
+## Cost
+
+| Model | Input | Output | Typical review |
+|-------|-------|--------|----------------|
+| Haiku 4.5 | $1/M | $5/M | ~$0.01-0.05 |
+| Sonnet 4.5 | $3/M | $15/M | ~$0.05-0.25 |
+| Opus 4.6 | $15/M | $75/M | ~$0.25-1.00 |
+
+Use `--max-turns` to cap iterations and cost.
+
+## Reference
+
+- [claude-code-action](https://github.com/anthropics/claude-code-action)
+- [Setup guide](https://github.com/anthropics/claude-code-action/blob/main/docs/setup.md)
+
+# R Package Development Conventions
+
+Standards for R package development across New Graph Environment repositories.
+Based on [R Packages (2e)](https://r-pkgs.org/) by Hadley Wickham and Jenny Bryan.
+
+**Reference packages:** When starting a new package, study these existing
+packages for patterns: `flooded`, `gq`. They demonstrate the conventions below
+in practice (DESCRIPTION fields, README layout, NEWS.md style, pkgdown setup,
+test structure, hex sticker, etc.).
+
+## Style
+
+- tidyverse style guide: snake_case, pipe operators (`|>` or `%>%`)
+- Match existing patterns in each codebase
+- Use `pak` for package installation (not `install.packages`)
+
+## Package Structure
+
+Follow R Packages (2e) conventions:
+- `R/` for functions, `tests/testthat/` for tests, `man/` for docs
+- `DESCRIPTION` with proper fields (Title, Description, Authors@R)
+- `DESCRIPTION` URL field: include both the GitHub repo and the pkgdown site
+  so pkgdown links correctly (e.g., `URL: https://github.com/OWNER/PKG,
+  https://owner.github.io/PKG/`)
+- `NAMESPACE` managed by roxygen2 (`#' @export`, `#' @import`, `#' @importFrom`)
+- Never edit `NAMESPACE` or `man/` by hand
+
+## One Function, One File
+
+Each exported function gets its own R file and its own test file:
+- `R/fl_mask.R` → `tests/testthat/test-fl_mask.R`
+- Commit the function and its tests together
+- Use `Fixes #N` in the commit message to close the corresponding issue
+
+## GitHub Issues and SRED Tracking
+
+### Issue-per-function workflow
+
+File a GitHub issue for each function before building it. This creates a
+traceable record of what was planned, built, and verified.
+
+### Branching for SRED
+
+For new packages or major features, work on a branch and merge via PR:
+
+```
+main ← scaffold-branch (PR closes with "Relates to NewGraphEnvironment/sred-2025-2026#N")
+```
+
+This gives one PR that contains all commits — a single SRED cross-reference
+covers the entire body of work. Individual commits within the branch close
+their respective function issues with `Fixes #N`.
+
+### Closing issues
+
+Close function issues via commit messages (not `gh issue close`) so the
+diff is linked:
+
+```
+Add fl_mask() with threshold and operator support
+
+Fixes #3
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+```
+
+## Testing
+
+- Use testthat 3e (`Config/testthat/edition: 3` in DESCRIPTION)
+- Run `devtools::test()` before committing
+- Test files mirror source: `R/utils.R` -> `tests/testthat/test-utils.R`
+- Test for edge cases and potential failures, not just happy paths
+- Tests must pass before closing the function's issue
+
+## Examples and Vignettes
+
+### Runnable examples on every exported function
+
+Examples are how users discover what a function does. They must:
+- **Actually run** — no `\dontrun{}` unless external resources are required
+- **Use bundled test data** via `system.file()` so they work for anyone
+- **Show why the function is useful** — not just that it runs, but what it
+  produces and why you'd use it
+- **Use qualified names** for non-exported dependencies (`terra::rast()`,
+  `sf::st_read()`) since examples run in the user's environment
+
+### Vignettes
+
+At least one vignette showing the full pipeline on real data:
+- Demonstrates the package solving an actual problem end-to-end
+- Uses bundled test data (committed to `inst/testdata/`)
+- Hosted on pkgdown so users can read it without installing
+
+### Test data
+
+- Created via a script in `data-raw/` that documents exactly how the data
+  was produced (database queries, spatial crops, etc.)
+- Committed to `inst/testdata/` — small enough to ship with the package
+- Used by tests, examples, and vignettes — one dataset, three purposes
+
+## Documentation
+
+- roxygen2 for all exported functions
+- `@import` or `@importFrom` in the package-level doc (`R/<pkg>-package.R`)
+  to populate NAMESPACE — don't rely on `::` everywhere in function bodies
+- pkgdown site for public packages with `_pkgdown.yml` (bootstrap 5)
+- GitHub Action for pkgdown (`usethis::use_github_action("pkgdown")`)
+
+## lintr
+
+Run `lintr::lint_package()` before committing R package code. Fix all warnings — every lint should be worth fixing.
+
+### Recommended .lintr config
+
+```r
+linters: linters_with_defaults(
+    line_length_linter(120),
+    object_name_linter(styles = c("snake_case", "dotted.case")),
+    commented_code_linter = NULL
+  )
+exclusions: list(
+    "renv" = list(linters = "all")
+  )
+```
+
+- 120 char line length (default 80 is too strict for data pipelines)
+- Allow dotted.case (common in base R and legacy code)
+- Suppress commented code lints (exploratory R scripts often have commented alternatives)
+- Exclude renv directory entirely
+
+## Dependencies
+
+- Minimize Imports — use `Suggests` for packages only needed in tests/vignettes
+- Pin versions only when breaking changes are known
+- Prefer packages already in the tidyverse ecosystem
+
+## Releasing
+
+1. Update `NEWS.md` — keep it concise:
+   - First release: one line (e.g., "Initial release. Brief description.")
+   - Later releases: describe what changed and why, not function-by-function.
+     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`)
+3. Commit as "Release vX.Y.Z"
+4. Tag: `git tag vX.Y.Z && git push && git push --tags`
+
+## Repository Setup
+
+### Branch protection
+
+Protect main from deletion and force pushes. Admin bypasses so you can
+push directly:
+
+```bash
+gh api repos/OWNER/REPO/rulesets --method POST --input - <<'EOF'
+{
+  "name": "Protect main",
+  "target": "branch",
+  "enforcement": "active",
+  "bypass_actors": [
+    { "actor_id": 5, "actor_type": "RepositoryRole", "bypass_mode": "always" }
+  ],
+  "conditions": { "ref_name": { "include": ["refs/heads/main"], "exclude": [] } },
+  "rules": [ { "type": "deletion" }, { "type": "non_fast_forward" } ]
+}
+EOF
+```
+
+### Scaffold checklist
+
+- `usethis::create_package(".")`
+- `usethis::use_mit_license("New Graph Environment Ltd.")`
+- `usethis::use_testthat(edition = 3)`
+- `usethis::use_pkgdown()`
+- `usethis::use_github_action("pkgdown")`
+- `usethis::use_directory("dev")` — reproducible setup script
+- `usethis::use_directory("data-raw")` — data generation scripts
+- Hex sticker via `hexSticker` (see `data-raw/make_hexsticker.R`)
+- Set GitHub Pages to serve from `gh-pages` branch
+
+### dev/dev.R
+
+Keep a `dev/dev.R` file that documents every setup step. Not idempotent —
+run interactively. This is the reproducible recipe for the package scaffold.
+
+## README
+
+Keep the README lean:
+- Hex sticker, one-line description, install, example showing *why* it's
+  useful
+- Link to pkgdown vignette and function reference — don't duplicate them
+- Don't maintain a function table — it's just another thing to keep updated
+  and pkgdown's reference page is the single source of truth
+
+## LLM Workflow
+
+When an LLM assistant modifies R package code:
+1. Run `lintr::lint_package()` — fix issues before committing
+2. Run `devtools::test()` — ensure tests pass
+3. Run `devtools::document()` if roxygen comments changed
+4. Check `devtools::check()` passes for releases
+
+# Reference Management Conventions
+
+How references flow between Claude Code, Zotero, and technical writing at New Graph Environment.
+
+## Tool Routing
+
+Three tools, different purposes. Use the right one.
+
+| Need | Tool | Why |
+|------|------|-----|
+| Search by keyword, read metadata/fulltext, semantic search | **MCP `zotero_*` tools** | pyzotero, works with Zotero item keys |
+| Look up by citation key (e.g., `irvine2020ParsnipRiver`) | **`/zotero-lookup` skill** | Citation keys are a BBT feature — pyzotero can't resolve them |
+| Create items, attach PDFs, deduplicate | **`/zotero-api` skill** | Connector API for writes, JS console for attachments |
+
+**Citation keys vs item keys:** Citation keys (like `irvine2020ParsnipRiver`) come from Better BibTeX. Item keys (like `K7WALMSY`) are native Zotero. The MCP works with item keys. `/zotero-lookup` bridges citation keys to item data.
+
+**BBT citation key storage:** As of Feb 2025+, BBT stores citation keys as a `citationKey` field directly in `zotero.sqlite` (via Zotero's item data system), not in a separate BBT database. The old `better-bibtex.sqlite` and `better-bibtex.migrated` files are stale and no longer updated. Query citation keys with: `SELECT idv.value FROM items i JOIN itemData id ON i.itemID = id.itemID JOIN itemDataValues idv ON id.valueID = idv.valueID JOIN fields f ON id.fieldID = f.fieldID WHERE f.fieldName = 'citationKey'`.
+
+## Adding References Workflow
+
+### 1. Search and flag
+
+When research turns up a reference:
+- **DOI available:** Tell the user — Zotero's magic wand (DOI lookup) is the fastest path
+- **ResearchGate link:** Flag to user for manual check — programmatic fetch is blocked (403), but full text is often there
+- **BC gov report:** Search [ACAT](https://a100.gov.bc.ca/pub/acat/), for.gov.bc.ca library, EIRS viewer
+- **Paywalled:** Note it, move on. Don't waste time trying to bypass.
+
+### 2. Add to Zotero
+
+**Preferred order:**
+1. DOI magic wand in Zotero UI (fastest, most complete metadata)
+2. `saveItems` via `/zotero-api` (good for batch creation from structured data)
+3. JS console script for group library (when connector can't target the right collection)
+
+**Collection targeting:** `saveItems` drops items into whatever collection is selected in Zotero's UI. Always confirm with the user before calling it.
+
+### 3. Attach PDFs
+
+`saveItems` attachments silently fail. Don't use them. Instead:
+
+1. Download with `curl` (see `/zotero-api` skill for source-specific patterns)
+2. Attach via `item_attach_pdf.js` in Zotero JS console
+3. Verify attachment exists via MCP: `zotero_get_item_children`
+
+### 4. Verify
+
+After manual adds, confirm via MCP:
+- `zotero_search_items` — find by title
+- `zotero_get_item_metadata` — check fields are complete
+- `zotero_get_item_children` — confirm PDF attached
+
+### 5. Clean up
+
+If duplicates were created (common with `saveItems` retries):
+- Run `collection_dedup.js` via Zotero JS console
+- It keeps the copy with the most attachments, trashes the rest
+
+## In Reports (bookdown)
+
+### Bibliography generation
+
+```yaml
+# index.Rmd — dynamic bib from Zotero via Better BibTeX
+bibliography: "`r rbbt::bbt_write_bib('references.bib', overwrite = TRUE)`"
+```
+
+`rbbt` pulls from BBT, which syncs with Zotero. Edit references in Zotero → rebuild report → bibliography updates.
+
+**Library targeting:** rbbt must know which Zotero library to search. This is set globally in `~/.Rprofile`:
+
+```r
+# default library — NewGraphEnvironment group (libraryID 9, group 4733734)
+options(rbbt.default.library_id = 9)
+```
+
+Without this option, rbbt searches only the personal library (libraryID 1) and won't find group library references. The library IDs map to Zotero's internal numbering — use `/zotero-lookup` with `SELECT DISTINCT libraryID FROM citationkey` against the BBT database to discover available libraries.
+
+### Citation syntax
+
+- `[@key2020]` — parenthetical: (Author 2020)
+- `@key2020` — narrative: Author (2020)
+- `[@key1; @key2]` — multiple
+- `nocite:` in YAML — include uncited references
+
+### Cite primary sources
+
+When a review paper references an older study, trace back to the original and cite it. Don't attribute findings to the review when the original exists. (See LLM Agent Conventions in `newgraph.md`.)
+
+**When the original is unavailable** (paywalled, out of print, can't locate): use secondary citation format in the prose and include bib entries for both sources:
+
+> Smith et al. (2003; as cited in Doctor 2022) found that...
+
+Both `@smith2003` and `@doctor2022` go in the `.bib` file. The reader can then track down the original themselves. Flag incomplete metadata on the primary entry — it's better to have a partial reference than none at all.
+
+## PDF Fallback Chain
+
+When you need a PDF and the obvious URL doesn't work:
+
+1. DOI resolver → publisher site (often has OA link)
+2. Europe PMC (`europepmc.org/backend/ptpmcrender.fcgi?accid=PMC{ID}&blobtype=pdf`) — ncbi blocks curl
+3. SciELO — needs `User-Agent: Mozilla/5.0` header
+4. ResearchGate — flag to user for manual download
+5. Semantic Scholar — sometimes has OA links
+6. Ask user for institutional access
+
+Always verify downloads: `file paper.pdf` should say "PDF document", not HTML.
+
+# SRED Conventions
+
+How SR&ED (Scientific Research and Experimental Development) 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
+- **Status:** Ongoing
+- **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.
+
+## What We're Building
+
+The SRED investment is in the **system**, not the reports it produces. Reports are service revenue. The framework is the IP and the competitive asset.
+
+The system is an integrated, version-controlled framework that:
+- Generates GIS projects from parameterized inputs
+- Synchronizes field data collection with cloud-hosted databases and portable GeoPackages
+- Processes and catalogs UAV imagery via STAC pipelines
+- Produces dynamic, reproducible reports (bookdown/Quarto)
+- Orchestrates workflows via LLM agents with shared conventions and skills
+- Manages communications, time tracking, and evidence as part of the framework
+
+No other environmental consultancy has this level of integration. This is the international competitiveness that SRED exists to incentivize.
+
+## System Components
+
+| Layer | Repos | Role in Framework |
+|-------|-------|-------------------|
+| **Agent governance** | soul | Conventions, skills, settings — how agents behave across all repos |
+| **Communications** | compost | Centralized email workflows, contact management, tone standards |
+| **Operations** | rolex | Time tracking, invoicing, SRED evidence, budget management |
+| **Infrastructure** | awshak | IaC (OpenTofu), S3, IAM, CORS, OIDC — reproducible cloud environments |
+| **GIS automation** | rfp, ngr, dff-2022 | QGIS project generation, spatial data processing, layer management |
+| **Imagery** | stac_uav, stac_orthophoto_bc | UAV processing, STAC cataloging, containerized pipelines |
+| **Change detection** | drift, flooded | Floodplain delineation, STAC land cover fetch, multi-temporal change analysis |
+| **Citations** | xciter | Pandoc hooks for citations in interactive tables |
+| **Data** | db_newgraph, bcfishpass, fwapg | PostgreSQL spatial databases, modelling, query APIs |
+| **Field collection** | Mergin Maps projects | Mobile forms, offline GeoPackages, bidirectional sync |
+| **Reporting** | Annual project repos | Bookdown reports consuming all of the above |
+
+## Fiscal Year Iterations
+
+Each fiscal year, Boast structures the claim as iterations within the project. Our internal experiment numbers map to these.
+
+### FY2024 (May 2023 – April 2024)
+
+Single narrative: version control for GIS projects + dynamic reporting engine.
+
+### FY2025 (May 2024 – April 2025)
+
+| Iteration | Focus | Key Repos |
+|-----------|-------|-----------|
+| 1 | GIS–RMarkdown synchronization | rfp, ngr, dff-2022 |
+| 2 | UAV imagery + STAC cataloging | stac_uav, stac_orthophoto_bc |
+| 3 | Citation handling (xciter) | xciter |
+| 4 | Field-to-cloud data workflows | Mergin, PostgreSQL, GeoPackages |
+| 5 | Infrastructure as Code | awshak |
+
+### FY2026 (May 2025 – April 2026)
+
+| Iteration | Focus | Key Repos |
+|-----------|-------|-----------|
+| TBD | LLM agent orchestration & governance | soul, agent teams |
+| TBD | Communications workflow | compost |
+| TBD | Time tracking & evidence management | rolex |
+| TBD | MCP integrations (Zotero, PostgreSQL, Harvest, Xero) | soul settings, MCP configs |
+| TBD | Continued GIS/reporting improvements | rfp, ngr, bookdown repos |
+
+Iteration numbers are assigned by Boast in the final report. We provide evidence organized by theme.
+
+## Tagging Work for SRED
+
+### Commits
+
+Use `Relates to NewGraphEnvironment/sred-2025-2026#N` in commit messages when work is SRED-eligible. The `/sred-commit` skill handles this.
+
+### Time entries (rolex)
+
+Tag hours with `sred_experiment` field linking to the relevant `sred-2025-2026` issue number. This enables automated evidence reports.
+
+### GitHub issues
+
+Link SRED-eligible issues to the tracking repo: `Relates to NewGraphEnvironment/sred-2025-2026#N`
+
+## What Qualifies as SRED
+
+From the Boast interview guide and CRA guidelines:
+
+**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 (but still important to document as due diligence):**
+- Evaluating existing tools to confirm they can't meet requirements
+- 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.
+
+## SRED and Contractors
+
+Subcontractors are eligible for SRED at a reduced rate (~32% vs ~64% for T4 employees). Arm's length, Canadian contractors only. The work must be performed in Canada.
+
+For core SRED work, T4 employees generate roughly 2x the credit per dollar spent. Use contractors when needed but be aware of the credit differential.
+
+## Evidence for Boast
+
+At fiscal year-end, Boast needs:
+1. **Time records** — hours by person, tagged to iterations (from rolex)
+2. **Technical narrative** — what was attempted, what worked, what didn't (from commit history, issues, PRs)
+3. **Financial summary** — wages, contractor payments, expenses (from rolex + Xero)
+4. **GitHub evidence** — commits, issues, PRs showing systematic investigation (from `sred-2025-2026` cross-references)
+
+The better our tagging during the year, the less work at claim time.
+
+## Fiscal Calendar
+
+| Period | Dates |
+|--------|-------|
+| FY2024 | May 1 2022 – April 30 2024 |
+| FY2025 | May 1 2024 – April 30 2025 |
+| FY2026 | May 1 2025 – April 30 2026 |
+
+Claims are filed within 18 months of fiscal year-end.
diff --git a/DESCRIPTION b/DESCRIPTION
index bfbc3bd..4561e17 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -1,6 +1,6 @@
 Package: flooded
 Title: Portable Floodplain Delineation from DEM and Stream Network
-Version: 0.1.0
+Version: 0.1.1
 Authors@R: c(
     person("Allan", "Irvine", , "al@newgraphenvironment.com", role = c("aut", "cre"),
            comment = c(ORCID = "0000-0002-3495-2128")),
@@ -36,6 +36,8 @@ Suggests:
     whitebox,
     testthat (>= 3.0.0),
     knitr,
-    rmarkdown
+    rmarkdown,
+    rstac,
+    gdalcubes
 Config/testthat/edition: 3
 VignetteBuilder: knitr
diff --git a/NEWS.md b/NEWS.md
index b5cf0d4..4129b4b 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,3 +1,12 @@
+# flooded 0.1.1
+
+* Add STAC DEM vignette comparing 25 m TRIM (resampled to 10 m) with native
+  1 m lidar — includes site-level zoom and pop-up analysis quantifying
+  anthropogenic barriers to floodplain connectivity.
+* Add `bcdata` reproducibility script (`data-raw/testdata_bcdata.R`).
+* Add resolution and restoration section to README.
+* Pre-build STAC vignette for fast pkgdown rendering.
+
 # flooded 0.1.0
 
 * Initial release. Valley Confinement Algorithm (VCA) pipeline for floodplain
diff --git a/README.md b/README.md
index f3f3d56..c1b007f 100644
--- a/README.md
+++ b/README.md
@@ -44,6 +44,12 @@ flood_depth    = bankfull_depth * flood_factor
 
 Both `upstream_area` (hectares) and `precip` (mean annual precipitation, mm) are important — omitting precipitation underestimates flood depth by ~4x.
 
+## Resolution and restoration
+
+`flooded` is DEM-agnostic — any source works. But resolution changes what you can see. At 25 m (e.g. the provincial TRIM DEM), the floodplain appears as one continuous surface. At 1 m lidar, anthropogenic features emerge: roads, railway grades, dykes, and agricultural fill that sit above the flood surface and block lateral connectivity.
+
+The gap between coarse and fine results is a diagnostic: it shows **what is preventing floodplain from functioning** and **where to act** — removing fill, breaching dykes, or installing crossings to reconnect floodplain. See the [STAC DEM vignette](https://newgraphenvironment.github.io/flooded/articles/stac-dem.html) for a worked example comparing 25 m TRIM with 1 m lidar on the Neexdzii Kwah (Bulkley River).
+
 ## Performance
 
 Set `terra` threads before running the pipeline to enable multi-core processing:
diff --git a/data-raw/testdata_bcdata.R b/data-raw/testdata_bcdata.R
new file mode 100644
index 0000000..e7c928f
--- /dev/null
+++ b/data-raw/testdata_bcdata.R
@@ -0,0 +1,96 @@
+#!/usr/bin/env Rscript
+#
+# testdata_bcdata.R
+#
+# Reproduce the bundled 10m test DEM without the bcfishpass database.
+# Uses bcdata (Python CLI by Simon Norris) to fetch the 25m provincial DEM
+# from BC Data Catalogue WCS, then resamples to 10m with bilinear
+# interpolation — the same approach used by bcfishpass habitat_lateral.
+#
+# This is an internal reproducibility reference, not user-facing.
+# The bundled test data in inst/testdata/ is generated by testdata.R
+# (which reads from the bcfishpass BULK DEM). This script documents
+# an alternative path that doesn't require the database.
+#
+# Prerequisites:
+#   - Python with bcdata installed: pip install bcdata
+#   - R packages: terra, sf
+#
+# Pattern from:
+#   bcfishpass/model/03_habitat_lateral/valley_confinement.py
+#     bcdata.get_dem(bounds, path, as_rasterio=True, align=True)
+#     gdaldem slope -p dem.tif slope.tif
+#
+# Output:
+#   data-raw/dem_bcdata_25m.tif  — raw 25m DEM from BC Data Catalogue
+#   data-raw/dem_bcdata_10m.tif  — resampled to 10m (bilinear)
+#   data-raw/slope_bcdata_10m.tif — percent slope from 10m DEM
+
+library(terra)
+library(sf)
+
+# --- Test area extent (same as inst/testdata/) ---
+# Neexdzii Kwah near Topley, BC Albers EPSG:3005
+xmin <- 975728
+xmax <- 983728
+ymin <- 1054058
+ymax <- 1060538
+
+out_dir <- here::here("data-raw")
+
+# --- Download 25m DEM via bcdata CLI ---
+# bcdata get-dem fetches from BC Data Catalogue WCS
+# bounds format: xmin,ymin,xmax,ymax in EPSG:3005
+dem_25m_path <- file.path(out_dir, "dem_bcdata_25m.tif")
+
+if (!file.exists(dem_25m_path)) {
+  bounds <- paste(xmin, ymin, xmax, ymax, sep = ",")
+  cmd <- paste(
+    "bcdata", "get-dem",
+    "--bounds", bounds,
+    "--src_crs", "EPSG:3005",
+    "--dst_crs", "EPSG:3005",
+    dem_25m_path
+  )
+  message("Downloading 25m DEM via bcdata...")
+  message("  Command: ", cmd)
+  system(cmd)
+} else {
+  message("25m DEM already exists: ", dem_25m_path)
+}
+
+# --- Resample to 10m (bilinear, matching bcfishpass pattern) ---
+dem_10m_path <- file.path(out_dir, "dem_bcdata_10m.tif")
+
+message("Resampling 25m -> 10m (bilinear)...")
+dem_25m <- terra::rast(dem_25m_path)
+
+# Create 10m template matching the test data extent
+template_10m <- terra::rast(
+  xmin = xmin, xmax = xmax,
+  ymin = ymin, ymax = ymax,
+  resolution = 10,
+  crs = "EPSG:3005"
+)
+
+dem_10m <- terra::resample(dem_25m, template_10m, method = "bilinear")
+terra::writeRaster(dem_10m, dem_10m_path, overwrite = TRUE)
+
+# --- Derive slope (percent, matching gdaldem slope -p) ---
+slope_10m_path <- file.path(out_dir, "slope_bcdata_10m.tif")
+
+message("Deriving percent slope...")
+slope_deg <- terra::terrain(dem_10m, "slope", unit = "degrees")
+slope_pct <- tan(slope_deg * pi / 180) * 100
+terra::writeRaster(slope_pct, slope_10m_path, overwrite = TRUE)
+
+# --- Summary ---
+message("\nOutputs:")
+message("  25m DEM: ", dem_25m_path, " (",
+        round(file.size(dem_25m_path) / 1e6, 1), " MB)")
+message("  10m DEM: ", dem_10m_path, " (",
+        round(file.size(dem_10m_path) / 1e6, 1), " MB)")
+message("  Slope:   ", slope_10m_path, " (",
+        round(file.size(slope_10m_path) / 1e6, 1), " MB)")
+message("  Extent:  ", paste(xmin, xmax, ymin, ymax, sep = ", "), " (EPSG:3005)")
+message("  Res:     ", paste(res(dem_10m), collapse = " x "), " m")
diff --git a/vignettes/figure/plot-compare-1.png b/vignettes/figure/plot-compare-1.png
new file mode 100644
index 0000000..ccbf43d
Binary files /dev/null and b/vignettes/figure/plot-compare-1.png differ
diff --git a/vignettes/figure/site-compare-1.png b/vignettes/figure/site-compare-1.png
new file mode 100644
index 0000000..95c1fce
Binary files /dev/null and b/vignettes/figure/site-compare-1.png differ
diff --git a/vignettes/stac-dem.Rmd b/vignettes/stac-dem.Rmd
new file mode 100644
index 0000000..4f7b855
--- /dev/null
+++ b/vignettes/stac-dem.Rmd
@@ -0,0 +1,463 @@
+---
+title: "Bring your own DEM via STAC"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Bring your own DEM via STAC}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+
+
+`flooded` works with any DEM — it doesn't require a specific source. This
+vignette demonstrates fetching 1 m lidar tiles from a STAC catalog and
+comparing the resulting floodplain with the bundled 10 m DEM.
+
+We use the same Neexdzii Kwah test area (Bulkley River near Topley, BC) as
+the main vignette, but source the DEM from
+[stac-dem-bc](https://images.a11s.one/) — a STAC collection of BC provincial
+lidar DEMs.
+
+## Setup
+
+
+``` r
+library(flooded)
+library(terra)
+#> terra 1.8.93
+library(sf)
+#> Linking to GEOS 3.13.0, GDAL 3.8.5, PROJ 9.5.1; sf_use_s2() is TRUE
+library(rstac)
+library(gdalcubes)
+#> 
+#> Attaching package: 'gdalcubes'
+#> The following objects are masked from 'package:terra':
+#> 
+#>     animate, crop, size
+
+terra::terraOptions(threads = 12)
+```
+
+## What does "resampled to 10 m" mean?
+
+The bundled test DEM is the 25 m BC TRIM DEM resampled to a 10 m grid using
+bilinear interpolation. That means each original 25 m pixel gets split into
+smaller 10 m pixels, with values smoothly blended from neighbours. The grid is
+genuinely 10 m — each cell is 10 m × 10 m — but the terrain detail is still
+25 m quality. It's like zooming into a low-resolution photo: the image gets
+bigger but not sharper. No real topographic detail is added.
+
+In contrast, the 1 m lidar tiles from the STAC catalog are *natively* 1 m.
+They capture real features at that scale — side channels, terrace edges, drainage
+ditches — that a 25 m DEM physically cannot see, no matter how finely you
+resample it.
+
+## Bundled 10 m baseline
+
+First, load the bundled test data and run the VCA to establish a baseline.
+
+
+``` r
+dem_10m <- rast(system.file("testdata/dem.tif", package = "flooded"))
+slope_10m <- rast(system.file("testdata/slope.tif", package = "flooded"))
+streams <- st_read(
+  system.file("testdata/streams.gpkg", package = "flooded"),
+  quiet = TRUE
+)
+
+precip_r <- fl_stream_rasterize(streams, dem_10m, field = "map_upstream")
+
+valleys_10m <- fl_valley_confine(
+  dem_10m, streams,
+  field = "upstream_area_ha",
+  slope = slope_10m,
+  slope_threshold = 9,
+  max_width = 2000,
+  cost_threshold = 2500,
+  flood_factor = 6,
+  precip = precip_r
+)
+
+n_10m <- sum(values(valleys_10m) == 1, na.rm = TRUE)
+cat("10 m DEM valley cells:", n_10m, "/", ncell(valleys_10m),
+    "(", round(100 * n_10m / ncell(valleys_10m), 1), "%)\n")
+#> 10 m DEM valley cells: 54637 / 518400 ( 10.5 %)
+```
+
+## Fetch 1 m lidar DEM from STAC
+
+Query the `stac-dem-bc` collection for tiles intersecting our test area.
+We filter to 2019 tiles only (1 m lidar).
+
+
+``` r
+# Test area bounding box in WGS84
+# terra ext() gives xmin,xmax,ymin,ymax — STAC needs xmin,ymin,xmax,ymax
+dem_wgs <- project(dem_10m, "EPSG:4326")
+e <- ext(dem_wgs)
+bbox <- c(e$xmin, e$ymin, e$xmax, e$ymax)
+
+# Query STAC
+items <- stac("https://images.a11s.one/") |>
+  stac_search(
+    collections = "stac-dem-bc",
+    bbox = bbox,
+    datetime = "2019-01-01T00:00:00Z/2019-12-31T23:59:59Z"
+  ) |>
+  post_request() |>
+  items_fetch()
+
+cat("STAC items found:", length(items$features), "\n")
+#> STAC items found: 2
+for (f in items$features) cat(" ", f$id, "\n")
+#>   093-093l-2019-dem-bc_093l059_xli1m_utm09_2019 
+#>   093-093l-2019-dem-bc_093l049_xli1m_utm09_2019
+```
+
+## Mosaic and crop with gdalcubes
+
+Use `gdalcubes` to mosaic the STAC tiles and reproject to BC Albers
+(EPSG:3005), matching the test area extent. We use 5 m resolution as a
+practical compromise — finer than the bundled 10 m, but fast enough to build
+in a vignette. For production work, set `dx = 1, dy = 1` for full 1 m
+resolution.
+
+
+``` r
+# Build gdalcubes image collection from STAC items
+col <- stac_image_collection(items$features, asset_names = "image")
+
+# Define target cube — same extent as bundled DEM, 5 m resolution
+e <- ext(dem_10m)
+stac_res <- 5  # use 1 for full resolution (100x more cells, ~25 min fetch)
+v <- cube_view(
+  srs = "EPSG:3005",
+  extent = list(
+    left = e$xmin, right = e$xmax,
+    bottom = e$ymin, top = e$ymax,
+    t0 = "2019-01-01", t1 = "2019-12-31"
+  ),
+  dx = stac_res, dy = stac_res, dt = "P1Y",
+  aggregation = "first",
+  resampling = "bilinear"
+)
+
+# write_tif creates a directory with timestamped TIF(s) inside
+cube <- raster_cube(col, v)
+out_dir <- tempfile()
+write_tif(cube, out_dir)
+dem_stac_path <- list.files(out_dir, pattern = "\\.tif$", full.names = TRUE)[1]
+dem_stac <- rast(dem_stac_path)
+
+cat(stac_res, "m DEM:", ncol(dem_stac), "x", nrow(dem_stac), "pixels\n")
+#> 5 m DEM: 1600 x 1296 pixels
+cat("Resolution:", res(dem_stac), "m\n")
+#> Resolution: 5 5 m
+```
+
+## Derive slope
+
+
+``` r
+slope_stac <- terra::terrain(dem_stac, v = "slope", unit = "degrees")
+# Convert to percent slope to match flooded convention
+slope_stac <- tan(slope_stac * pi / 180) * 100
+```
+
+## Run VCA on STAC DEM
+
+
+``` r
+# Rasterize streams onto the STAC DEM grid
+precip_stac <- fl_stream_rasterize(streams, dem_stac, field = "map_upstream")
+
+valleys_stac <- fl_valley_confine(
+  dem_stac, streams,
+  field = "upstream_area_ha",
+  slope = slope_stac,
+  slope_threshold = 9,
+  max_width = 2000,
+  cost_threshold = 2500,
+  flood_factor = 6,
+  precip = precip_stac
+)
+
+n_stac <- sum(values(valleys_stac) == 1, na.rm = TRUE)
+cat(stac_res, "m DEM valley cells:", n_stac, "/", ncell(valleys_stac),
+    "(", round(100 * n_stac / ncell(valleys_stac), 1), "%)\n")
+#> 5 m DEM valley cells: 250564 / 2073600 ( 12.1 %)
+```
+
+## Compare
+
+
+``` r
+# Resample STAC result to 10 m grid for visual comparison
+valleys_stac_10 <- resample(valleys_stac, dem_10m, method = "near")
+
+# Area comparison
+area_10m <- n_10m * res(dem_10m)[1] * res(dem_10m)[2] / 1e6
+area_stac <- sum(values(valleys_stac_10) == 1, na.rm = TRUE) *
+  res(dem_10m)[1] * res(dem_10m)[2] / 1e6
+
+cat("Valley area (bundled 10 m DEM):", round(area_10m, 2), "km²\n")
+#> Valley area (bundled 10 m DEM): 5.46 km²
+cat("Valley area (STAC", stac_res, "m DEM):", round(area_stac, 2), "km²\n")
+#> Valley area (STAC 5 m DEM): 6.26 km²
+```
+
+
+``` r
+par(mfrow = c(2, 1), mar = c(2, 4, 2, 1))
+plot(valleys_10m, col = c("grey90", "darkgreen"),
+     main = "Bundled 10 m DEM (25 m TRIM resampled)", legend = FALSE)
+plot(st_geometry(streams), add = TRUE, col = "blue", lwd = 1)
+
+plot(valleys_stac_10, col = c("grey90", "darkgreen"),
+     main = paste0("STAC lidar ", stac_res, " m DEM"), legend = FALSE)
+plot(st_geometry(streams), add = TRUE, col = "blue", lwd = 1)
+```
+
+<div class="figure">
+<img src="figure/plot-compare-1.png" alt="Valley delineation from bundled 10 m DEM (top) vs STAC lidar DEM (bottom)." width="100%" />
+<p class="caption">Valley delineation from bundled 10 m DEM (top) vs STAC lidar DEM (bottom).</p>
+</div>
+
+## Site-level zoom: 1 m lidar
+
+At watershed scale, 5–10 m resolution is practical. But for site-level
+restoration prescriptions — identifying where to excavate historic fill,
+reconnect side channels, or plug drainage trenches — 1 m lidar is essential.
+Those features are invisible at 25 m.
+
+Here we crop to a ~3.5 × 4 km site around Robert Hatch Creek and Richfield
+Creek where they enter the Bulkley River floodplain, and run at full 1 m
+resolution.
+
+
+``` r
+# Site extent — Robert Hatch / Richfield confluence with Bulkley
+site_ext <- ext(976560, 980060, 1055808, 1059808)
+```
+
+
+``` r
+# Fetch 1 m lidar for the site extent
+site_wgs <- project(rast(site_ext, crs = "EPSG:3005"), "EPSG:4326")
+se <- ext(site_wgs)
+site_bbox <- c(se$xmin, se$ymin, se$xmax, se$ymax)
+
+site_items <- stac("https://images.a11s.one/") |>
+  stac_search(
+    collections = "stac-dem-bc",
+    bbox = site_bbox,
+    datetime = "2019-01-01T00:00:00Z/2019-12-31T23:59:59Z"
+  ) |>
+  post_request() |>
+  items_fetch()
+
+cat("STAC tiles for site:", length(site_items$features), "\n")
+#> STAC tiles for site: 2
+
+# Mosaic at 1 m
+site_col <- stac_image_collection(site_items$features, asset_names = "image")
+site_view <- cube_view(
+  srs = "EPSG:3005",
+  extent = list(
+    left = 976560, right = 980060,
+    bottom = 1055808, top = 1059808,
+    t0 = "2019-01-01", t1 = "2019-12-31"
+  ),
+  dx = 1, dy = 1, dt = "P1Y",
+  aggregation = "first",
+  resampling = "bilinear"
+)
+
+site_cube <- raster_cube(site_col, site_view)
+site_dir <- tempfile()
+write_tif(site_cube, site_dir)
+dem_1m <- rast(list.files(site_dir, "\\.tif$", full.names = TRUE)[1])
+
+cat("1 m DEM:", ncol(dem_1m), "x", nrow(dem_1m), "pixels (",
+    format(ncell(dem_1m), big.mark = ","), "cells)\n")
+#> 1 m DEM: 3500 x 4000 pixels ( 1.4e+07 cells)
+```
+
+
+``` r
+slope_1m <- terra::terrain(dem_1m, v = "slope", unit = "degrees")
+slope_1m <- tan(slope_1m * pi / 180) * 100
+
+# Crop streams to site
+streams_site <- st_crop(streams, st_as_sfc(st_bbox(c(
+  xmin = 976560, ymin = 1055808, xmax = 980060, ymax = 1059808
+), crs = st_crs(streams))))
+#> Warning: attribute variables are assumed to be spatially constant throughout
+#> all geometries
+
+precip_1m <- fl_stream_rasterize(streams_site, dem_1m, field = "map_upstream")
+
+valleys_1m <- fl_valley_confine(
+  dem_1m, streams_site,
+  field = "upstream_area_ha",
+  slope = slope_1m,
+  slope_threshold = 9,
+  max_width = 2000,
+  cost_threshold = 2500,
+  flood_factor = 6,
+  precip = precip_1m
+)
+#> Warning: [costDist] distance algorithm did not converge
+
+n_1m <- sum(values(valleys_1m) == 1, na.rm = TRUE)
+cat("1 m DEM valley cells:", format(n_1m, big.mark = ","), "/",
+    format(ncell(valleys_1m), big.mark = ","),
+    "(", round(100 * n_1m / ncell(valleys_1m), 1), "%)\n")
+#> 1 m DEM valley cells: 3,883,179 / 1.4e+07 ( 27.7 %)
+```
+
+
+``` r
+# Run 10 m (resampled TRIM) on the same site for comparison
+dem_site_10m <- terra::crop(dem_10m, site_ext)
+slope_site_10m <- terra::crop(slope_10m, site_ext)
+precip_site_10m <- fl_stream_rasterize(streams_site, dem_site_10m, field = "map_upstream")
+
+valleys_site_10m <- fl_valley_confine(
+  dem_site_10m, streams_site,
+  field = "upstream_area_ha",
+  slope = slope_site_10m,
+  slope_threshold = 9,
+  max_width = 2000,
+  cost_threshold = 2500,
+  flood_factor = 6,
+  precip = precip_site_10m
+)
+
+par(mfrow = c(2, 1), mar = c(2, 4, 2, 1))
+plot(valleys_site_10m, col = c("grey90", "darkgreen"),
+     main = "Site: 10 m (25 m TRIM resampled)", legend = FALSE)
+plot(st_geometry(streams_site), add = TRUE, col = "blue", lwd = 1)
+
+# Resample 1 m result to same grid for visual comparison
+valleys_1m_plot <- resample(valleys_1m, dem_site_10m, method = "near")
+plot(valleys_1m_plot, col = c("grey90", "darkgreen"),
+     main = "Site: 1 m native lidar", legend = FALSE)
+plot(st_geometry(streams_site), add = TRUE, col = "blue", lwd = 1)
+```
+
+<div class="figure">
+<img src="figure/site-compare-1.png" alt="Site-level comparison: resampled 10 m (top) vs native 1 m lidar (bottom). Fine-scale features like side channels and terrace edges emerge at 1 m." width="100%" />
+<p class="caption">Site-level comparison: resampled 10 m (top) vs native 1 m lidar (bottom). Fine-scale features like side channels and terrace edges emerge at 1 m.</p>
+</div>
+
+## Quantifying the difference
+
+
+``` r
+# Resample 1 m result to the 25 m (resampled to 10 m) site grid
+valleys_1m_on_10m <- resample(valleys_1m, dem_site_10m, method = "near")
+
+# Site floodplain area from each DEM
+cell_area_m2 <- res(dem_site_10m)[1] * res(dem_site_10m)[2]  # 100 m²
+fp_25m <- sum(values(valleys_site_10m) == 1, na.rm = TRUE)
+fp_1m  <- sum(values(valleys_1m_on_10m) == 1, na.rm = TRUE)
+
+# "Pop-ups": cells that are floodplain at 25 m but NOT at 1 m
+popups <- sum(values(valleys_site_10m) == 1 & values(valleys_1m_on_10m) != 1,
+              na.rm = TRUE)
+
+data.frame(
+  Metric = c(
+    "Floodplain area (25 m TRIM)",
+    "Floodplain area (1 m lidar)",
+    "Elevated features (pop-ups)",
+    "Pop-ups as % of 25 m floodplain"
+  ),
+  Value = c(
+    paste(round(fp_25m * cell_area_m2 / 1e4, 1), "ha"),
+    paste(round(fp_1m * cell_area_m2 / 1e4, 1), "ha"),
+    paste(round(popups * cell_area_m2 / 1e4, 1), "ha"),
+    paste0(round(100 * popups / fp_25m, 1), "%")
+  )
+) |> knitr::kable()
+```
+
+
+
+|Metric                          |Value    |
+|:-------------------------------|:--------|
+|Floodplain area (25 m TRIM)     |373 ha   |
+|Floodplain area (1 m lidar)     |388.3 ha |
+|Elevated features (pop-ups)     |36.1 ha  |
+|Pop-ups as % of 25 m floodplain |9.7%     |
+
+
+
+The elevated features — "pop-ups" — are areas the 25 m TRIM DEM classifies as
+floodplain but the 1 m lidar reveals are sitting above the flood surface. These
+are the barriers: roads, dykes, fill, and other raised features that block
+lateral connectivity.
+
+## Anthropogenic barriers to floodplain connectivity
+
+The difference between the two maps above is striking — and informative. The
+25 m TRIM DEM (resampled to a 10 m grid but still only 25 m terrain detail)
+shows the floodplain as one continuous green mass. The 1 m lidar reveals a
+different story: white gaps cut through the green where the ground surface sits
+**above** the modelled flood level.
+
+These white features are areas the VCA identifies as "not floodplain" — pixels
+too high or too steep to be reached by the flood surface. At 25 m resolution
+those features are invisible because a single pixel averages the road
+embankment with the surrounding low ground, smoothing it away. At 1 m, the
+actual elevation of a raised road bed, railway grade, or dyke is resolved, so
+it stands out.
+
+**Linear white features** cutting through the floodplain are likely:
+
+- **Roads** — raised road beds, even a metre or two of fill is enough
+- **Railway grades** — often built on significant embankments
+- **Dykes and levees** — flood protection berms along the river
+- **Riprap and erosion protection** — armoured banks
+
+**Irregular white patches** may be:
+
+- **Agricultural fill** — floodplain built up over decades of farming
+- **Building pads** — cleared and filled for structures
+- **Natural terraces** — legitimately higher ground not connected to the
+  flood surface
+
+The implication for restoration is direct: **the gap between the 25 m and 1 m
+results is largely the anthropogenic footprint on the floodplain.** The 25 m
+DEM says "this is all floodplain" because it cannot see the barriers. The 1 m
+DEM says "this would be floodplain, except these raised features are blocking
+it." Those white features — roads, dykes, fill — are potential intervention
+targets. Removing or breaching them could reconnect floodplain function:
+filling drainage trenches, excavating historic fill back to floodplain grade,
+or installing culverts and bridges to restore lateral connectivity.
+
+This is the power of running `flooded` at 1 m: it turns a binary
+floodplain/not-floodplain map into a diagnostic tool for identifying **what is
+preventing floodplain from functioning** and **where to act**.
+
+## Summary
+
+### A practical workflow
+
+Use coarse resolution (5–10 m) at watershed scale to identify candidate
+floodplain sites, then zoom into specific sites at 1 m for restoration
+prescriptions. The 1 m lidar reveals features that matter for on-the-ground
+work: historic fill from agriculture, drainage trenches, disconnected side
+channels, and terrace edges where excavation could reconnect floodplain.
+
+### DEM sources
+
+The `flooded` pipeline is DEM-agnostic. Any source works:
+
+| Source | Native resolution | Notes |
+|--------|------------------|-------|
+| BC Data Catalogue (WCS) | 25 m | Provincial TRIM DEM; `bcdata get-dem` (Python CLI) |
+| Bundled test data | 25 m → 10 m | TRIM resampled via bilinear; `system.file("testdata/", package = "flooded")` |
+| stac-dem-bc (this vignette) | 1 m | Provincial lidar; `rstac` + `gdalcubes` |
+| CDEM / SRTM | 30 m | Federal/global fallback for areas without lidar |
diff --git a/vignettes/stac-dem.Rmd.orig b/vignettes/stac-dem.Rmd.orig
new file mode 100644
index 0000000..679165b
--- /dev/null
+++ b/vignettes/stac-dem.Rmd.orig
@@ -0,0 +1,416 @@
+---
+title: "Bring your own DEM via STAC"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Bring your own DEM via STAC}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r setup, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>",
+  fig.width = 7,
+  fig.height = 6,
+  dpi = 96,
+  out.width = "100%"
+)
+```
+
+`flooded` works with any DEM — it doesn't require a specific source. This
+vignette demonstrates fetching 1 m lidar tiles from a STAC catalog and
+comparing the resulting floodplain with the bundled 10 m DEM.
+
+We use the same Neexdzii Kwah test area (Bulkley River near Topley, BC) as
+the main vignette, but source the DEM from
+[stac-dem-bc](https://images.a11s.one/) — a STAC collection of BC provincial
+lidar DEMs.
+
+## Setup
+
+```{r load}
+library(flooded)
+library(terra)
+library(sf)
+library(rstac)
+library(gdalcubes)
+
+terra::terraOptions(threads = 12)
+```
+
+## What does "resampled to 10 m" mean?
+
+The bundled test DEM is the 25 m BC TRIM DEM resampled to a 10 m grid using
+bilinear interpolation. That means each original 25 m pixel gets split into
+smaller 10 m pixels, with values smoothly blended from neighbours. The grid is
+genuinely 10 m — each cell is 10 m × 10 m — but the terrain detail is still
+25 m quality. It's like zooming into a low-resolution photo: the image gets
+bigger but not sharper. No real topographic detail is added.
+
+In contrast, the 1 m lidar tiles from the STAC catalog are *natively* 1 m.
+They capture real features at that scale — side channels, terrace edges, drainage
+ditches — that a 25 m DEM physically cannot see, no matter how finely you
+resample it.
+
+## Bundled 10 m baseline
+
+First, load the bundled test data and run the VCA to establish a baseline.
+
+```{r baseline}
+dem_10m <- rast(system.file("testdata/dem.tif", package = "flooded"))
+slope_10m <- rast(system.file("testdata/slope.tif", package = "flooded"))
+streams <- st_read(
+  system.file("testdata/streams.gpkg", package = "flooded"),
+  quiet = TRUE
+)
+
+precip_r <- fl_stream_rasterize(streams, dem_10m, field = "map_upstream")
+
+valleys_10m <- fl_valley_confine(
+  dem_10m, streams,
+  field = "upstream_area_ha",
+  slope = slope_10m,
+  slope_threshold = 9,
+  max_width = 2000,
+  cost_threshold = 2500,
+  flood_factor = 6,
+  precip = precip_r
+)
+
+n_10m <- sum(values(valleys_10m) == 1, na.rm = TRUE)
+cat("10 m DEM valley cells:", n_10m, "/", ncell(valleys_10m),
+    "(", round(100 * n_10m / ncell(valleys_10m), 1), "%)\n")
+```
+
+## Fetch 1 m lidar DEM from STAC
+
+Query the `stac-dem-bc` collection for tiles intersecting our test area.
+We filter to 2019 tiles only (1 m lidar).
+
+```{r stac-query}
+# Test area bounding box in WGS84
+# terra ext() gives xmin,xmax,ymin,ymax — STAC needs xmin,ymin,xmax,ymax
+dem_wgs <- project(dem_10m, "EPSG:4326")
+e <- ext(dem_wgs)
+bbox <- c(e$xmin, e$ymin, e$xmax, e$ymax)
+
+# Query STAC
+items <- stac("https://images.a11s.one/") |>
+  stac_search(
+    collections = "stac-dem-bc",
+    bbox = bbox,
+    datetime = "2019-01-01T00:00:00Z/2019-12-31T23:59:59Z"
+  ) |>
+  post_request() |>
+  items_fetch()
+
+cat("STAC items found:", length(items$features), "\n")
+for (f in items$features) cat(" ", f$id, "\n")
+```
+
+## Mosaic and crop with gdalcubes
+
+Use `gdalcubes` to mosaic the STAC tiles and reproject to BC Albers
+(EPSG:3005), matching the test area extent. We use 5 m resolution as a
+practical compromise — finer than the bundled 10 m, but fast enough to build
+in a vignette. For production work, set `dx = 1, dy = 1` for full 1 m
+resolution.
+
+```{r mosaic}
+# Build gdalcubes image collection from STAC items
+col <- stac_image_collection(items$features, asset_names = "image")
+
+# Define target cube — same extent as bundled DEM, 5 m resolution
+e <- ext(dem_10m)
+stac_res <- 5  # use 1 for full resolution (100x more cells, ~25 min fetch)
+v <- cube_view(
+  srs = "EPSG:3005",
+  extent = list(
+    left = e$xmin, right = e$xmax,
+    bottom = e$ymin, top = e$ymax,
+    t0 = "2019-01-01", t1 = "2019-12-31"
+  ),
+  dx = stac_res, dy = stac_res, dt = "P1Y",
+  aggregation = "first",
+  resampling = "bilinear"
+)
+
+# write_tif creates a directory with timestamped TIF(s) inside
+cube <- raster_cube(col, v)
+out_dir <- tempfile()
+write_tif(cube, out_dir)
+dem_stac_path <- list.files(out_dir, pattern = "\\.tif$", full.names = TRUE)[1]
+dem_stac <- rast(dem_stac_path)
+
+cat(stac_res, "m DEM:", ncol(dem_stac), "x", nrow(dem_stac), "pixels\n")
+cat("Resolution:", res(dem_stac), "m\n")
+```
+
+## Derive slope
+
+```{r slope}
+slope_stac <- terra::terrain(dem_stac, v = "slope", unit = "degrees")
+# Convert to percent slope to match flooded convention
+slope_stac <- tan(slope_stac * pi / 180) * 100
+```
+
+## Run VCA on STAC DEM
+
+```{r vca-stac}
+# Rasterize streams onto the STAC DEM grid
+precip_stac <- fl_stream_rasterize(streams, dem_stac, field = "map_upstream")
+
+valleys_stac <- fl_valley_confine(
+  dem_stac, streams,
+  field = "upstream_area_ha",
+  slope = slope_stac,
+  slope_threshold = 9,
+  max_width = 2000,
+  cost_threshold = 2500,
+  flood_factor = 6,
+  precip = precip_stac
+)
+
+n_stac <- sum(values(valleys_stac) == 1, na.rm = TRUE)
+cat(stac_res, "m DEM valley cells:", n_stac, "/", ncell(valleys_stac),
+    "(", round(100 * n_stac / ncell(valleys_stac), 1), "%)\n")
+```
+
+## Compare
+
+```{r compare}
+# Resample STAC result to 10 m grid for visual comparison
+valleys_stac_10 <- resample(valleys_stac, dem_10m, method = "near")
+
+# Area comparison
+area_10m <- n_10m * res(dem_10m)[1] * res(dem_10m)[2] / 1e6
+area_stac <- sum(values(valleys_stac_10) == 1, na.rm = TRUE) *
+  res(dem_10m)[1] * res(dem_10m)[2] / 1e6
+
+cat("Valley area (bundled 10 m DEM):", round(area_10m, 2), "km²\n")
+cat("Valley area (STAC", stac_res, "m DEM):", round(area_stac, 2), "km²\n")
+```
+
+```{r plot-compare, fig.width = 7, fig.height = 8, fig.cap = "Valley delineation from bundled 10 m DEM (top) vs STAC lidar DEM (bottom)."}
+par(mfrow = c(2, 1), mar = c(2, 4, 2, 1))
+plot(valleys_10m, col = c("grey90", "darkgreen"),
+     main = "Bundled 10 m DEM (25 m TRIM resampled)", legend = FALSE)
+plot(st_geometry(streams), add = TRUE, col = "blue", lwd = 1)
+
+plot(valleys_stac_10, col = c("grey90", "darkgreen"),
+     main = paste0("STAC lidar ", stac_res, " m DEM"), legend = FALSE)
+plot(st_geometry(streams), add = TRUE, col = "blue", lwd = 1)
+```
+
+## Site-level zoom: 1 m lidar
+
+At watershed scale, 5–10 m resolution is practical. But for site-level
+restoration prescriptions — identifying where to excavate historic fill,
+reconnect side channels, or plug drainage trenches — 1 m lidar is essential.
+Those features are invisible at 25 m.
+
+Here we crop to a ~3.5 × 4 km site around Robert Hatch Creek and Richfield
+Creek where they enter the Bulkley River floodplain, and run at full 1 m
+resolution.
+
+```{r site-crop}
+# Site extent — Robert Hatch / Richfield confluence with Bulkley
+site_ext <- ext(976560, 980060, 1055808, 1059808)
+```
+
+```{r site-stac}
+# Fetch 1 m lidar for the site extent
+site_wgs <- project(rast(site_ext, crs = "EPSG:3005"), "EPSG:4326")
+se <- ext(site_wgs)
+site_bbox <- c(se$xmin, se$ymin, se$xmax, se$ymax)
+
+site_items <- stac("https://images.a11s.one/") |>
+  stac_search(
+    collections = "stac-dem-bc",
+    bbox = site_bbox,
+    datetime = "2019-01-01T00:00:00Z/2019-12-31T23:59:59Z"
+  ) |>
+  post_request() |>
+  items_fetch()
+
+cat("STAC tiles for site:", length(site_items$features), "\n")
+
+# Mosaic at 1 m
+site_col <- stac_image_collection(site_items$features, asset_names = "image")
+site_view <- cube_view(
+  srs = "EPSG:3005",
+  extent = list(
+    left = 976560, right = 980060,
+    bottom = 1055808, top = 1059808,
+    t0 = "2019-01-01", t1 = "2019-12-31"
+  ),
+  dx = 1, dy = 1, dt = "P1Y",
+  aggregation = "first",
+  resampling = "bilinear"
+)
+
+site_cube <- raster_cube(site_col, site_view)
+site_dir <- tempfile()
+write_tif(site_cube, site_dir)
+dem_1m <- rast(list.files(site_dir, "\\.tif$", full.names = TRUE)[1])
+
+cat("1 m DEM:", ncol(dem_1m), "x", nrow(dem_1m), "pixels (",
+    format(ncell(dem_1m), big.mark = ","), "cells)\n")
+```
+
+```{r site-vca}
+slope_1m <- terra::terrain(dem_1m, v = "slope", unit = "degrees")
+slope_1m <- tan(slope_1m * pi / 180) * 100
+
+# Crop streams to site
+streams_site <- st_crop(streams, st_as_sfc(st_bbox(c(
+  xmin = 976560, ymin = 1055808, xmax = 980060, ymax = 1059808
+), crs = st_crs(streams))))
+
+precip_1m <- fl_stream_rasterize(streams_site, dem_1m, field = "map_upstream")
+
+valleys_1m <- fl_valley_confine(
+  dem_1m, streams_site,
+  field = "upstream_area_ha",
+  slope = slope_1m,
+  slope_threshold = 9,
+  max_width = 2000,
+  cost_threshold = 2500,
+  flood_factor = 6,
+  precip = precip_1m
+)
+
+n_1m <- sum(values(valleys_1m) == 1, na.rm = TRUE)
+cat("1 m DEM valley cells:", format(n_1m, big.mark = ","), "/",
+    format(ncell(valleys_1m), big.mark = ","),
+    "(", round(100 * n_1m / ncell(valleys_1m), 1), "%)\n")
+```
+
+```{r site-compare, fig.width = 7, fig.height = 8, fig.cap = "Site-level comparison: resampled 10 m (top) vs native 1 m lidar (bottom). Fine-scale features like side channels and terrace edges emerge at 1 m."}
+# Run 10 m (resampled TRIM) on the same site for comparison
+dem_site_10m <- terra::crop(dem_10m, site_ext)
+slope_site_10m <- terra::crop(slope_10m, site_ext)
+precip_site_10m <- fl_stream_rasterize(streams_site, dem_site_10m, field = "map_upstream")
+
+valleys_site_10m <- fl_valley_confine(
+  dem_site_10m, streams_site,
+  field = "upstream_area_ha",
+  slope = slope_site_10m,
+  slope_threshold = 9,
+  max_width = 2000,
+  cost_threshold = 2500,
+  flood_factor = 6,
+  precip = precip_site_10m
+)
+
+par(mfrow = c(2, 1), mar = c(2, 4, 2, 1))
+plot(valleys_site_10m, col = c("grey90", "darkgreen"),
+     main = "Site: 10 m (25 m TRIM resampled)", legend = FALSE)
+plot(st_geometry(streams_site), add = TRUE, col = "blue", lwd = 1)
+
+# Resample 1 m result to same grid for visual comparison
+valleys_1m_plot <- resample(valleys_1m, dem_site_10m, method = "near")
+plot(valleys_1m_plot, col = c("grey90", "darkgreen"),
+     main = "Site: 1 m native lidar", legend = FALSE)
+plot(st_geometry(streams_site), add = TRUE, col = "blue", lwd = 1)
+```
+
+## Quantifying the difference
+
+```{r popups}
+# Resample 1 m result to the 25 m (resampled to 10 m) site grid
+valleys_1m_on_10m <- resample(valleys_1m, dem_site_10m, method = "near")
+
+# Site floodplain area from each DEM
+cell_area_m2 <- res(dem_site_10m)[1] * res(dem_site_10m)[2]  # 100 m²
+fp_25m <- sum(values(valleys_site_10m) == 1, na.rm = TRUE)
+fp_1m  <- sum(values(valleys_1m_on_10m) == 1, na.rm = TRUE)
+
+# "Pop-ups": cells that are floodplain at 25 m but NOT at 1 m
+popups <- sum(values(valleys_site_10m) == 1 & values(valleys_1m_on_10m) != 1,
+              na.rm = TRUE)
+
+data.frame(
+  Metric = c(
+    "Floodplain area (25 m TRIM)",
+    "Floodplain area (1 m lidar)",
+    "Elevated features (pop-ups)",
+    "Pop-ups as % of 25 m floodplain"
+  ),
+  Value = c(
+    paste(round(fp_25m * cell_area_m2 / 1e4, 1), "ha"),
+    paste(round(fp_1m * cell_area_m2 / 1e4, 1), "ha"),
+    paste(round(popups * cell_area_m2 / 1e4, 1), "ha"),
+    paste0(round(100 * popups / fp_25m, 1), "%")
+  )
+) |> knitr::kable()
+```
+
+The elevated features — "pop-ups" — are areas the 25 m TRIM DEM classifies as
+floodplain but the 1 m lidar reveals are sitting above the flood surface. These
+are the barriers: roads, dykes, fill, and other raised features that block
+lateral connectivity.
+
+## Anthropogenic barriers to floodplain connectivity
+
+The difference between the two maps above is striking — and informative. The
+25 m TRIM DEM (resampled to a 10 m grid but still only 25 m terrain detail)
+shows the floodplain as one continuous green mass. The 1 m lidar reveals a
+different story: white gaps cut through the green where the ground surface sits
+**above** the modelled flood level.
+
+These white features are areas the VCA identifies as "not floodplain" — pixels
+too high or too steep to be reached by the flood surface. At 25 m resolution
+those features are invisible because a single pixel averages the road
+embankment with the surrounding low ground, smoothing it away. At 1 m, the
+actual elevation of a raised road bed, railway grade, or dyke is resolved, so
+it stands out.
+
+**Linear white features** cutting through the floodplain are likely:
+
+- **Roads** — raised road beds, even a metre or two of fill is enough
+- **Railway grades** — often built on significant embankments
+- **Dykes and levees** — flood protection berms along the river
+- **Riprap and erosion protection** — armoured banks
+
+**Irregular white patches** may be:
+
+- **Agricultural fill** — floodplain built up over decades of farming
+- **Building pads** — cleared and filled for structures
+- **Natural terraces** — legitimately higher ground not connected to the
+  flood surface
+
+The implication for restoration is direct: **the gap between the 25 m and 1 m
+results is largely the anthropogenic footprint on the floodplain.** The 25 m
+DEM says "this is all floodplain" because it cannot see the barriers. The 1 m
+DEM says "this would be floodplain, except these raised features are blocking
+it." Those white features — roads, dykes, fill — are potential intervention
+targets. Removing or breaching them could reconnect floodplain function:
+filling drainage trenches, excavating historic fill back to floodplain grade,
+or installing culverts and bridges to restore lateral connectivity.
+
+This is the power of running `flooded` at 1 m: it turns a binary
+floodplain/not-floodplain map into a diagnostic tool for identifying **what is
+preventing floodplain from functioning** and **where to act**.
+
+## Summary
+
+### A practical workflow
+
+Use coarse resolution (5–10 m) at watershed scale to identify candidate
+floodplain sites, then zoom into specific sites at 1 m for restoration
+prescriptions. The 1 m lidar reveals features that matter for on-the-ground
+work: historic fill from agriculture, drainage trenches, disconnected side
+channels, and terrace edges where excavation could reconnect floodplain.
+
+### DEM sources
+
+The `flooded` pipeline is DEM-agnostic. Any source works:
+
+| Source | Native resolution | Notes |
+|--------|------------------|-------|
+| BC Data Catalogue (WCS) | 25 m | Provincial TRIM DEM; `bcdata get-dem` (Python CLI) |
+| Bundled test data | 25 m → 10 m | TRIM resampled via bilinear; `system.file("testdata/", package = "flooded")` |
+| stac-dem-bc (this vignette) | 1 m | Provincial lidar; `rstac` + `gdalcubes` |
+| CDEM / SRTM | 30 m | Federal/global fallback for areas without lidar |