Development

.github/workflows/docs.yaml

@@ -0,0 +1,75 @@
+# Build the Quarto docs site in docs/ and publish it to GitHub
+# Pages. Same pattern as sciSpatialR's pkgdown workflow.
+#
+# The site is rebuilt from docs/ on every run and handed to Pages
+# as a build artifact, so no rendered HTML is ever committed and
+# there is no gh-pages branch to keep in sync. Pull requests build
+# but do not publish, which surfaces a broken page during review
+# rather than after merge.
+#
+# The pages are plain Markdown, so Quarto renders them without R.
+# Which pages are built is set by `project: render` in
+# docs/_quarto.yml.
+#
+# Repository prerequisite: Settings > Pages > Source = "GitHub
+# Actions". Without that, the deploy job fails with a 404.
+
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs.yaml"
+  pull_request:
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs.yaml"
+  workflow_dispatch:
+
+# Deny by default; each job requests only the scopes it needs.
+permissions: {}
+
+# Serialize publishing. Queued runs collapse to the newest, but an
+# in-flight deployment is allowed to finish so the live site is
+# never left half-written.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: quarto-dev/quarto-actions/setup@v2
+
+      # Renders to docs/_site, as set in docs/_quarto.yml
+      - name: Build site
+        run: quarto render docs
+
+      # No configure-pages step: Quarto reads its base URL from
+      # `site-url` in docs/_quarto.yml, so this job stays on
+      # contents:read alone.
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs/_site
+
+  deploy:
+    # Publishing is a main-branch-only consequence of a green build.
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

.gitignore

@@ -55,5 +55,19 @@ vignettes/*.pdf
 !3_output/**/
 !3_output/**/.gitkeep
 
+# ...but keep the small, diffable summaries of each experiment:
+# the run record, the report and the summary tables. They are
+# what lets experiments be compared from the repository alone.
+# Per-species detail (coefficient_summary.csv,
+# parity_terms.csv) is large and is rebuilt from the
+# 2_pipeline/ stores, so it stays ignored.
+!3_output/**/run_record.md
+!3_output/**/report.md
+!3_output/**/tables/parity_summary.csv
+!3_output/**/tables/coverage.csv
+!3_output/**/tables/metric_summary.csv
+!3_output/**/tables/grid_summary.csv
+!3_output/**/tables/v2_self_agreement_summary.csv
+
 AGENTS.md
 CLAUDE.md

0_data/v2_scripts/README.md

@@ -0,0 +1,53 @@
+# v2_scripts
+
+![Status](https://img.shields.io/badge/Status-Reference%20only-lightgrey)
+![Languages](https://img.shields.io/badge/Languages-R-blue)
+
+Cloned snapshots of the v2 modelling code, taken on **2026-09-08**, one
+subfolder per taxon.
+
+These are the code as received, kept unmodified. They are the reference the
+rewritten modules in `1_code/modules/` are checked against, and they are
+**not run** — nothing in the harness, modules, or experiments sources them.
+Subfolder names match those under `1_code/modules/`, so each module has an
+obvious reference.
+
+## Sources
+
+| Folder | Source | Taken from | Commit |
+| --- | --- | --- | --- |
+| `birds/` | <https://github.com/ABbiodiversity/BirdModels> | whole repository | `1a3e086` (2026-04-22) |
+| `mammals/` | <https://github.com/ABbiodiversity/MammalModels> | `1_code/2_habitat-modeling/2024/` | `2874dec` (2026-09-01) |
+| `plants/` | `\\ABMI-DATA2\science\sc\ToEmily\VegetationModels\1_code\r-scripts` | `1_code/r-scripts/` | `24e97e3` (2025-04-02) |
+
+Each snapshot was verified against its source on 2026-09-08:
+
+- `birds/` — 21 files, cloned that day from `main`.
+- `mammals/` — 21 files, every blob hash matches the commit above.
+- `plants/` — 19 files, byte-identical to the network path.
+
+The `plants/` source is a working copy on ABMI-DATA2 of
+<https://github.com/beallen/VegetationModels>, on `main`. The commit was read
+from its `.git` refs; whether that working copy had uncommitted changes was
+not checked, so treat the commit as indicative rather than exact.
+
+Soil mites sit in `plants/` because that is how the vegetation repository
+groups them — "plant group" names a file layout, not a taxonomy, and covers
+vascular plants, bryophytes, lichens and soil mites alike.
+
+## No nested repositories
+
+The `.git/` directories were not kept. An embedded repository is recorded by
+the parent as a gitlink rather than as files, which would leave these scripts
+untracked here. Re-clone at the commit above to recover history.
+
+`birds/.gitignore` came with the clone and was kept as received. It applies
+to that subtree and would exclude `data/`, `figs/` and `out/` if any were
+added there.
+
+## Refreshing a snapshot
+
+Replace the folder's contents, update the commit and date in the table above,
+and re-check the rewritten module against it. A change here is a change to
+the reference the parity gate is measured against, so it should not be made
+silently — see [Parity gate](../../README.md#parity-gate).

1_code/_scratch.R

@@ -0,0 +1,28 @@
+# ---
+# title: Scratch Work
+# author: Brendan Casey
+# created: 2026-09-06
+# inputs:
+#   - ad hoc, temporary inputs as needed
+# outputs:
+#   - none by default
+# notes:
+#   Temporary workspace for testing, exploration, and one-off
+#   tasks. Keep work grouped under dated headings and move any
+#   durable code into the appropriate script or module.
+#
+#   Headings run three deep, so the Outline menu reads as a
+#   day > task > step outline:
+#     # YYYY-MM-DD ----  one per day of scratch work
+#     ## Task ----       one per piece of work that day, named
+#                        for what it does, not for the date
+#     ### Step ----      stages within a task; the first is
+#                        Setup, loading packages and data
+#
+#   Add new code under the current date heading, creating that
+#   heading if the day does not have one yet. A day with only
+#   one task still gets both a date and a task heading, so the
+#   outline stays the same shape throughout.
+# ---
+
+# End of script ----