Update CLAUDE.md with selective soul conventions

Filter by applies_when frontmatter. Only include conventions relevant
to this repo. Frontmatter stripped from output.

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

Author: NewGraphEnvironment

CLAUDE.md

@@ -30,296 +30,6 @@ geometry column may be named `geom` not `geometry`
 
 <\!-- BEGIN SOUL CONVENTIONS — DO NOT EDIT BELOW THIS LINE -->
 
-# 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
 
@@ -409,6 +119,7 @@ drift::dft_map_interactive(classified, aoi = aoi)
 - 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`.
@@ -497,6 +208,7 @@ Add new checks here when a bug class is discovered — they compound over time.
 - New variables: update .tfvars.example
 - New workflows: update relevant README
 
+
 # Communications Conventions
 
 Standards for external communications across New Graph Environment.
@@ -558,6 +270,7 @@ 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 -->
@@ -625,10 +338,10 @@ For multi-step tasks, state a brief plan:
 
 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.
@@ -773,6 +486,7 @@ Scripts and logs live together: `scripts/<module>/logs/`
 | Restoration planning | **Aquatic Restoration Planning (#5)** |
 | QGIS, Mergin, field forms | **Collaborative GIS (#3)** |
 
+
 # Planning Conventions
 
 How Claude manages structured planning for complex tasks using planning-with-files (PWF).
@@ -869,6 +583,7 @@ If `planning/` doesn't exist in the repo, run `/planning-init` first.
 | `/planning-update` | Mid-session — sync checkboxes and progress |
 | `/planning-archive` | Issue complete — archive and create fresh active/ |
 
+
 # R Package Development Conventions
 
 Standards for R package development across New Graph Environment repositories.
@@ -1102,6 +817,7 @@ When an LLM assistant modifies R package code:
    Rscript -e 'devtools::check()' 2>&1 | grep -E "(ERROR|WARNING|NOTE|errors|warnings|notes)" | tail -10
    ```
 
+
 # Reference Management Conventions
 
 How references flow between Claude Code, Zotero, and technical writing at New Graph Environment.
@@ -1227,6 +943,7 @@ Always verify downloads: `file paper.pdf` should say "PDF document", not HTML.
 - NEVER cite specific numbers without verifying from the source PDF via ragnar search
 - NEVER paraphrase equations — copy exact notation and cite page/section
 
+
 # SRED Conventions
 
 How SR&ED tracking integrates with New Graph Environment's development workflows.