Add generating-coverage-reports docs page and .svx → .md export pipeline

.github/workflows/export-docs.yml

@@ -0,0 +1,57 @@
+# Docs export pipeline: renders the configured .svx files into plain markdown
+# and opens (or updates) a PR against CoverageTracker/coverage-tracker.
+#
+# This repo is the origin of truth for shared docs content — the generated
+# files downstream (docs/generating-coverage-reports.md, docs/INSTALLATION.md)
+# must never be edited directly. See README.md § Docs export pipeline for the
+# COVERAGE_TRACKER_SYNC_TOKEN setup.
+name: Export docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'src/lib/docs-content/*.svx'
+      - 'scripts/export-docs.ts'
+      - '.github/workflows/export-docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  export:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout coveragetracker.dev
+        uses: actions/checkout@v4
+
+      - name: Checkout coverage-tracker
+        uses: actions/checkout@v4
+        with:
+          repository: CoverageTracker/coverage-tracker
+          token: ${{ secrets.COVERAGE_TRACKER_SYNC_TOKEN }}
+          path: target-repo
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Export docs
+        run: node --experimental-strip-types scripts/export-docs.ts target-repo
+
+      # Fixed branch name so repeated runs update the same PR; skips cleanly
+      # (no commit, no PR) when the export produced no diff.
+      - name: Open or update sync PR
+        uses: peter-evans/create-pull-request@v7
+        with:
+          path: target-repo
+          token: ${{ secrets.COVERAGE_TRACKER_SYNC_TOKEN }}
+          branch: docs-sync
+          commit-message: 'docs: sync generated docs from coveragetracker.dev'
+          title: 'docs: sync generated docs from coveragetracker.dev'
+          body: |
+            Automated docs sync from [coveragetracker.dev](https://github.com/CoverageTracker/coveragetracker.dev) (`${{ github.sha }}`).
+
+            The files in this PR are generated from `src/lib/docs-content/*.svx` — do not edit them here; edit the `.svx` sources instead.

CLAUDE.md

@@ -10,9 +10,17 @@ pnpm build        # production build → .svelte-kit/cloudflare
 pnpm preview      # preview production build locally
 pnpm check        # svelte-kit sync + svelte-check (type checking)
 pnpm deploy       # build + wrangler pages deploy
+pnpm test         # vitest (remark plugins + docs exporter)
+pnpm export-docs <coverage-tracker-root>  # render .svx → downstream markdown
 ```
 
-There are no tests in this repo.
+## Docs are exported downstream
+
+`src/lib/docs-content/*.svx` is the origin of truth for shared docs. `scripts/export-docs.ts`
+renders configured files into `docs/generating-coverage-reports.md` and `docs/INSTALLATION.md`
+in the coverage-tracker repo (PR sync via `.github/workflows/export-docs.yml`). Never edit
+those generated files downstream. Content must stay dual-renderable: GFM tables and callouts
+work on GitHub too; wrap site-only markup in `<!-- site-only -->` … `<!-- /site-only -->`.
 
 ## Stack
 

README.md

@@ -74,6 +74,48 @@ static/
   logo-mark.svg
 ```
 
+## Docs export pipeline
+
+This repo is the **origin of truth for shared docs content**. The `.svx` files under
+`src/lib/docs-content/` are rendered into plain GitHub markdown and synced to the
+[`coverage-tracker`](https://github.com/CoverageTracker/coverage-tracker) repo via PR:
+
+- `12-generating-coverage-reports.svx` → `docs/generating-coverage-reports.md`
+- the quick-start / installation / usage sections → `docs/INSTALLATION.md`
+
+**Never edit those two files in the coverage-tracker repo** — they carry a `GENERATED`
+header and any direct edit is overwritten by the next sync. Edit the `.svx` sources here
+instead.
+
+The sync runs from `.github/workflows/export-docs.yml` on every push to `main` that touches
+a `.svx` file or the exporter, and opens/updates a PR on the fixed `docs-sync` branch
+(re-runs update the same PR; no diff → no PR). The target list is an explicit config in
+`scripts/export-docs.ts` — no globbing; adding a new synced doc is a deliberate config change.
+
+Run it locally against a sibling checkout:
+
+```bash
+pnpm export-docs ../coverage-tracker
+```
+
+### Provisioning the sync token
+
+The workflow authenticates with a fine-grained PAT stored as the repo secret
+`COVERAGE_TRACKER_SYNC_TOKEN`. The product GitHub App's permissions are deliberately
+**not** widened for this docs plumbing. To (re)provision the token — after expiry, a new
+fork, or a maintainer change:
+
+1. GitHub → **Settings → Developer settings → Personal access tokens → Fine-grained
+   tokens → Generate new token**
+2. Resource owner: the **CoverageTracker** org; Repository access: **Only select
+   repositories** → `coverage-tracker`
+3. Repository permissions: **Contents → Read and write**, **Pull requests → Read and
+   write**; everything else: No access
+4. Set an expiration and note it somewhere you'll see it — when the token lapses, the
+   workflow fails with an auth error on the checkout or PR step
+5. Save the token in **this repo** as the Actions secret `COVERAGE_TRACKER_SYNC_TOKEN`
+   (Settings → Secrets and variables → Actions)
+
 ## Theming
 
 The store writes `data-theme` and `data-mode` onto `<html>`; `app.css` maps each combination to