address search, changelog system, update AGENTS + README

Search: server-proxied Nominatim geocoding with rate limiting and
24h cache. Search bar moved inside the info panel with inline spinner
and attribution. (#11)

Changelog: CHANGELOG.md with project history, cli.py subcommand to
generate an HTML fragment, changelog modal with localStorage-based
new-update notification dot, Dockerfile build-time generation.

AGENTS.md: changelog guidelines (user-facing language, when to update,
agent behavior) and README sync convention.

README: added /search endpoint to API table.

Author: jackharrhy

.gitignore

@@ -6,3 +6,4 @@ __pycache__/
 *.egg-info/
 dist/
 .ruff_cache/
+src/where_the_plow/static/changelog.html

AGENTS.md

@@ -51,3 +51,32 @@ See the existing migrations in `db.init()` for examples (e.g. `geom` on
   `ip` + `user_agent` for fingerprinting.
 - `_client_ip(request)` helper in `routes.py` extracts IP from
   `X-Forwarded-For` with fallback to `request.client.host`.
+- `README.md` documents the API endpoint table, environment variables,
+  database schema, and stack. When adding or removing endpoints, update
+  the API table in the README to match.
+
+## Changelog
+
+`CHANGELOG.md` at the project root is for **end users**, not developers.
+Write in plain English -- no file paths, no code snippets, no technical
+jargon. Each entry links to a GitHub commit range via
+`[View changes](compare URL)` so technical users can drill in.
+
+**Format:** Each entry is `## YYYY-MM-DD — Title` followed by a few
+sentences, an optional `**Contributors:**` line (only for non-Jack
+contributors), and a `[View changes]()` link. Increment the
+`<!-- changelog-id: N -->` integer at the top whenever a new entry is added.
+
+**When to update:** User-facing features, significant bug fixes, and new
+data sources warrant a changelog entry. Internal refactors, code cleanup,
+CI changes, and documentation do not.
+
+**Agent behavior:** If a change looks changelog-worthy, mention it to the
+user ("This might warrant a changelog entry") but do NOT add it
+automatically. The user decides when to batch changes into an entry,
+typically before finishing a branch. Reference GitHub issues with `(#N)`
+when relevant.
+
+**Generating HTML:** After editing `CHANGELOG.md`, run
+`uv run python cli.py changelog` to regenerate the HTML fragment. The
+Dockerfile does this automatically at build time.

CHANGELOG.md

@@ -0,0 +1,44 @@
+<!-- changelog-id: 5 -->
+# Changelog
+
+## 2026-02-22 - Address Search
+You can now search for a street address and jump directly to it on the map,
+instead of scrolling and zooming manually.
+
+**Contributors:** [@blossom2016](https://github.com/blossom2016)
+[View changes](https://github.com/jackharrhy/where-the-plow/compare/c5672ad...42ddc1e)
+
+## 2026-02-22 - Email Signups & About Modal
+New welcome modal with information about the project and an email signup form.
+Leave your email to get notified when street-level plow alerts are ready.
+Social sharing images and SEO metadata added.
+
+[View changes](https://github.com/jackharrhy/where-the-plow/compare/ae41e5f...c5672ad)
+
+## 2026-02-21 - Coverage Playback Controls
+Play back coverage data as a time-lapse animation. Filter by vehicle type
+using the legend checkboxes. Follow a specific vehicle during playback.
+Improved time range slider and mobile layout.
+
+[View changes](https://github.com/jackharrhy/where-the-plow/compare/5036734...ae41e5f)
+
+## 2026-02-19 - Map Legend & Geolocate
+Collapsible legend showing vehicle types with color coding. "Locate me" button
+to center the map on your position.
+
+**Contributors:** [@AminTaheri23](https://github.com/AminTaheri23)
+[View changes](https://github.com/jackharrhy/where-the-plow/compare/5036734...7f4db6c)
+
+## 2026-02-19 - Coverage History & Heatmap
+View which streets have been plowed over the last 6, 12, or 24 hours. Switch
+between route lines and a heatmap view. Pick a specific date to review past
+coverage. Time slider to scrub through the window.
+
+[View changes](https://github.com/jackharrhy/where-the-plow/compare/4402d55...54f335f)
+
+## 2026-02-19 - Launch
+Live map of St. John's snowplow fleet. Vehicles update every 6 seconds from
+the City of St. John's AVL system. Click any vehicle to see its recent trail.
+Data is stored for historical playback.
+
+[View changes](https://github.com/jackharrhy/where-the-plow/compare/2a08888...4402d55)

Dockerfile

@@ -8,6 +8,8 @@ COPY pyproject.toml uv.lock ./
 RUN uv sync --frozen --no-dev
 
 COPY src/ src/
+COPY CHANGELOG.md cli.py ./
+RUN uv run python cli.py changelog
 
 EXPOSE 8000
 

README.md

@@ -49,6 +49,7 @@ All geo endpoints return GeoJSON. Full OpenAPI docs at [`/docs`](https://plow.ja
 | `GET /vehicles/nearby?lat=&lng=&radius=` | Vehicles within radius (meters) |
 | `GET /vehicles/{id}/history?since=&until=` | Position history for one vehicle |
 | `GET /coverage?since=&until=` | Per-vehicle LineString trails with timestamps |
+| `GET /search?q=` | Geocode an address via Nominatim (cached proxy) |
 | `GET /stats` | Collection statistics |
 | `GET /health` | Health check |
 | `POST /track` | Record anonymous viewport focus event |

cli.py

@@ -1,11 +1,14 @@
 """Dev CLI for where-the-plow."""
 
+import re
 import subprocess
 import sys
+from pathlib import Path
 
 COMMANDS = {
     "dev": "Run uvicorn in development mode with auto-reload",
     "start": "Run uvicorn in production mode",
+    "changelog": "Convert CHANGELOG.md to an HTML fragment",
 }
 
 APP = "where_the_plow.main:app"
@@ -43,6 +46,87 @@ def start():
     )
 
 
+def _md_inline(text: str) -> str:
+    """Convert inline markdown to HTML: bold, links, and issue references."""
+    # Convert **text** to <strong>text</strong>
+    text = re.sub(r"\*\*(.+?)\*\*", r"<strong>\1</strong>", text)
+    # Convert [text](url) to <a> tags
+    text = re.sub(
+        r"\[(.+?)\]\((.+?)\)",
+        r'<a href="\2" target="_blank" rel="noopener">\1</a>',
+        text,
+    )
+    # Convert standalone (#N) to issue links
+    text = re.sub(
+        r"\(#(\d+)\)",
+        r'(<a href="https://github.com/jackharrhy/where-the-plow/issues/\1" target="_blank" rel="noopener">#\1</a>)',
+        text,
+    )
+    return text
+
+
+def changelog():
+    root = Path(__file__).parent
+    md_path = root / "CHANGELOG.md"
+    out_path = root / "src" / "where_the_plow" / "static" / "changelog.html"
+
+    content = md_path.read_text()
+
+    # Extract changelog-id
+    id_match = re.search(r"<!--\s*changelog-id:\s*(\d+)\s*-->", content)
+    changelog_id = id_match.group(1) if id_match else "0"
+
+    # Split on ## headings; first chunk is the header/preamble, skip it
+    sections = re.split(r"^## ", content, flags=re.MULTILINE)
+
+    articles = []
+    for section in sections[1:]:
+        lines = section.strip()
+        # First line is the title
+        title, _, body = lines.partition("\n")
+        title = title.strip()
+        body = body.strip()
+
+        # Split body into paragraphs on double newlines
+        paragraphs = re.split(r"\n\n+", body)
+        p_html = []
+        for para in paragraphs:
+            if not para.strip():
+                continue
+            # Within a paragraph block, lines starting with [ (a link)
+            # are separate paragraphs (e.g. "View changes" links)
+            sub_parts: list[list[str]] = [[]]
+            for line in para.strip().splitlines():
+                stripped = line.strip()
+                if not stripped:
+                    continue
+                if stripped.startswith("[") and sub_parts[-1]:
+                    sub_parts.append([stripped])
+                else:
+                    sub_parts[-1].append(stripped)
+            for part in sub_parts:
+                if not part:
+                    continue
+                text = " ".join(part)
+                text = _md_inline(text)
+                p_html.append(f"<p>{text}</p>")
+
+        article = (
+            f"<article>\n<h2>{_md_inline(title)}</h2>\n"
+            + "\n".join(p_html)
+            + "\n</article>"
+        )
+        articles.append(article)
+
+    html = f'<div class="changelog" data-changelog-id="{changelog_id}">\n'
+    html += "\n".join(articles)
+    html += "\n</div>\n"
+
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(html)
+    print(f"Wrote changelog.html (changelog-id: {changelog_id})")
+
+
 def usage():
     print("Usage: uv run cli.py <command>\n")
     print("Commands:")
@@ -56,7 +140,7 @@ def main():
         usage()
 
     cmd = sys.argv[1]
-    {"dev": dev, "start": start}[cmd]()
+    {"dev": dev, "start": start, "changelog": changelog}[cmd]()
 
 
 if __name__ == "__main__":

docs/plans/2026-02-22-changelog-design.md

@@ -0,0 +1,75 @@
+# Changelog System Design
+
+## Summary
+
+Add a user-facing changelog to the site. CHANGELOG.md at project root, a CLI
+subcommand to convert it to an HTML fragment, baked into the Docker image at
+build time, a new Changelog dialog in the frontend, and a "new updates"
+notification dot using localStorage.
+
+## CHANGELOG.md Format
+
+```markdown
+<!-- changelog-id: N -->
+# Changelog
+
+## YYYY-MM-DD — Title
+Plain-English description of what changed. No code paths.
+References issues inline like (#11).
+
+**Contributors:** @username (only for non-Jack contributors)
+[View changes](https://github.com/jackharrhy/where-the-plow/compare/abc...def)
+```
+
+- `changelog-id` is an integer, incremented on each new entry
+- Reverse-chronological (newest first)
+- User-facing language only, link commit ranges for technical detail
+- Issue references as `(#N)` — converted to GitHub links in HTML
+
+## CLI Subcommand
+
+`cli.py changelog` — parses CHANGELOG.md, outputs HTML fragment to
+`src/where_the_plow/static/changelog.html`.
+
+Markdown parsing is minimal, using `re` — no external dependency:
+- Split on `## ` to get entries
+- Convert `**text**` → `<strong>`
+- Convert `[text](url)` → `<a>`
+- Convert `(#N)` → GitHub issue link
+- Extract `changelog-id` from HTML comment
+- Output: `<div data-changelog-id="N">` with `<article>` per entry
+
+## Dockerfile Integration
+
+After `COPY src/ src/`, add:
+```dockerfile
+COPY CHANGELOG.md cli.py ./
+RUN uv run python cli.py changelog
+```
+
+HTML fragment is baked into image at `/app/src/where_the_plow/static/changelog.html`.
+
+## Frontend
+
+### New HTML elements (index.html)
+- `#panel-footer`: add `<a href="#" id="btn-view-changelog">Changelog</a>`
+- About section in welcome modal: add `<button id="btn-about-changelog">`
+- New `#changelog-overlay` / `#changelog-modal` pair (same pattern as welcome)
+
+### JavaScript (app.js)
+- `CHANGELOG_KEY = "wtp-changelog-seen"` — stores last-seen changelog-id
+- On init: fetch `/static/changelog.html`, parse `data-changelog-id`, compare
+  with localStorage, add `has-update` class to footer link if newer
+- `showChangelog()`: inject HTML, show overlay, update localStorage, remove dot
+- `hideChangelog()`: hide overlay
+- Wired to: footer link, about-dialog button, close button, overlay click
+
+### CSS (style.css)
+- Reuse modal overlay/card pattern from welcome modal
+- `.has-update::after` — notification dot (accent color circle)
+- Changelog article styling: entry spacing, date headers
+
+## AGENTS.md Addition
+
+New `## Changelog` section with guidelines on when to update, what to write,
+and how to suggest updates without auto-adding.