jonashertner · jonashertner · Aug 22, 2026 · Aug 22, 2026 · Aug 22, 2026
@@ -0,0 +1,8 @@
+# Release, scientific provenance and legal-method changes need an accountable
+# maintainer review. Add domain reviewers here as the contributor group grows.
+* @jonashertner
+
+/build/ @jonashertner
+/scripts/ @jonashertner
+/site/data/ @jonashertner
+/.github/ @jonashertner
@@ -0,0 +1,20 @@
+## What changed
+
+<!-- State the smallest defensible claim. -->
+
+## Evidence
+
+<!-- Link primary sources. Give the holder, publication/data date and access date. -->
+
+## Validation
+
+- [ ] `node scripts/verify-site.mjs` passes
+- [ ] Data-derived claims and provenance were rebuilt
+- [ ] All five languages remain complete, or translation help is requested
+- [ ] Keyboard, touch and narrow-screen behavior were checked when UI changed
+- [ ] Scientific and legal limitations appear next to the affected claim
+- [ ] No third-party material is presented under a broader licence than its own
+
+## Review requested
+
+<!-- Name the scientific, legal, accessibility, translation or engineering expertise needed. -->
@@ -1,87 +1,94 @@
-name: Publish site
+name: Verify and publish
+
 on:
+  pull_request:
   push:
     branches: [main]
   schedule:
-    # Monday 05:40 UTC. BFE posts the reservoir filling level for the previous
-    # week early in the week, and the vintage audit re-reads every federal
-    # layer's Datenstand at the same time, so the page never claims a currency
-    # it no longer has.
+    # Monday 05:40 UTC, after the usual weekly reservoir publication.
     - cron: '40 5 * * 1'
   workflow_dispatch:
+    inputs:
+      refresh_data:
+        description: Build a review artifact from current upstream data
+        type: boolean
+        default: false
+
 permissions:
-  contents: write
-  pages: write
-  id-token: write
+  contents: read
+
 concurrency:
-  group: pages
+  group: riverflow-${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
+
 jobs:
   validate:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: '22'
+          cache: npm
+      - run: npm ci
       - name: Verify the complete publication surface
-        run: node scripts/verify-site.mjs
+        run: npm test
 
-  # The weekly filling series is baked at build time because the BFE file allows
-  # only map.geo.admin.ch to read it from a browser. Baked data goes stale in a
-  # way live data cannot, so it is rebuilt on a schedule and the result is
-  # committed: the repo, not just the deployment, stays the record.
-  refresh:
-    if: github.event_name != 'push'
+  refresh-review:
+    if: github.event_name == 'schedule' || (github.event_name == 'workflow_dispatch' && inputs.refresh_data)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: '22'
-      - name: Refresh federal stations, reservoirs, quality, cantonal dates, wetlands and source states
-        id: build
-        run: |
-          node build/01-stations.mjs
-          node build/06-reservoirs.mjs
-          node build/11-cantons.mjs
-          node build/12-wetlands.mjs
-          node build/17-quality.mjs
-          node build/18-monitoring.mjs
-          node build/08-vintage.mjs
-          node build/16-provenance.mjs
-          node scripts/verify-site.mjs
-      - name: Commit if anything moved
-        if: success()
+          cache: npm
+      - run: npm ci
+      - name: Refresh reviewable federal and cantonal artifacts
+        run: npm run refresh
+      - name: Check primary external links
+        run: npm run check:links
+      - name: Record the candidate patch
+        id: diff
+        shell: bash
         run: |
-          if git diff --quiet -- site/data; then
-            echo "no change this week"
-            exit 0
+          if git diff --quiet -- site build/pages; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            echo "No upstream publication change detected." >> "$GITHUB_STEP_SUMMARY"
+          else
+            git diff --binary -- site build/pages > riverflow-refresh.patch
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            echo "A reviewed data refresh is available as a workflow artifact. Apply it on a branch and open a pull request; this workflow never writes to main." >> "$GITHUB_STEP_SUMMARY"
           fi
-          git config user.name  "github-actions[bot]"
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git add site/data
-          git commit -m "Weekly refresh: stations, reservoirs, quality and source states"
-          git push
-      - name: Say so if the refresh failed
-        if: failure()
-        run: |
-          echo "::error::The weekly data refresh or evidence validation failed. Nothing will deploy."
+      - name: Upload the review patch
+        if: steps.diff.outputs.changed == 'true'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: riverflow-refresh-${{ github.run_id }}
+          path: riverflow-refresh.patch
+          if-no-files-found: error
+          retention-days: 30
+
   deploy:
-    needs: [refresh, validate]
-    # Runs on a push too, where refresh is skipped.
-    if: always() && needs.validate.result == 'success' && (needs.refresh.result == 'success' || needs.refresh.result == 'skipped')
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: validate
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
-      - uses: actions/checkout@v4
-        with:
-          ref: main
-      - uses: actions/configure-pages@v5
-      - uses: actions/upload-pages-artifact@v3
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Bind the deployed provenance to this source revision
+        env:
+          PUBLICATION_REVISION: ${{ github.sha }}
+        run: node build/16-provenance.mjs
+      - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
         with:
           path: site
       - id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
@@ -0,0 +1,18 @@
+cff-version: 1.2.0
+message: "If this project supports your work, cite the repository and the dated source records used by the relevant layer."
+title: "Water and ice in Switzerland"
+type: software
+authors:
+  - name: "riverflow-ch contributors"
+repository-code: "https://github.com/jonashertner/riverflow-ch"
+url: "https://opengovclimate.ch/riverflow/"
+license: MIT
+version: 0.1.0
+date-released: 2026-08-22
+keywords:
+  - hydrology
+  - water quality
+  - wetlands
+  - Switzerland
+  - environmental law
+  - open government data
@@ -0,0 +1,35 @@
+# Code of conduct
+
+## Our pledge
+
+We pledge to make participation in this project a harassment-free experience
+for everyone, regardless of age, body size, visible or invisible disability,
+ethnicity, sex characteristics, gender identity and expression, level of
+experience, education, socioeconomic status, nationality, personal appearance,
+race, caste, colour, religion, or sexual identity and orientation.
+
+We will act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive and healthy community.
+
+## Expected behaviour
+
+- Be precise about evidence and generous with people.
+- Welcome corrections and explain disagreement with sources and reasoning.
+- Respect privacy, professional duties and the safety of affected communities.
+- Accept responsibility, apologize when appropriate and learn from mistakes.
+- Keep scientific and legal scrutiny independent of personal or political attack.
+
+Harassment, intimidation, discriminatory language, deliberate misinformation,
+publication of private information, and retaliation against good-faith reviewers
+are not acceptable.
+
+## Enforcement
+
+Report conduct concerns privately to the repository owner through the security
+contact described in [SECURITY.md](SECURITY.md). Reports will be reviewed
+promptly, fairly and as confidentially as possible. Maintainers may edit or
+remove contributions, limit participation, or permanently exclude a participant
+when necessary to protect the community.
+
+This policy is adapted from the [Contributor Covenant 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html),
+licensed under CC BY 4.0.
@@ -0,0 +1,16 @@
+# Content and data licensing
+
+Original explanatory text, diagrams and documentation in this repository are
+licensed under [Creative Commons Attribution 4.0 International](https://creativecommons.org/licenses/by/4.0/).
+Attribute them to “Water and ice in Switzerland contributors” and link to the
+repository where practical.
+
+Code is licensed separately under the [MIT License](LICENSE).
+
+Third-party datasets, maps, names and other source material are **not
+relicensed**. Each retains the terms of its holder. The publication records the
+holder, direct source, data date and licence for every source on the live Sources
+page and in `site/data/vintage.json`. When a derived artifact combines sources,
+all applicable source attributions and restrictions continue to apply.
+
+Logos, institutional names and trademarks remain the property of their owners.
@@ -0,0 +1,34 @@
+# Governance
+
+Riverflow is a public evidence project. Maintainers are responsible for the
+publication process; no maintainer owns the underlying facts.
+
+## Decisions
+
+- Scientific claims require a primary source, data date and stated limitation.
+- Legal claims require the operative text, jurisdiction and date checked.
+- Material data, method and copy changes are made by pull request.
+- At least one review is required before `main` changes. Authors do not approve
+  their own pull requests.
+- Generated data refreshes receive the same review as hand-written changes.
+- Uncertainty is disclosed next to the claim it qualifies.
+
+## Roles
+
+Contributors propose evidence, analysis, code, translations and corrections.
+Reviewers assess work within their expertise. Maintainers protect the release
+process, resolve conflicts and publish accepted work. Scientific or legal review
+does not imply institutional endorsement.
+
+## Conflicts of interest
+
+Anyone reviewing a claim should disclose a financial, professional, litigation
+or institutional relationship that a reasonable reader could see as relevant.
+Disclosure does not automatically disqualify a reviewer; it lets maintainers
+assign additional independent review where needed.
+
+## Becoming a maintainer
+
+Maintainers are added after a sustained record of careful, constructive and
+independent contributions. The decision and scope of access are recorded in a
+public issue or pull request.
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 riverflow-ch contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
@@ -21,15 +21,15 @@ primary law and reproducible methods that can support legal action when needed.
 | Layer | Evidence |
 |---|---|
 | River flow | Current BAFU discharge where a station passes the live-data rules; indicative estimates elsewhere |
-| Against normal | Current discharge divided by a modelled annual mean; not a drought index |
+| Relative to mean | Current discharge divided by a modelled annual mean; not a drought index |
 | Temperature | Current BAFU station readings |
-| Water quality | All 1'543'996 results in the current prepared NAWA TREND release, reduced to station-year summaries with exact laboratory rows on demand |
-| Reservoirs | 225 dam structures and a separate weekly regional energy-storage series |
+| Water quality | The current prepared NAWA TREND release, reduced to station-year summaries with exact laboratory rows on demand |
+| Reservoirs | Federally supervised dam structures and a separate weekly regional energy-storage series |
 | Ice | Glacier area in six inventories: 1850, 1931, 1973, 2010, 2016 and 2023 |
 | Residual flow | BAFU Q347 points and an illustrative Art. 31(1) calculation |
 | Water use | Federal registers of hydropower, abstractions, nuclear sites and treatment plants |
 | Wetlands | Five federal inventories of protected wetlands |
-| Water sources | Groundwater bodies, headwaters, sub-catchments and drinking-water protection zones |
+| Sources and groundwater | Groundwater bodies, headwaters, sub-catchments and drinking-water protection zones |
 | Monitoring duties | Federal duties and a 26-canton public-evidence audit; evidence and freshness, not a compliance score |
 
 This is not a forecast, a finding of breach or legal advice. It is also not a
@@ -86,6 +86,9 @@ Please use GitHub issues for data defects, source updates and research proposals
 Pull requests should keep the five language editions and the release checks in
 sync.
 
+The [roadmap](ROADMAP.md) defines the evidence needed to extend this foundation
+through the full water cycle and into obligation-level monitoring and enforcement.
+
 ## Run locally
 
 The publication is static and has no application backend.
@@ -105,18 +108,21 @@ view.
 ## Verify a release
 
 ```bash
-node scripts/verify-site.mjs
+npm ci
+npm test
 ```
 
 The release gate checks all five languages, links, metadata, accessibility,
 translations, JavaScript and JSON syntax, dataset identities, units, time-series
-order, published counts and artifact hashes.
+order, data-derived publication facts, semantic invariants and artifact hashes.
 
 ## Rebuild data
 
-The build uses Bash, curl, unzip, Node 22 and mapshaper 0.7.53.
+The build uses Bash, curl, unzip and Node 22. Exact JavaScript and map-processing
+dependencies are locked in `package-lock.json`.
 
 ```bash
+npm ci
 bash build/00-sources.sh
 node build/01-stations.mjs
 node build/02-network.mjs
@@ -134,6 +140,7 @@ node build/17-quality.mjs
 node build/18-monitoring.mjs
 node build/08-vintage.mjs
 python3 build/14-pages.py build
+node build/15-social-card.mjs
 node build/16-provenance.mjs
 node scripts/verify-site.mjs
 ```
@@ -146,12 +153,22 @@ each holder and term.
 
 ## Publication
 
-GitHub Actions verifies every push to `main`. A weekly job refreshes federal
-stations, reservoirs, water quality, cantonal deliveries, wetlands and source
-dates, rebuilds provenance, validates the refreshed artifact, and publishes only
-after all checks pass. The curated legal-evidence audit changes only after its
-primary canton records are reviewed again.
+GitHub Actions verifies every pull request and every push to `main`. A weekly job
+builds federal and cantonal updates as a downloadable review patch. It never
+writes directly to `main`. A maintainer applies the patch on a branch, reviews
+the source and data diff, and opens a pull request. Deployment runs only for a
+validated `main` revision and binds that revision into the deployed provenance.
+The curated legal-evidence audit changes only after its primary records are
+reviewed again.
 
 The repository is the publication record. A map URL stores its layer, centre and
 zoom so a view can be cited, but live observations still need their station time
 and underlying BAFU source.
+
+## Licence and governance
+
+Code is available under the [MIT License](LICENSE). Original explanatory content
+is available under [CC BY 4.0](CONTENT-LICENSE.md). Upstream datasets retain their
+own terms and are never relicensed here. See [GOVERNANCE.md](GOVERNANCE.md) for
+review and decision rules, [SECURITY.md](SECURITY.md) for private vulnerability
+reports, and [CITATION.cff](CITATION.cff) for citation metadata.