RallypointOne · joshday · Sep 8, 2026 · Sep 3, 2026 · Sep 3, 2026 · Sep 8, 2026
diff --git a/.github/workflows/Docs.yml b/.github/workflows/Docs.yml
@@ -4,6 +4,8 @@ on:
   push:
     branches:
       - main
+    tags:
+      - 'v*'
   release:
     types: [published]
   workflow_dispatch:
@@ -21,12 +23,19 @@ jobs:
     steps:
       - uses: actions/checkout@v7
 
-      # Determine deploy target from ref
+      # Determine deploy target from ref.
+      # A tag push is the reliable release signal: TagBot pushes tags over an SSH deploy
+      # key (which does trigger workflows), but creates the GitHub Release with
+      # GITHUB_TOKEN — and token-authored events never start a workflow run.
       - name: Set deploy version
         id: version
         run: |
           if [ "${{ github.event_name }}" = "release" ]; then
             VERSION="${{ github.event.release.tag_name }}"
+          elif [ "${{ github.ref_type }}" = "tag" ]; then
+            VERSION="${{ github.ref_name }}"
+          fi
+          if [ -n "$VERSION" ]; then
             echo "version=$VERSION" >> "$GITHUB_OUTPUT"
             echo "is_release=true" >> "$GITHUB_OUTPUT"
           else
@@ -46,6 +55,8 @@ jobs:
       - uses: quarto-dev/quarto-actions/setup@v2
       - name: Set build date
         run: sed -i "s/__BUILD_DATE__/$(date -u +'%Y-%m-%d')/" docs/_quarto.yml
+      # Retry: QuartoNotebookRunner precompiles outside the cached depot on first
+      # run, which can exceed the render timeout; the second attempt succeeds.
       - name: Render docs
         run: quarto render docs || quarto render docs
 
@@ -75,6 +86,13 @@ jobs:
           rm -rf "gh-pages-deploy/${VERSION}"
           cp -r docs/_site "gh-pages-deploy/${VERSION}"
 
+          # Inject version + base path into every rendered page so the version
+          # selector doesn't have to guess from the URL.
+          find "gh-pages-deploy/${VERSION}" -name '*.html' -exec sed -i \
+            -e "s|__CURRENT_VERSION__|${VERSION}|g" \
+            -e "s|__BASE_PATH__|/${REPO_NAME}/|g" \
+            {} +
+
           cd gh-pages-deploy
 
           # If release tag: update versions.json and stable redirect
@@ -111,22 +129,24 @@ jobs:
           STABLE_EOF
           fi
 
-          # Create stable placeholder if no releases yet
-          if [ ! -d stable ]; then
+          # (Re)write stable placeholder while no releases exist. Once versions.json
+          # is non-empty, the release branch above owns stable/ so we leave it alone.
+          if [ ! -f versions.json ] || [ "$(tr -d ' \n' < versions.json)" = "[]" ]; then
             mkdir -p stable
             cat > stable/index.html << PLACEHOLDER_EOF
           <!DOCTYPE html>
           <html>
           <head>
           <meta charset="utf-8">
           <meta name="viewport" content="width=device-width, initial-scale=1">
-          <title>No Stable Release Yet</title>
+          <title>${REPO_NAME} — No Stable Release Yet</title>
+          <meta http-equiv="refresh" content="5; url=/${REPO_NAME}/dev/">
           <link href="https://cdn.jsdelivr.net/npm/bootstrap@5/dist/css/bootstrap.min.css" rel="stylesheet">
           </head>
           <body class="d-flex align-items-center justify-content-center min-vh-100 bg-light">
           <div class="text-center p-5">
-          <h1 class="mb-3">No Stable Release Yet</h1>
-          <p class="lead text-muted">This package has not published a release.<br>Check out the <a href="/${REPO_NAME}/dev/">development docs</a> instead.</p>
+          <h1 class="mb-3">${REPO_NAME}</h1>
+          <p class="lead text-muted">No stable version has been released yet.<br>Redirecting to the <a href="/${REPO_NAME}/dev/">development docs</a> in 5 seconds...</p>
           </div>
           </body>
           </html>

diff --git a/.github/workflows/DocsBackfill.yml b/.github/workflows/DocsBackfill.yml
@@ -19,23 +19,19 @@ jobs:
         with:
           fetch-depth: 0
 
-      # Save docs infrastructure from main (without coverage — too slow for backfill)
+      # Save docs infrastructure from main. Regenerating coverage for every tag is
+      # too slow, so the coverage page is swapped for a placeholder — that keeps the
+      # sidebar structure intact and lets LocalCoverage drop out of the environment.
       - name: Save docs infrastructure
         run: |
           cp -r docs /tmp/docs-infrastructure
-          rm -f /tmp/docs-infrastructure/coverage.qmd
+          cat > /tmp/docs-infrastructure/pages/coverage.qmd << 'COVERAGE_EOF'
+          ---
+          title: "Coverage"
+          ---
 
-          # Remove coverage chapter from _quarto.yml
-          python3 -c "
-          import re
-          with open('/tmp/docs-infrastructure/_quarto.yml') as f:
-              content = f.read()
-          content = re.sub(r'\n\s*- coverage\.qmd', '', content)
-          with open('/tmp/docs-infrastructure/_quarto.yml', 'w') as f:
-              f.write(content)
-          "
-
-          # Remove LocalCoverage from docs/Project.toml
+          Coverage is reported for the current release only.
+          COVERAGE_EOF
           sed -i '/LocalCoverage/d' /tmp/docs-infrastructure/Project.toml
 
       - uses: julia-actions/setup-julia@v3
@@ -112,6 +108,14 @@ jobs:
             fi
 
             cp -r docs/_site "gh-pages-deploy/$TAG"
+
+            # Inject version + base path into every rendered page so the version
+            # selector doesn't render raw placeholders.
+            find "gh-pages-deploy/$TAG" -name '*.html' -exec sed -i \
+              -e "s|__CURRENT_VERSION__|$TAG|g" \
+              -e "s|__BASE_PATH__|/${REPO_NAME}/|g" \
+              {} +
+
             BUILT+=("$TAG")
             echo "Success: $TAG"
           done

diff --git a/.github/workflows/LiveTests.yml b/.github/workflows/LiveTests.yml
@@ -0,0 +1,33 @@
+name: LiveTests
+on:
+  push:
+    branches:
+      - main
+      - master
+  pull_request:
+  workflow_dispatch:
+
+# The public Overpass API asks users not to run multiple scripts in parallel,
+# so the live tests run on a single job and never concurrently for the same ref.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
+
+jobs:
+  live:
+    name: Live Overpass API
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      actions: write
+      contents: read
+    env:
+      OVERPASS_LIVE_TESTS: "true"
+    steps:
+      - uses: actions/checkout@v7
+      - uses: julia-actions/setup-julia@v3
+        with:
+          version: '1'
+      - uses: julia-actions/cache@v3
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-runtest@v1
diff --git a/.github/workflows/TagBot.yml b/.github/workflows/TagBot.yml
@@ -8,11 +8,6 @@ on:
       lookback:
         description: "[DEPRECATED] No longer has any effect"
         default: "3"
-permissions:
-  actions: read
-  contents: write
-  issues: read
-  pull-requests: read
 jobs:
   TagBot:
     if: github.event_name == 'workflow_dispatch' || github.actor == 'JuliaTagBot'

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -1,6 +1,7 @@
 # Development
 
 - Run tests: `julia --project -e 'using Pkg; Pkg.test()'`
+- Live tests against the public Overpass API (`test/test_service.jl`) are opt-in: `OVERPASS_LIVE_TESTS=true`. They run in CI only in the LiveTests workflow, on a single job.
 - Build docs: `quarto render docs`
 - `docs/` has its own Project.toml for doc-specific dependencies.
 - Each .qmd file in the docs should have `engine: julia` in the YAML frontmatter
@@ -11,7 +12,6 @@
 
 - `api.qmd` must always be the last item before the "Reference" section in `_quarto.yml`
 - `api.qmd` lives in its own `part: "API"` to visually separate it from other doc pages
-- The API page uses open cards (not collapsible blocks) to display exports
 
 # Style
 

diff --git a/docs/.gitignore b/docs/.gitignore
@@ -1,2 +1,5 @@
 /.quarto/
+/_site/
 **/*.quarto_ipynb
+/pages/coverage/
+/pages/lcov.info
diff --git a/docs/_quarto.yml b/docs/_quarto.yml
@@ -2,7 +2,7 @@ project:
   type: book
   output-dir: _site
 
-engine: julia
+engines: ['julia']
 julia:
   project: "."
 
@@ -13,6 +13,8 @@ book:
     keyboard-shortcut:
       - "/"
   navbar:
+    logo: assets/logo.svg
+    logo-href: https://rallypoint1.com
     right:
       - icon: star
         href: https://github.com/RallypointOne/OverpassAPI.jl/stargazers
@@ -27,11 +29,11 @@ book:
         - overpass-ql.qmd
     - part: "API"
       chapters:
-        - api.qmd
+        - pages/api.qmd
     - part: "Reference"
       chapters:
         - changelog.qmd
-        - coverage.qmd
+        - pages/coverage.qmd
 
   page-footer:
     center: "Built on __BUILD_DATE__"
@@ -41,11 +43,10 @@ language:
 
 format:
   html:
-    css: styles.css
+    css: assets/styles.css
     number-sections: false
     theme:
-      light: flatly
-      dark: darkly
-    respect-user-color-scheme: true
+      - flatly
+      - assets/theme.scss
     include-after-body:
-      - file: _version-selector.html
+      - file: assets/_version-selector.html
diff --git a/docs/api.qmd b/docs/api.qmd