diff --git a/.claude/hooks/format-lint-python.sh b/.claude/hooks/format-lint-python.sh
index ed92dfc..ed392a4 100644
--- a/.claude/hooks/format-lint-python.sh
+++ b/.claude/hooks/format-lint-python.sh
@@ -10,4 +10,33 @@ elif command -v ruff &>/dev/null; then
     ruff format "$FILE" 2>/dev/null || true
     ruff check --fix "$FILE" 2>/dev/null || true
 fi
+
+# The project's own rules (lint/rules/), on the one file that just changed. Same
+# rules ./doit.sh lint runs over everything, so the hook cannot drift from CI.
+# Each rule decides whether the file is in its own scope.
+command -v uv &>/dev/null || exit 0
+
+# An environment that cannot run anything (fresh clone, offline uv cache) would
+# otherwise fail every rule and block every edit on a uv traceback. The exit code
+# cannot tell that apart afterwards: a rule that raises also exits 1. The ruff
+# steps above skip for the same reason.
+uv run python -c "" &>/dev/null || exit 0
+
+FAILURES=""
+collect() {
+    OUTPUT=$("$@" 2>&1) || FAILURES+="$OUTPUT"$'\n'
+    return 0
+}
+
+for RULE in lint/rules/*.py; do
+    [ -e "$RULE" ] || continue
+    collect uv run python "$RULE" "$FILE"
+done
+if compgen -G "lint/rules/*.yml" >/dev/null; then
+    collect uv run ast-grep scan "$FILE"
+fi
+if [[ -n "$FAILURES" ]]; then
+    printf '%s\n' "$FAILURES" >&2
+    exit 2
+fi
 exit 0
diff --git a/.claude/rules/docs.md b/.claude/rules/docs.md
new file mode 100644
index 0000000..f58f4f1
--- /dev/null
+++ b/.claude/rules/docs.md
@@ -0,0 +1,45 @@
+---
+paths:
+  - "docs/**/*.md"
+  - "README.md"
+  - ".claude/**/*.md"
+---
+
+# Documentation conventions
+
+For *where* a fact belongs (docs vs rule vs skill vs hook vs ADR), load the
+**ojhunt-update-env** skill. This rule covers how to write once you know the target.
+
+## Write only what cannot be derived
+
+Two questions kill most draft lines:
+
+- Can an agent derive this by opening one file? Delete the line.
+- Does a test, hook, or linter already assert it? Delete the line.
+
+Docs capture intent — why a construct is load-bearing, why the obvious alternative is
+wrong. Before writing a rule, try to make a test assert it instead: a test fails when
+somebody breaks the rule, a doc line does not.
+
+**Prefer deleting to adding.** Appending a clarification is the reflex; usually the file reads
+better with the wrong line gone. A false observation — a flaky test that was really a bad
+connection, a gotcha that was really local misconfiguration — is deleted, not corrected. A
+paragraph saying an earlier paragraph was wrong leaves the reader two claims to adjudicate.
+
+## README.md is a quick start
+
+Keep it short and direct: what the tool is, how to run it, one example per interface.
+Everything else is a link.
+
+When a section grows past a screen, move the detail into `docs/` and leave a pointer.
+Reference material belongs in [`docs/cli.md`](../../docs/cli.md),
+[`docs/web.md`](../../docs/web.md) and [`docs/library.md`](../../docs/library.md) — not in
+the README.
+
+`docs/library.md` is generated by `./doit.sh gen-docs`: write library-facing prose in the
+docstrings it compiles, never in the file itself. A unit test fails while the committed copy
+is stale.
+
+To check whether it is stale, run the task and read `.doit/gen-docs.log`: never suppress the
+generator's stderr, because a crash leaves the file untouched and so looks exactly like
+"already fresh".
diff --git a/docs/dev/e2e.md b/.claude/rules/e2e.md
similarity index 95%
rename from docs/dev/e2e.md
rename to .claude/rules/e2e.md
index 9d977dc..4043f38 100644
--- a/docs/dev/e2e.md
+++ b/.claude/rules/e2e.md
@@ -1,6 +1,11 @@
+---
+paths:
+  - "tests/e2e/**/*.py"
+---
+
 # E2E tests (Playwright)
 
-See [`docs/dev/testing.md`](testing.md) for shared pytest fixture and assertion conventions.
+See [`tests.md`](tests.md) for shared pytest fixture and assertion conventions.
 
 ## Setup
 
diff --git a/.claude/rules/hooks.md b/.claude/rules/hooks.md
new file mode 100644
index 0000000..a0f0981
--- /dev/null
+++ b/.claude/rules/hooks.md
@@ -0,0 +1,30 @@
+---
+paths:
+  - ".claude/hooks/**"
+  - ".claude/settings.json"
+---
+
+# Project hooks
+
+Hooks decide *when* a check runs. Check `.claude/settings.json` to see what is currently
+active.
+
+## Location
+
+Scripts live in `.claude/hooks/`, wired in `.claude/settings.json` (checked
+into git — not `settings.local.json`, not `~/.claude/`).
+
+## Keep the check out of the hook
+
+`format-lint-python.sh` runs ruff and then every rule in `lint/rules/` over the file that
+changed. What each rule checks is defined there, not here, so the hook and `./doit.sh lint`
+can never disagree. Adding a check to the hook alone gives you a rule that CI does not run and
+nobody can test — write it in `lint/rules/` instead (see `.claude/rules/lint-rules.md`).
+
+## Regex gotcha for command bans
+
+Do NOT use `(^|[;&|[:space:]])word[[:space:]]` — this matches the word inside
+quoted strings and heredocs (e.g. commit messages containing the banned word).
+
+Use `^[[:space:]]*(sudo[[:space:]]+)?word[[:space:]]` to only match when the
+word is the actual command at the start of the line.
diff --git a/.claude/rules/lint-rules.md b/.claude/rules/lint-rules.md
new file mode 100644
index 0000000..efca82f
--- /dev/null
+++ b/.claude/rules/lint-rules.md
@@ -0,0 +1,51 @@
+---
+paths:
+  - "lint/**"
+  - "tests/lint/**"
+---
+
+# Project lint rules
+
+Rules the project enforces on its own code, beyond what ruff covers. They live in
+`lint/rules/`, run from `./doit.sh lint`, and run again from the edit-time hook on the single
+file that changed — one definition, so the hook cannot drift from CI.
+
+```bash
+./doit.sh lint          # every rule over the whole repo
+./doit.sh lint-rules    # the rules' own tests
+uv run python lint/rules/<rule>.py <file>...   # one rule, one file
+```
+
+## When a convention earns a rule
+
+A rule pays for itself when the convention is objective and somebody will break it without
+noticing. If judging a case needs context the parser does not have, leave the convention in
+`.claude/rules/*.md` as prose — a rule that misfires teaches everyone to ignore it.
+
+Before writing prose, check whether a rule can assert it instead: a rule fails when somebody
+breaks the convention, a paragraph does not.
+
+## Pick the form
+
+| Form | Use when | Tests |
+|------|----------|-------|
+| `lint/rules/<id>.yml` | The match is purely structural — a node shape, nesting, a pattern | `lint/rule-tests/<id>-test.yml` |
+| `lint/rules/<id>.py` | The match needs source position, file paths, or cross-file state | `tests/lint/<id>_test.py` |
+
+Position is the usual reason to reach for Python. A YAML rule sees the parse tree, where a
+trailing comment and an own-line comment are the same shape; only line and column separate
+them. `comment_above_assert.py` exists for exactly that reason — its docstring says so.
+
+A Python rule is a script: `find_violations(source, path)` for tests to call, and a `main()`
+that takes file arguments, prints to stderr and returns 1 on a finding. Copy the shape from
+`lint/rules/comment_above_assert.py`.
+
+For ast-grep's rule syntax, node kinds and relational operators, query the ast-grep
+documentation through Context7 rather than looking for it here.
+
+## Every rule ships with its tests
+
+`tests/lint/rules_are_tested_test.py` fails when a rule has no test file, so this is not a
+convention you can forget. Cover the edge cases, not just the happy path — for anything
+position-sensitive, pin **which line** each case is blamed on, and include the cases that must
+stay silent.
diff --git a/docs/dev/python.md b/.claude/rules/python.md
similarity index 85%
rename from docs/dev/python.md
rename to .claude/rules/python.md
index 9489cc1..238eaa3 100644
--- a/docs/dev/python.md
+++ b/.claude/rules/python.md
@@ -1,3 +1,9 @@
+---
+paths:
+  - "**/*.py"
+  - "pyproject.toml"
+---
+
 # Python conventions
 
 ## Import order
@@ -30,7 +36,7 @@ Do not use `Dict`, `List`, `Optional` or `Union` from `typing` — ruff rewrites
 (`UP006`, `UP007`, `UP035`, `UP045`), and the `format-lint-python.sh` hook applies that
 rewrite on every edit. Take `Callable` and `Awaitable` from `collections.abc`, not `typing`.
 
-See [ADR 0016](../adr/0016-adopt-ruff-default-rule-set.md) for why this reversed.
+See [ADR 0016](../../docs/adr/0016-adopt-ruff-default-rule-set.md) for why this reversed.
 
 ## Prefer asserts and names over comments
 
@@ -45,7 +51,9 @@ Asserts are for what the code guarantees itself. Data arriving from outside —
 argument, a judge's response — needs a real `raise`, because `python -O` strips asserts.
 
 In tests, put the explanation in the assert message, not in a comment above it:
-`assert "items" in listed, "dict's own attributes must survive"`.
+`assert "items" in listed, "dict's own attributes must survive"`. This is enforced —
+`lint/rules/comment_above_assert.py` flags a comment beside an `assert`, whether it sits
+above the line or trails it.
 
 Where a comment would explain *what* an expression produces, name the value instead:
 `single_line_description = " ".join(text.split())`.
@@ -67,9 +75,9 @@ resolve. This applies to all packages including FastAPI, uvicorn, etc.
 
 ## Ruff removes imports before their usage
 
-Ruff (pre-commit hook) runs between edits and strips imports that appear unused at
-that moment. If you add an import in one `Edit` call and the code that uses it in a
-second call, ruff will delete the import between the two calls.
+Ruff runs between edits and strips imports that appear unused at that moment. If you add an
+import in one `Edit` call and the code that uses it in a second call, ruff will delete the
+import between the two calls.
 
 **Fix:** always add new imports and the code that uses them in the same `Edit` call.
 
diff --git a/docs/dev/testing.md b/.claude/rules/tests.md
similarity index 76%
rename from docs/dev/testing.md
rename to .claude/rules/tests.md
index 4d7d1b6..73e79f8 100644
--- a/docs/dev/testing.md
+++ b/.claude/rules/tests.md
@@ -1,7 +1,14 @@
+---
+paths:
+  - "**/*_test.py"
+  - "tests/**/*.py"
+---
+
 # Pytest conventions
 
-Crawler-specific test conventions live in [`docs/dev/crawlers.md`](crawlers.md) and the
-**ojhunt-crawlers** skill. Playwright e2e tests live in [`docs/dev/e2e.md`](e2e.md).
+Crawler-specific test conventions live in [`docs/dev/crawlers.md`](../../docs/dev/crawlers.md)
+and the **ojhunt-crawlers** skill. Playwright e2e tests have their own rule in
+[`e2e.md`](e2e.md).
 
 ## Running tests
 
@@ -47,6 +54,13 @@ client = TestClient(app, follow_redirects=False)
 files = {"field": ("name.pdf", bytes_content, "application/pdf")}
 ```
 
+## Prefer discovery over a hardcoded list
+
+A test that enumerates today's routes, crawlers, or files goes stale in silence: the thing it
+was meant to catch is exactly the new entry nobody added to the list. Walk the router or glob
+the directory instead. When a shape genuinely cannot be discovered, assert that no such shape
+exists yet, so the day one appears the suite says so.
+
 ## Markdown doc tests
 
 Python fenced blocks in `README.md` and `docs/` are collected by `pytest-markdown-docs`
diff --git a/.claude/rules/web.md b/.claude/rules/web.md
new file mode 100644
index 0000000..a85cf7f
--- /dev/null
+++ b/.claude/rules/web.md
@@ -0,0 +1,97 @@
+---
+paths:
+  - "src/ojhunt/web/**"
+---
+
+# Web layer conventions
+
+Dev server lifecycle and environment variables are operational, not code conventions —
+they live in [`docs/dev/web.md`](../../docs/dev/web.md). For user-facing usage see
+[`docs/web.md`](../../docs/web.md).
+
+## PDF internals
+
+- `extract_data(pdf_bytes)` returns `PdfEmbeddedData` — has `settings` and `history` only.
+  It does **not** have a `snapshot`; the snapshot is never embedded in the PDF. Build one
+  manually from history if needed.
+- For page routes returning `application/pdf` on success and HTML on error: return explicit
+  `Response(content=..., media_type="application/pdf")` or `HTMLResponse(...)` — do not use
+  `response_class=HTMLResponse` on the decorator.
+- When adding form-based page endpoints accessible to agents, document them in `llms.txt`.
+
+## Minimal JS principle
+
+Keep JavaScript minimal. Business logic belongs in Python; JS handles only browser-specific
+concerns.
+
+- Day boundary / timezone computation → backend (frontend sends IANA timezone string)
+- History merge/dedup → backend
+- Pydantic schemas on all new API endpoints (not loose dicts)
+- Prefer a POST to the server over inline JS computation
+
+JS is appropriate for: reading local files, computing timezone name via
+`Intl.DateTimeFormat().resolvedOptions().timeZone`, triggering downloads, reactive UI state.
+
+## FastAPI trailing slashes + StaticFiles
+
+When `StaticFiles` is mounted at `"/"`, FastAPI's `redirect_slashes` is suppressed.
+`Mount("/")` matches every path first and returns 404 for paths that aren't real files —
+the redirect never fires.
+
+- `fetch()` URLs in `app.js` must exactly match the route path in `api.py` (no trailing
+  slashes unless the route has one)
+- HTML `href` attributes are harmless (browsers follow 307 redirects), but `fetch()` calls
+  can silently fail because StaticFiles returns a non-JSON 404 body that breaks `response.json()`
+
+## Reverse-proxy rate limiting (429)
+
+The app itself never emits HTTP 429 — rate limiting is enforced by the production reverse
+proxy, and its 429 body is **not** JSON. Any client `fetch` that reaches the server can
+therefore receive a 429 with an HTML/plain-text body.
+
+- Client `fetch` handlers must special-case `response.status === 429` **before** calling
+  `response.json()` — otherwise the non-JSON body makes `response.json()` throw and the user
+  sees a confusing parse error instead of a rate-limit message.
+- Established guards live in `app.js`: `executeQuery`, `calculateReport`, `downloadReport`.
+
+## CSS conventions
+
+CSS files live at `src/ojhunt/web/static/assets/`:
+
+| File | What belongs here |
+|------|-------------------|
+| `base.css` | Design-system tokens (`:root`, `[data-accent=...]`), page resets, `.topbar`, `.page`, `.header`, `.footer`, `dialog`/`.dlg-*`, `.card` base layout (including `::before` stripe and `:hover`), `[x-cloak]`, `:focus-visible`, responsive media queries for shared components |
+| `index.css` | Everything used *only* by the home page: `.step`, `.report-slot`, `.grid`, card internals (`.c-hd`, `.c-body-row`, `.c-ft`, `.c-err-msg`, `.solved-link`, `.subs-val`, `.iconbtn`, `.loading-dots`, `.card-empty`), card status variants (`.card.r-ok::before` etc.), `.download-card`/`.summary`/`.dc-*`/`.stat`, `.composer`, `.field`, `.btn` (all variants), `.step-actions` |
+
+**Short templates** (crawlers, about, pdf pages) keep their inline `<style>` blocks — only extract when a template's styles grow long.
+
+**The critical rule:** anything from the original `base.html.jinja` `<style>` block that *any* page besides `index.html` uses must stay in `base.css`. The `about` page uses `.card`, `.card::before`, and `.card:hover` — these are in `base.css`.
+
+**Referencing CSS in templates:**
+
+```html
+<link rel="stylesheet" href="/assets/base.css?v={{ static_version }}">
+```
+
+`static_version` is a Jinja2 global injected via `jinja_env.globals["static_version"] = STATIC_VERSION` in `pages.py` — no need to pass it in individual `.render()` calls.
+
+**Visual regression tests** live in `tests/e2e/test_visual.py` (local-only, skipped in CI). After any CSS change:
+
+```bash
+# Update baselines (dangerouslyDisableSandbox: true)
+./doit.sh update-snapshots
+
+# Verify no unintended visual diff (dangerouslyDisableSandbox: true)
+./doit.sh test-visual
+```
+
+Baselines are stored in `tests/e2e/__snapshots__/`. Commit baseline PNGs alongside the test or CSS change that necessitates them.
+
+## Project history context (for UI copy)
+
+When writing UI copy that refers to "the old site":
+- **Old site** = `github.com/Liu233w/acm-statistics` deployment (also known as *ACM Statistics*,
+  *OJ Analyzer*, *OJHunt*)
+- **Not** npuacm.info (built by Jiduo Zhang; unrelated to this codebase)
+- VPS compromise: October 2025 — data after 2025-10-22 was lost
+- `legacy.db` preserves history up to 2025-10-22; web + CLI export available
diff --git a/.claude/skills/ojhunt-crawlers/SKILL.md b/.claude/skills/ojhunt-crawlers/SKILL.md
index 3b54ed0..7b4ac4c 100644
--- a/.claude/skills/ojhunt-crawlers/SKILL.md
+++ b/.claude/skills/ojhunt-crawlers/SKILL.md
@@ -9,7 +9,7 @@ This skill is the **procedure**. The reference material it points to —
 `__crawler_meta__` fields, login types, code templates, HTML parsing, SSL, license header,
 archived-crawler rules — lives in **`docs/dev/crawlers.md`**. Read that alongside these steps.
 
-For general pytest conventions see **`docs/dev/testing.md`**. For ADR guidance on significant
+For general pytest conventions see **`.claude/rules/tests.md`**. For ADR guidance on significant
 design decisions, invoke the **ojhunt-commit** skill.
 
 ## Implementing a New Crawler
diff --git a/.claude/skills/ojhunt-implement/SKILL.md b/.claude/skills/ojhunt-implement/SKILL.md
index 80e1797..f198d9b 100644
--- a/.claude/skills/ojhunt-implement/SKILL.md
+++ b/.claude/skills/ojhunt-implement/SKILL.md
@@ -7,7 +7,8 @@ description: End-to-end feature workflow — plan (in plan mode) → approval 
 
 This skill is the **procedure** for taking a feature from request to committed code.
 It only orchestrates — the *conventions* for each area (Python style, tests, web
-layer, crawlers, …) live in `docs/dev/*.md`, indexed by the routing table in
+layer, crawlers, …) load from `.claude/rules/*.md` on a file match, or sit in `docs/dev/*.md`
+indexed by the routing table in
 `docs/development.md`. Read the matching doc **before** you write code in that area.
 
 ## User request
@@ -22,7 +23,7 @@ make the change reviewable — don't skip ahead.
 1. **Plan first, and get approval.** If you are not already in plan mode, enter it
    (EnterPlanMode) — planning before editing is what lets the user redirect the
    approach cheaply, before any code is written. Explore the relevant code, read the
-   matching `docs/dev/*.md`, then draft a concrete plan and present it for approval
+   matching rule or `docs/dev/*.md`, then draft a concrete plan and present it for approval
    (ExitPlanMode). **Do not implement until the user approves** — the request above
    is a starting point, not a mandate to build immediately.
 
diff --git a/.claude/skills/ojhunt-update-env/SKILL.md b/.claude/skills/ojhunt-update-env/SKILL.md
index 69d9562..afd0e48 100644
--- a/.claude/skills/ojhunt-update-env/SKILL.md
+++ b/.claude/skills/ojhunt-update-env/SKILL.md
@@ -9,13 +9,22 @@ description: Single source of truth for where each piece of knowledge belongs (d
 documentation, point to the authoritative source — don't inline definitions that already exist
 elsewhere. Duplication causes drift.
 
-**Workflow vs. convention — pick the right channel.** A **workflow** (a procedure you run on
-demand: commit, implement a crawler, decide where knowledge goes) is a **skill**. A
-**convention or reference fact** (code style, a schema, a gotcha, a test rule) is a **doc under
-`docs/dev/`** — because skills are lazily triggered and unreliably loaded, whereas `docs/dev/`
-is indexed by `docs/development.md`, which is `@`-imported into `CLAUDE.md` and therefore always
-in context. Don't put a convention in a skill hoping it triggers; add it to `docs/dev/` and its
-routing-table row.
+**Route by what triggers the knowledge, not by what it is about.** A **workflow** (a procedure
+you run on demand: commit, implement a crawler, decide where knowledge goes) is a **skill**. A
+**convention tied to editing a kind of file** is a **rule under `.claude/rules/`** with `paths:`
+frontmatter, so it enters context the moment a matching file is opened. Don't put a convention in
+a skill hoping it triggers.
+
+**`paths:` cannot trigger everything.** Keep a fact in `docs/dev/` plus a routing-table row when:
+
+- The file does not exist yet. A rule fires when Claude *reads* a matching file, so writing a
+  brand-new crawler has nothing to trigger on — this is why `docs/dev/crawlers.md` stays a doc.
+- The knowledge precedes any file: whether to write an ADR, which layer a fact belongs to,
+  which branch to commit on. No glob matches a decision.
+- The activity is not file editing at all: starting the dev server, deploying, ops.
+
+One more limit worth knowing: after `/compact`, path-scoped rules are **not** re-injected. They
+reload the next time a matching file is read. Root `CLAUDE.md` is re-injected.
 
 **Command docs span multiple layers — search before changing.** Shell commands (e.g. how to
 run tests, start the server, add a dependency) can be documented in skills, READMEs, `docs/`,
@@ -39,22 +48,41 @@ Documentation for users running or deploying the project:
   detail in `docs/dev/`, not here.
 - `docs/adr/` — Architectural decisions (see below)
 
-## `docs/dev/` (internal conventions & reference)
-The home for development conventions, schemas, templates, and gotchas — the knowledge you need
-*while working* but that isn't a procedure. One file per domain:
+## `.claude/rules/` (conventions that load on a file match)
+Conventions for editing a kind of file. Each carries `paths:` frontmatter and loads by itself:
+- `python.md` — `**/*.py`, `pyproject.toml`: import order, typing, comments, dependencies
+- `tests.md` — `**/*_test.py`, `tests/**`: pytest conventions, CI scope, page-route tests
+- `e2e.md` — `tests/e2e/**`: Playwright / visual regression conventions
+- `web.md` — `src/ojhunt/web/**`: PDF internals, minimal-JS, CSS, FastAPI gotchas
+- `docs.md` — `docs/**`, `README.md`, `.claude/**`: what to write and what to leave out
+- `hooks.md` — `.claude/hooks/**`, `.claude/settings.json`: hook wiring and the regex gotcha
+- `lint-rules.md` — `lint/**`, `tests/lint/**`: when a convention earns a lint rule, which
+  form it takes (YAML or Python), and the requirement that every rule ships with tests
+
+A rule is not a place to dump reference material: it costs context every time a matching file
+is opened. Keep each one to conventions somebody could get wrong.
+
+## `docs/dev/` (reference no file pattern can trigger)
 - `docs/dev/crawlers.md` — crawler metadata schema, login types, return format, templates,
   HTML parsing, SSL, license header, archived-crawler rules
-- `docs/dev/python.md` — import order, typing, error handling, dependencies (`uv add`)
-- `docs/dev/testing.md` — pytest conventions, CI scope, page-route tests, markdown doc tests
-- `docs/dev/e2e.md` — Playwright e2e / visual regression conventions
-- `docs/dev/web.md` — FastAPI app, PDF internals, dev server, env vars, minimal-JS, CSS
-- `docs/dev/hooks.md` — how project hooks work and the command-ban regex gotcha
+- `docs/dev/web.md` — dev server lifecycle, ports in worktrees, environment variables
 - `docs/dev/deployment.md` — system fonts, `legacy.db`, PDF preview script
 
 **When adding a fact here, add a routing-table row to `docs/development.md`** if the domain is
 new, so the agent can find it. **Only document what's non-obvious** — if Claude can derive it by
 reading the files, or it's enforced elsewhere (hook, test, linter), don't write it.
 
+**Docs capture intent, not facts that can be reasoned.** Two questions kill most draft lines:
+
+- Can an agent derive this by opening one file? Delete the line.
+- Does a test, hook, or linter already assert it? Delete the line.
+
+**Before writing a rule, try to make a test assert it instead.** A test fails when somebody
+breaks the rule; a doc line does not. Prefer a test that *discovers* what it checks (walk the
+router, glob the crawler files) over one that hardcodes today's list — a hardcoded list goes
+stale silently, which is the gap the rule was meant to close. Document only what the test
+cannot express: why the rule exists.
+
 **When a well-written doc already covers a topic, reference it — don't replicate.** A skill or
 another doc should point to the authoritative file plus any gotchas it doesn't capture.
 
@@ -83,7 +111,7 @@ directory. Use the `ojhunt-` prefix to group related project skills.
 
 ## Hooks (`.claude/hooks/` + `.claude/settings.json`)
 Hard enforcement rules — things the agent must never do or must always do automatically.
-Update when you need mechanical enforcement, not just reminders. See `docs/dev/hooks.md`.
+Update when you need mechanical enforcement, not just reminders. See `.claude/rules/hooks.md`.
 
 ## Commands (`.claude/commands/`)
 Project-level slash commands that override global ones.
@@ -138,8 +166,9 @@ not here.
 - Development convention, style, schema, or gotcha for a code area → `docs/dev/<area>.md`
   (add a routing-table row in `docs/development.md` if the domain is new)
 - Workflow or process (a procedure run on demand) → `.claude/skills/ojhunt-*/`
-- "Never do X" or "always do Y after Z" → **hook first** (see `docs/dev/hooks.md`); once
-  hook-enforced, do NOT also add a doc/skill entry — the hook is the enforcement, a note just
+- "Never do X" or "always do Y after Z" → a **lint rule** in `lint/rules/` when a parser can
+  judge it (see `.claude/rules/lint-rules.md`), wired by a hook (`.claude/rules/hooks.md`);
+  once enforced, do NOT also add a doc/skill entry — the rule is the enforcement, a note just
   creates drift
 - Project-level command override → `.claude/commands/`
 - Significant architectural decision (multiple approaches considered, choice non-obvious from code) → `docs/adr/`
diff --git a/CLAUDE.md b/CLAUDE.md
index 5f3664e..0b38f53 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,15 +4,15 @@
 
 Run `./doit.sh help` for the full list. Key tasks:
 
-- `./doit.sh lint` — ruff linter
+- `./doit.sh lint` — ruff plus the project's own rules in `lint/rules/`
 - `./doit.sh test-unit` — unit tests (fast, no network, no browser)
 - `./doit.sh test-e2e` — browser e2e tests, excluding visual (starts dev server if needed)
 - `./doit.sh test-crawler <name>` — network tests for one crawler (e.g. `codeforces`)
 - `./doit.sh test-visual` / `update-snapshots` — visual regression tests
-- `./doit.sh full-check` — lint + all tests (unit, e2e, visual); starts & stops the server
+- `./doit.sh full-check` — lint + rule tests + all tests (unit, e2e, visual); starts & stops the server
 - `./doit.sh start` / `kill` / `status` / `logs` — dev server lifecycle
 
-When a `lint`/`test-*`/`full-check` task fails, its full output is already saved to `.doit/<task>.log` — **read that log** (e.g. `grep -nE 'FAILED|error' .doit/test-unit.log`) instead of re-running the task with `| tail`/`| grep`. `full-check` runs each step as its own task, so read the specific step's log (`.doit/test-e2e.log`, `.doit/test-visual.log`, …); its own stdout is only a short `full-check PASSED/FAILED` summary, so don't pipe it through `| tail` either.
+When a `lint*`/`test-*`/`full-check` task fails, its full output is already saved to `.doit/<task>.log` — **read that log** (e.g. `grep -nE 'FAILED|error' .doit/test-unit.log`) instead of re-running the task with `| tail`/`| grep`. `full-check` runs each step as its own task, so read the specific step's log (`.doit/test-e2e.log`, `.doit/test-visual.log`, …); its own stdout is only a short `full-check PASSED/FAILED` summary, so don't pipe it through `| tail` either.
 
 ## Where to find documentation
 
@@ -20,8 +20,9 @@ When a `lint`/`test-*`/`full-check` task fails, its full output is already saved
 - **Development conventions & reference** → the index in [docs/development.md](docs/development.md)
 - **Architectural decisions** → [docs/adr/](docs/adr/)
 
-The development index is imported below so its routing table — "working on X → read
-`docs/dev/X.md`" — is always in context. Follow it to the right reference before starting work.
+Code conventions load by themselves: `.claude/rules/*.md` carry `paths:` frontmatter, so the
+Python, test, e2e, web-layer, docs and hook rules enter context when you open a matching file.
+The development index below routes what no file pattern can trigger.
 
 @docs/development.md
 
@@ -35,18 +36,18 @@ tool (don't read skill files as plain text):
 - **ojhunt-commit** — commit, commit conventions, ADRs
 - **ojhunt-update-env** — decide where a new piece of knowledge belongs
 
-**Conventions and reference** (Python style, tests, e2e, web layer, hooks, crawler reference,
-deployment) are *not* skills — they live in `docs/dev/*.md`, indexed by the routing table in
-`docs/development.md` (imported above). Read the matching doc before working in that area
-rather than relying on a skill to trigger.
+**Conventions and reference** are *not* skills. A convention tied to editing a kind of file
+lives in `.claude/rules/*.md` and loads on its own. Crawler reference and ops knowledge stay in
+`docs/dev/*.md`, routed by the table in `docs/development.md` (imported above).
 
 ### Growing project knowledge
 
 If the user mentions a workflow, convention, or recurring pattern that isn't captured yet,
-route it: a **workflow/procedure** → a skill; a **convention or reference fact** →
-`docs/dev/*.md` (and add a row to the routing table in `docs/development.md`); a **hard rule**
-→ a hook. Ask the user before adding, and see the **ojhunt-update-env** skill for the full
-routing map. Don't silently let project knowledge go undocumented.
+route it: a **workflow/procedure** → a skill; a **convention tied to a kind of file** →
+`.claude/rules/*.md` with `paths:` frontmatter; a **fact no file pattern can trigger** →
+`docs/dev/*.md` plus a routing-table row; a **cheap deterministic check** → a hook. Ask the
+user before adding, and see the **ojhunt-update-env** skill for the full routing map. Don't
+silently let project knowledge go undocumented.
 
 ### Self-correcting on repeated failures
 
diff --git a/docs/adr/0016-adopt-ruff-default-rule-set.md b/docs/adr/0016-adopt-ruff-default-rule-set.md
index acdef0c..efb6cbb 100644
--- a/docs/adr/0016-adopt-ruff-default-rule-set.md
+++ b/docs/adr/0016-adopt-ruff-default-rule-set.md
@@ -13,7 +13,7 @@ Two of the newly enabled rule groups collide with the codebase on purpose rather
 accident:
 
 - `UP006`, `UP007`, `UP035` and `UP045` — 341 of the 534 findings — demand PEP 585 and PEP 604
-  syntax (`dict[str, X]`, `X | None`). `docs/dev/python.md` said the opposite: "Use `Dict`,
+  syntax (`dict[str, X]`, `X | None`). The Python convention said the opposite: "Use `Dict`,
   `List`, `Union` from the `typing` module." Both rules cannot hold.
 - `BLE001` flags 23 `except Exception` blocks. Every crawler ends in one by design.
 
@@ -52,7 +52,7 @@ recorded in config, and three at the site:
 | `# noqa: UP031` | `crawlers/eolymp.py` | `.format()` needs every brace in the GraphQL body doubled. |
 | `# noqa: DTZ007` | `web/pdf.py` | The chart axis parses day keys that are already local-day strings. It needs their order, not an instant. |
 
-`docs/dev/python.md` now states the PEP 585/604 rule, and the `query()` templates in
+`.claude/rules/python.md` now states the PEP 585/604 rule, and the `query()` templates in
 `docs/dev/crawlers.md` were updated so a new crawler does not reintroduce the old style.
 
 ## Consequences
diff --git a/docs/dev/docs.md b/docs/dev/docs.md
deleted file mode 100644
index 2756504..0000000
--- a/docs/dev/docs.md
+++ /dev/null
@@ -1,18 +0,0 @@
-# Documentation conventions
-
-## README.md is a quick start
-
-Keep it short and direct: what the tool is, how to run it, one example per interface.
-Everything else is a link.
-
-When a section grows past a screen, move the detail into `docs/` and leave a pointer.
-Reference material belongs in [`docs/cli.md`](../cli.md), [`docs/web.md`](../web.md) and
-[`docs/library.md`](../library.md) — not in the README.
-
-`docs/library.md` is generated by `./doit.sh gen-docs`: write library-facing prose in the
-docstrings it compiles, never in the file itself. A unit test fails while the committed copy
-is stale.
-
-To check whether it is stale, run the task and read `.doit/gen-docs.log`: never suppress the
-generator's stderr, because a crash leaves the file untouched and so looks exactly like
-"already fresh".
diff --git a/docs/dev/hooks.md b/docs/dev/hooks.md
deleted file mode 100644
index 7c1442a..0000000
--- a/docs/dev/hooks.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# Project hooks
-
-Hooks enforce constraints mechanically. Check `.claude/settings.json` to see
-what's currently active.
-
-## Location
-
-Scripts live in `.claude/hooks/`, wired in `.claude/settings.json` (checked
-into git — not `settings.local.json`, not `~/.claude/`).
-
-## Regex gotcha for command bans
-
-Do NOT use `(^|[;&|[:space:]])word[[:space:]]` — this matches the word inside
-quoted strings and heredocs (e.g. commit messages containing the banned word).
-
-Use `^[[:space:]]*(sudo[[:space:]]+)?word[[:space:]]` to only match when the
-word is the actual command at the start of the line.
diff --git a/docs/dev/web.md b/docs/dev/web.md
index 02d0028..6ba0c0e 100644
--- a/docs/dev/web.md
+++ b/docs/dev/web.md
@@ -1,8 +1,8 @@
-# Web layer
+# Web layer operations
 
-Internal reference for the FastAPI app, PDF handling, dev server, and frontend conventions.
-For user-facing usage (production deployment, container, API endpoints) see
-[`docs/web.md`](../web.md).
+Running the dev server and configuring it. Code conventions for the web layer load
+automatically from `.claude/rules/web.md` when you edit `src/ojhunt/web/`. For user-facing
+usage (production deployment, container, API endpoints) see [`docs/web.md`](../web.md).
 
 ## Running the dev server
 
@@ -33,16 +33,6 @@ Use `doit.sh` — it starts the server, waits until it's ready, and manages the
 - e2e tests auto-discover the port (`OJHUNT_DEV_PORT` → `.doit/server.port` → 8080), so
   `./doit.sh test-e2e` / `test-visual` work in any worktree.
 
-## PDF internals
-
-- `extract_data(pdf_bytes)` returns `PdfEmbeddedData` — has `settings` and `history` only.
-  It does **not** have a `snapshot`; the snapshot is never embedded in the PDF. Build one
-  manually from history if needed.
-- For page routes returning `application/pdf` on success and HTML on error: return explicit
-  `Response(content=..., media_type="application/pdf")` or `HTMLResponse(...)` — do not use
-  `response_class=HTMLResponse` on the decorator.
-- When adding form-based page endpoints accessible to agents, document them in `llms.txt`.
-
 ## Environment variables
 
 | Variable | Required | Description |
@@ -54,80 +44,3 @@ Use `doit.sh` — it starts the server, waits until it's ready, and manages the
 
 Credentials go in `.env` (gitignored) — loaded automatically by `load_dotenv()` in
 `src/ojhunt/web/app.py`. No need to `source .env` manually.
-
-## Minimal JS principle
-
-Keep JavaScript minimal. Business logic belongs in Python; JS handles only browser-specific
-concerns.
-
-- Day boundary / timezone computation → backend (frontend sends IANA timezone string)
-- History merge/dedup → backend
-- Pydantic schemas on all new API endpoints (not loose dicts)
-- Prefer a POST to the server over inline JS computation
-
-JS is appropriate for: reading local files, computing timezone name via
-`Intl.DateTimeFormat().resolvedOptions().timeZone`, triggering downloads, reactive UI state.
-
-## FastAPI trailing slashes + StaticFiles
-
-When `StaticFiles` is mounted at `"/"`, FastAPI's `redirect_slashes` is suppressed.
-`Mount("/")` matches every path first and returns 404 for paths that aren't real files —
-the redirect never fires.
-
-- `fetch()` URLs in `app.js` must exactly match the route path in `api.py` (no trailing
-  slashes unless the route has one)
-- HTML `href` attributes are harmless (browsers follow 307 redirects), but `fetch()` calls
-  can silently fail because StaticFiles returns a non-JSON 404 body that breaks `response.json()`
-
-## Reverse-proxy rate limiting (429)
-
-The app itself never emits HTTP 429 — rate limiting is enforced by the production reverse
-proxy, and its 429 body is **not** JSON. Any client `fetch` that reaches the server can
-therefore receive a 429 with an HTML/plain-text body.
-
-- Client `fetch` handlers must special-case `response.status === 429` **before** calling
-  `response.json()` — otherwise the non-JSON body makes `response.json()` throw and the user
-  sees a confusing parse error instead of a rate-limit message.
-- Established guards live in `app.js`: `executeQuery`, `calculateReport`, `downloadReport`.
-
-## CSS conventions
-
-CSS files live at `src/ojhunt/web/static/assets/`:
-
-| File | What belongs here |
-|------|-------------------|
-| `base.css` | Design-system tokens (`:root`, `[data-accent=...]`), page resets, `.topbar`, `.page`, `.header`, `.footer`, `dialog`/`.dlg-*`, `.card` base layout (including `::before` stripe and `:hover`), `[x-cloak]`, `:focus-visible`, responsive media queries for shared components |
-| `index.css` | Everything used *only* by the home page: `.step`, `.report-slot`, `.grid`, card internals (`.c-hd`, `.c-body-row`, `.c-ft`, `.c-err-msg`, `.solved-link`, `.subs-val`, `.iconbtn`, `.loading-dots`, `.card-empty`), card status variants (`.card.r-ok::before` etc.), `.download-card`/`.summary`/`.dc-*`/`.stat`, `.composer`, `.field`, `.btn` (all variants), `.step-actions` |
-
-**Short templates** (crawlers, about, pdf pages) keep their inline `<style>` blocks — only extract when a template's styles grow long.
-
-**The critical rule:** anything from the original `base.html.jinja` `<style>` block that *any* page besides `index.html` uses must stay in `base.css`. The `about` page uses `.card`, `.card::before`, and `.card:hover` — these are in `base.css`.
-
-**Referencing CSS in templates:**
-
-```html
-<link rel="stylesheet" href="/assets/base.css?v={{ static_version }}">
-```
-
-`static_version` is a Jinja2 global injected via `jinja_env.globals["static_version"] = STATIC_VERSION` in `pages.py` — no need to pass it in individual `.render()` calls.
-
-**Visual regression tests** live in `tests/e2e/test_visual.py` (local-only, skipped in CI). After any CSS change:
-
-```bash
-# Update baselines (dangerouslyDisableSandbox: true)
-./doit.sh update-snapshots
-
-# Verify no unintended visual diff (dangerouslyDisableSandbox: true)
-./doit.sh test-visual
-```
-
-Baselines are stored in `tests/e2e/__snapshots__/`. Commit baseline PNGs alongside the test or CSS change that necessitates them.
-
-## Project history context (for UI copy)
-
-When writing UI copy that refers to "the old site":
-- **Old site** = `github.com/Liu233w/acm-statistics` deployment (also known as *ACM Statistics*,
-  *OJ Analyzer*, *OJHunt*)
-- **Not** npuacm.info (built by Jiduo Zhang; unrelated to this codebase)
-- VPS compromise: October 2025 — data after 2025-10-22 was lost
-- `legacy.db` preserves history up to 2025-10-22; web + CLI export available
diff --git a/docs/development.md b/docs/development.md
index 7010118..5423446 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -4,6 +4,10 @@ This is the **index** for internal development knowledge. It is `@`-imported int
 so the routing table below is always in context — use it to find the right reference before
 starting work. Keep this file short; put detail in `docs/dev/*.md`.
 
+Most code conventions are **not** listed here: they live in `.claude/rules/*.md` with `paths:`
+frontmatter and load by themselves when you open a matching file (Python, tests, e2e, the web
+layer, docs, hooks). The table below carries only what no file pattern can trigger.
+
 ## Setup
 
 ```bash
@@ -26,15 +30,13 @@ Read the matching reference **before** implementing or debugging in that area.
 |-------------|------|
 | Crawler reference (metadata schema, login types, return format, templates, HTML parsing, SSL, license, archived rules) | [`docs/dev/crawlers.md`](dev/crawlers.md) |
 | **Implementing / debugging** a crawler (procedure, decision tree, checklist) | **ojhunt-crawlers** skill |
-| Python style, typing, imports, dependencies (`uv add`) | [`docs/dev/python.md`](dev/python.md) |
-| Tests: pytest conventions, CI scope, page-route tests, markdown doc tests | [`docs/dev/testing.md`](dev/testing.md) |
-| Playwright e2e / visual regression tests | [`docs/dev/e2e.md`](dev/e2e.md) |
-| Web layer: FastAPI app, PDF internals, dev server, env vars, CSS, minimal-JS | [`docs/dev/web.md`](dev/web.md) |
-| Writing docs: what belongs in the README vs `docs/` | [`docs/dev/docs.md`](dev/docs.md) |
-| Claude Code hooks (enforcement rules) | [`docs/dev/hooks.md`](dev/hooks.md) |
+| Dev server: start/stop, ports in worktrees, env vars | [`docs/dev/web.md`](dev/web.md) |
 | Deployment / ops: system fonts, `legacy.db`, PDF preview | [`docs/dev/deployment.md`](dev/deployment.md) |
 | Committing, commit conventions, when to write an ADR | **ojhunt-commit** skill |
-| Where a new piece of knowledge belongs (docs vs skill vs hook vs ADR) | **ojhunt-update-env** skill |
+| Where a new piece of knowledge belongs (rule vs docs vs skill vs hook vs ADR) | **ojhunt-update-env** skill |
+
+A crawler is the one code area still routed by this table rather than by a rule: a new crawler
+starts as a file that does not exist yet, so no `paths:` pattern can fire on it.
 
 User-facing usage docs (not development conventions): [`docs/cli.md`](cli.md),
 [`docs/web.md`](web.md), [`docs/library.md`](library.md) — the last one is generated by
diff --git a/doit.sh b/doit.sh
index 93b6590..54f9a7a 100755
--- a/doit.sh
+++ b/doit.sh
@@ -205,15 +205,45 @@ status() {
 logs() { tail -F "$SERVER_LOG"; }
 
 lint() {
-  run_logged lint _ruff_check_and_format
+  run_logged lint _lint_all
 }
 
-# Both ruff passes always run, so one report lists every problem. Ruff 0.16 also
+# Every pass always runs, so one report lists every problem. Ruff 0.16 also
 # formats python blocks inside markdown, which `ruff check` alone does not see.
-_ruff_check_and_format() {
+# The project's own rules live in lint/rules/ — see .claude/rules/hooks.md.
+_lint_all() {
   local status=0
   uv run ruff check . || status=1
   uv run ruff format --check . || status=1
+  _project_lint_rules || status=1
+  return "$status"
+}
+
+# Python rules take the files to scan; each falls back to its own default scope.
+_project_lint_rules() {  # _project_lint_rules [file...]
+  local status=0 rule
+  for rule in lint/rules/*.py; do
+    [ -e "$rule" ] || continue
+    uv run python "$rule" "$@" || status=1
+  done
+  if compgen -G "lint/rules/*.yml" >/dev/null; then
+    uv run ast-grep scan "$@" || status=1
+  fi
+  return "$status"
+}
+
+# Tests for the rules themselves: pytest for the python ones, `ast-grep test`
+# for the yaml ones. tests/lint/ also fails when a rule has no tests at all.
+lint-rules() {
+  run_logged lint-rules _lint_rules_tests
+}
+
+_lint_rules_tests() {
+  local status=0
+  uv run pytest tests/lint -q || status=1
+  if compgen -G "lint/rules/*.yml" >/dev/null; then
+    uv run ast-grep test || status=1
+  fi
   return "$status"
 }
 
@@ -265,7 +295,7 @@ update-snapshots() {
 }
 
 full-check() {
-  # Full pre-commit gate: lint + every test suite (incl. visual) against a live
+  # Full pre-commit gate: lint + rule tests + every test suite (incl. visual) against a live
   # server. We own the server lifecycle so callers don't have to: start it once,
   # run everything, then stop it — but only if *we* started it, so a dev server
   # you left running with `./doit.sh start` survives.
@@ -278,13 +308,14 @@ full-check() {
   # function returns, where the local no longer exists and `set -u` would abort.
   trap "[[ $started_here == 1 ]] && kill" EXIT
   start
-  # Run all four to completion and collect failures rather than aborting on the
+  # Run every step to completion and collect failures rather than aborting on the
   # first — one run should surface every problem. `set +e` because these commands
   # are expected to fail sometimes and we handle the codes ourselves; each task
   # already tees its full output to .doit/<task>.log via run_logged.
   local -a failed=()
   set +e
   lint        || failed+=("lint")
+  lint-rules  || failed+=("lint-rules")
   test-unit   || failed+=("test-unit")
   test-e2e    || failed+=("test-e2e")
   test-visual || failed+=("test-visual")
@@ -293,7 +324,7 @@ full-check() {
     echo "full-check FAILED: ${failed[*]} — read .doit/<task>.log for details"
     return 1
   fi
-  echo "full-check PASSED (lint, test-unit, test-e2e, test-visual)"
+  echo "full-check PASSED (lint, lint-rules, test-unit, test-e2e, test-visual)"
 }
 
 help() {
@@ -309,13 +340,14 @@ Server:
   reap               kill orphaned servers whose git worktree has been removed
 
 Tests:
-  lint               run ruff linter and formatter check
+  lint               run ruff (linter + formatter check) and the rules in lint/rules/
+  lint-rules         test the lint rules themselves (pytest + ast-grep test)
   test-unit          run unit tests (no network, no playwright) [pytest-args...]
   test-e2e           run e2e tests excluding visual (starts server if needed) [pytest-args...]
   test-visual        run visual regression tests (starts server if needed) [pytest-args...]
   test-crawler NAME  run tests for a specific crawler by name [pytest-args...]
   update-snapshots   update visual regression snapshots (starts server if needed)
-  full-check         run lint + all tests (unit, e2e, visual); starts & stops the server
+  full-check         run lint + rule tests + all tests (unit, e2e, visual); starts & stops the server
 
 Docs:
   gen-docs           regenerate docs/library.md from the library docstrings
diff --git a/lint/rule-tests/.gitkeep b/lint/rule-tests/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/lint/rules/comment_above_assert.py b/lint/rules/comment_above_assert.py
new file mode 100644
index 0000000..931b23f
--- /dev/null
+++ b/lint/rules/comment_above_assert.py
@@ -0,0 +1,130 @@
+"""Lint rule: the explanation next to an assert belongs in its message.
+
+A comment is invisible when the assertion fails; a message prints with the
+failure. See `.claude/rules/python.md`.
+
+This rule is Python rather than YAML because it needs source position. A
+trailing comment and an own-line comment are the same shape in the parse tree —
+both are sibling nodes between two statements — so only line and column tell
+them apart. Getting that wrong reports the violation on the innocent line below
+it, or misses it entirely when no assert follows.
+
+Run over the default scope, or over named files. A named file outside the scope
+is skipped, so the edit-time hook can pass whatever file just changed and still
+report exactly what CI reports:
+
+    uv run python lint/rules/comment_above_assert.py
+    uv run python lint/rules/comment_above_assert.py tests/web/api_test.py
+"""
+
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from ast_grep_py import SgNode, SgRoot
+
+RULE_ID = "comment-above-assert"
+MESSAGE = "move the explanation into the assert message"
+
+NOTE = """\
+A comment is silent when the assert fails; a message prints.
+
+    # the crawler reports only an AC count
+    assert result["submissions"] == result["solved"]
+
+    assert result["submissions"] == result["solved"], (
+        "the crawler reports only an AC count"
+    )
+"""
+
+# Files the rule applies to, relative to the repository root.
+SCOPE = "tests/**/*.py"
+
+# A tool directive is addressed to another program, so "move it into the assert
+# message" is not advice anybody can take.
+PRAGMAS = ("# type:", "# noqa", "# pragma:", "# fmt:", "# ruff:")
+
+
+@dataclass(frozen=True)
+class Finding:
+    path: Path
+    line: int
+    comment: str
+
+    def __str__(self) -> str:
+        return f"{self.path}:{self.line}: {RULE_ID}: {MESSAGE}\n    {self.comment}"
+
+
+def _trailing_statement(comment: SgNode) -> SgNode | None:
+    """The statement this comment trails, or None when it sits on its own line."""
+    previous = comment.prev()
+    if previous is None:
+        return None
+    if previous.range().end.line != comment.range().start.line:
+        return None
+    return previous
+
+
+def _statement_below(comment: SgNode) -> SgNode | None:
+    """The statement this comment sits above.
+
+    A comment before the *first* statement of a body attaches to the enclosing
+    definition instead of the body, so the next sibling is the block itself.
+    """
+    below = comment.next()
+    if below is not None and below.kind() == "block":
+        children = below.children()
+        return children[0] if children else None
+    return below
+
+
+def find_violations(source: str, path: Path) -> list[Finding]:
+    """Every assert in `source` whose explanation sits in a comment."""
+    findings = []
+    for comment in SgRoot(source, "python").root().find_all(kind="comment"):
+        text = comment.text().strip()
+        if text.lower().startswith(PRAGMAS):
+            continue
+        trailed = _trailing_statement(comment)
+        target = trailed if trailed is not None else _statement_below(comment)
+        if target is None or target.kind() != "assert_statement":
+            continue
+        findings.append(Finding(path, target.range().start.line + 1, text))
+    return findings
+
+
+def scan(paths: list[Path]) -> list[Finding]:
+    findings = []
+    for path in sorted(paths):
+        findings.extend(find_violations(path.read_text(encoding="utf-8"), path))
+    return findings
+
+
+def scoped_files() -> list[Path]:
+    """Every file in SCOPE. The rule owns its scope, not its callers.
+
+    The hook passes the single file that just changed, whatever it is. Filtering
+    here is what keeps the hook and `./doit.sh lint` from disagreeing about
+    which files the rule covers.
+    """
+    return sorted(Path(__file__).parents[2].glob(SCOPE))
+
+
+def main(argv: list[str]) -> int:
+    scope = scoped_files()
+    if argv:
+        covered = {path.resolve() for path in scope}
+        paths = [path for path in map(Path, argv) if path.resolve() in covered]
+    else:
+        paths = scope
+    findings = scan(paths)
+    for finding in findings:
+        print(finding, file=sys.stderr)
+    if findings:
+        print(f"\n{NOTE}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
diff --git a/pyproject.toml b/pyproject.toml
index b081e54..fbb8827 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -77,4 +77,6 @@ dev = [
     "pytest-timeout>=2.4.0",
     "pytest-markdown-docs",
     "ruff>=0.15.1",
+    "ast-grep-cli>=0.45.1",
+    "ast-grep-py>=0.45.1",
 ]
diff --git a/sgconfig.yml b/sgconfig.yml
new file mode 100644
index 0000000..ee98e3c
--- /dev/null
+++ b/sgconfig.yml
@@ -0,0 +1,4 @@
+ruleDirs:
+  - lint/rules
+testConfigs:
+  - testDir: lint/rule-tests
diff --git a/src/ojhunt/web/app.py b/src/ojhunt/web/app.py
index b202404..5150798 100644
--- a/src/ojhunt/web/app.py
+++ b/src/ojhunt/web/app.py
@@ -24,7 +24,7 @@
 from ojhunt.web.api import router as api_router
 from ojhunt.web.crawler_status import start_checker, stop_checker
 from ojhunt.web.http_client import close_http_client, get_http_client, init_http_client
-from ojhunt.web.pages import jinja_env
+from ojhunt.web.pages import render_page
 from ojhunt.web.pages import router as pages_router
 
 load_dotenv()
@@ -145,9 +145,13 @@ async def http_exception_handler(
 ) -> Response:
     if exc.status_code == 404 and not request.url.path.startswith("/api"):
         image_filename = random.choice(["cat.jpg", "man.jpg", "metro.jpg"])
-        template = jinja_env.get_template("404.html.jinja")
         return HTMLResponse(
-            template.render(image_filename=image_filename),
+            render_page(
+                "404.html.jinja",
+                request,
+                canonical=False,
+                image_filename=image_filename,
+            ),
             status_code=404,
         )
     return await _default_http_exception_handler(request, exc)
diff --git a/src/ojhunt/web/pages.py b/src/ojhunt/web/pages.py
index 5ce9dde..a0e0761 100644
--- a/src/ojhunt/web/pages.py
+++ b/src/ojhunt/web/pages.py
@@ -83,8 +83,27 @@
 jinja_env.globals["static_version"] = STATIC_VERSION
 
 
+def render_page(
+    template_name: str, request: Request, *, canonical: bool = True, **context: object
+) -> str:
+    """Render a page template with the metadata `base.html.jinja` needs.
+
+    Pass `canonical=False` for a page that must stay out of the search index
+    (404, easter eggs) — a noindex page must not claim a canonical URL.
+
+    The canonical URL comes from the request URL itself, not from `base_url` plus
+    the path: both carry any ASGI `root_path`, so joining them repeats the mount
+    prefix. `site_base` keeps `base_url`, because it is joined with a literal path.
+    """
+    return jinja_env.get_template(template_name).render(
+        site_base=str(request.base_url).rstrip("/"),
+        canonical_url=str(request.url.replace(query="")) if canonical else None,
+        **context,
+    )
+
+
 @router.get("/", response_class=HTMLResponse)
-async def index() -> str:
+async def index(request: Request) -> str:
     crawler_data = {
         name: {
             "title": info.meta.title,
@@ -93,13 +112,11 @@ async def index() -> str:
         }
         for name, info in sorted(crawler_registry.items())
     }
-    template = jinja_env.get_template("index.html.jinja")
-    return template.render(crawlers=crawler_data)
+    return render_page("index.html.jinja", request, crawlers=crawler_data)
 
 
 @router.get("/about", response_class=HTMLResponse)
-async def about() -> str:
-    template = jinja_env.get_template("about.html.jinja")
+async def about(request: Request) -> str:
     build_time_str = None
     if BUILD_TIME:
         try:
@@ -111,7 +128,9 @@ async def about() -> str:
             )
         except ValueError:
             build_time_str = BUILD_TIME
-    return template.render(
+    return render_page(
+        "about.html.jinja",
+        request,
         build_time=build_time_str,
         git_commit_sha=GIT_COMMIT_SHA,
     )
@@ -155,22 +174,24 @@ async def statistics_redirect():
 
 
 @router.get("/pdf/legacy", response_class=HTMLResponse)
-async def pdf_legacy_get() -> str:
-    template = jinja_env.get_template("pdf_legacy.html.jinja")
-    return template.render(
+async def pdf_legacy_get(request: Request) -> str:
+    return render_page(
+        "pdf_legacy.html.jinja",
+        request,
         active_page="legacy",
         legacy_available=Path("legacy.db").exists(),
     )
 
 
 @router.post("/pdf/legacy")
-async def pdf_legacy_post(username: str = Form(...)):
-    template = jinja_env.get_template("pdf_legacy.html.jinja")
+async def pdf_legacy_post(request: Request, username: str = Form(...)):
     try:
         pdf_bytes = export_user_pdf(username.strip())
     except FileNotFoundError:
         return HTMLResponse(
-            template.render(
+            render_page(
+                "pdf_legacy.html.jinja",
+                request,
                 active_page="legacy",
                 legacy_available=False,
                 prefill_username=username,
@@ -178,7 +199,9 @@ async def pdf_legacy_post(username: str = Form(...)):
         )
     except ValueError as e:
         return HTMLResponse(
-            template.render(
+            render_page(
+                "pdf_legacy.html.jinja",
+                request,
                 active_page="legacy",
                 legacy_available=True,
                 error=str(e),
@@ -196,17 +219,16 @@ async def pdf_legacy_post(username: str = Form(...)):
 
 
 @router.get("/pdf/merge", response_class=HTMLResponse)
-async def pdf_merge_get() -> str:
-    template = jinja_env.get_template("pdf_merge.html.jinja")
-    return template.render(active_page="merge")
+async def pdf_merge_get(request: Request) -> str:
+    return render_page("pdf_merge.html.jinja", request, active_page="merge")
 
 
 @router.post("/pdf/merge")
 async def pdf_merge_post(
+    request: Request,
     pdf_a: UploadFile = File(...),
     pdf_b: UploadFile = File(...),
 ):
-    template = jinja_env.get_template("pdf_merge.html.jinja")
     try:
         bytes_a = await pdf_a.read()
         bytes_b = await pdf_b.read()
@@ -223,7 +245,11 @@ async def pdf_merge_post(
         )
         pdf_bytes = generate_pdf(data_a.settings, history, snapshot)
     except ValueError as e:
-        return HTMLResponse(template.render(active_page="merge", error=str(e)))
+        return HTMLResponse(
+            render_page(
+                "pdf_merge.html.jinja", request, active_page="merge", error=str(e)
+            )
+        )
     return Response(
         content=pdf_bytes,
         media_type="application/pdf",
@@ -232,7 +258,7 @@ async def pdf_merge_post(
 
 
 @router.get("/crawlers", response_class=HTMLResponse)
-async def crawlers_page(test_availability: str | None = None) -> str:
+async def crawlers_page(request: Request, test_availability: str | None = None) -> str:
     import json
 
     if test_availability is not None:
@@ -260,16 +286,16 @@ async def crawlers_page(test_availability: str | None = None) -> str:
                 ),
             }
         )
-    template = jinja_env.get_template("crawlers.html.jinja")
-    return template.render(crawlers=crawler_list)
+    return render_page("crawlers.html.jinja", request, crawlers=crawler_list)
 
 
 async def _easter_egg_handler(request: Request) -> HTMLResponse:
     easter_egg_path = random.choice(
         ["easter_egg.html.jinja", "easter_egg_rick.html.jinja"]
     )
-    template = jinja_env.get_template(easter_egg_path)
-    return HTMLResponse(template.render(path=request.url.path))
+    return HTMLResponse(
+        render_page(easter_egg_path, request, canonical=False, path=request.url.path)
+    )
 
 
 for _path in _EASTER_EGG_PATHS:
diff --git a/src/ojhunt/web/templates/404.html.jinja b/src/ojhunt/web/templates/404.html.jinja
index d26e930..c3a5d69 100644
--- a/src/ojhunt/web/templates/404.html.jinja
+++ b/src/ojhunt/web/templates/404.html.jinja
@@ -2,6 +2,8 @@
 
 {% block title %}???????? — OJHunt Lite{% endblock %}
 
+{% block robots %}<meta name="robots" content="noindex">{% endblock %}
+
 {% block extra_head %}
 <style>
     .error-page {
diff --git a/src/ojhunt/web/templates/base.html.jinja b/src/ojhunt/web/templates/base.html.jinja
index 143a63e..1232079 100644
--- a/src/ojhunt/web/templates/base.html.jinja
+++ b/src/ojhunt/web/templates/base.html.jinja
@@ -4,6 +4,16 @@
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>{% block title %}OJHunt Lite{% endblock %}</title>
+    <meta name="description" content="{% block meta_description %}A lightweight async Python tool for Online Judge (OJ) statistics. Track your accepted problems (AC) and submissions across 29+ competitive programming sites.{% endblock %}">
+    {% block robots %}{% endblock %}
+    {% if canonical_url %}<link rel="canonical" href="{{ canonical_url }}">{% endif %}
+    <meta property="og:type" content="website">
+    <meta property="og:site_name" content="OJHunt Lite">
+    <meta property="og:title" content="{{ self.title() }}">
+    <meta property="og:description" content="{{ self.meta_description() }}">
+    {% if canonical_url %}<meta property="og:url" content="{{ canonical_url }}">{% endif %}
+    {% if site_base %}<meta property="og:image" content="{{ site_base }}/assets/logo.png">{% endif %}
+    <meta name="twitter:card" content="summary">
     <link rel="icon" type="image/x-icon" href="/favicon.ico">
     <link rel="describedby" href="/llms.txt" type="text/plain">
     <link rel="preconnect" href="https://fonts.googleapis.com">
diff --git a/src/ojhunt/web/templates/crawlers.html.jinja b/src/ojhunt/web/templates/crawlers.html.jinja
index 4310223..f98edc2 100644
--- a/src/ojhunt/web/templates/crawlers.html.jinja
+++ b/src/ojhunt/web/templates/crawlers.html.jinja
@@ -60,6 +60,8 @@
 
 {% block title %}Supported Crawlers - OJHunt Lite{% endblock %}
 
+{% block meta_description %}All {{ crawlers | length }} online judges that OJHunt Lite supports, with live availability status — Codeforces, AtCoder, LeetCode, HDU, POJ, SPOJ, UVa and more.{% endblock %}
+
 {% block page_id %}page-crawlers{% endblock %}
 
 {% block content %}
diff --git a/src/ojhunt/web/templates/easter_egg.html.jinja b/src/ojhunt/web/templates/easter_egg.html.jinja
index c3bb81c..c919120 100644
--- a/src/ojhunt/web/templates/easter_egg.html.jinja
+++ b/src/ojhunt/web/templates/easter_egg.html.jinja
@@ -2,6 +2,8 @@
 
 {% block title %}你访问的不是 {{ path }} — OJHunt Lite{% endblock %}
 
+{% block robots %}<meta name="robots" content="noindex">{% endblock %}
+
 {% block extra_head %}
 <style>
     .easter-egg-page {
diff --git a/src/ojhunt/web/templates/easter_egg_rick.html.jinja b/src/ojhunt/web/templates/easter_egg_rick.html.jinja
index 863426d..27ec89c 100644
--- a/src/ojhunt/web/templates/easter_egg_rick.html.jinja
+++ b/src/ojhunt/web/templates/easter_egg_rick.html.jinja
@@ -2,6 +2,8 @@
 
 {% block title %}Never Gonna Give You Up — OJHunt Lite{% endblock %}
 
+{% block robots %}<meta name="robots" content="noindex">{% endblock %}
+
 {% block extra_head %}
 <style>
     .easter-egg-page {
diff --git a/src/ojhunt/web/templates/pdf_legacy.html.jinja b/src/ojhunt/web/templates/pdf_legacy.html.jinja
index 5bc5d53..2f8a542 100644
--- a/src/ojhunt/web/templates/pdf_legacy.html.jinja
+++ b/src/ojhunt/web/templates/pdf_legacy.html.jinja
@@ -2,6 +2,8 @@
 
 {% block title %}Legacy Data Export - OJHunt Lite{% endblock %}
 
+{% block meta_description %}Export your solved-problem history from the old acm-statistics site as an OJHunt PDF report, then carry it forward into new queries.{% endblock %}
+
 {% block pdf_heading %}legacy-export{% endblock %}
 {% block pdf_meta %}recover acm-statistics history{% endblock %}
 
diff --git a/src/ojhunt/web/templates/pdf_merge.html.jinja b/src/ojhunt/web/templates/pdf_merge.html.jinja
index dc26666..0ecf489 100644
--- a/src/ojhunt/web/templates/pdf_merge.html.jinja
+++ b/src/ojhunt/web/templates/pdf_merge.html.jinja
@@ -2,6 +2,8 @@
 
 {% block title %}Merge History - OJHunt Lite{% endblock %}
 
+{% block meta_description %}Merge two OJHunt PDF progress reports into one file that keeps the complete solved-problem history from both.{% endblock %}
+
 {% block pdf_heading %}merge-history{% endblock %}
 {% block pdf_meta %}combine history from multiple PDFs{% endblock %}
 
diff --git a/tests/cli/output_test.py b/tests/cli/output_test.py
index 72ba851..3545f59 100644
--- a/tests/cli/output_test.py
+++ b/tests/cli/output_test.py
@@ -464,8 +464,9 @@ def test_json_show_problems_ignored(self, capsys):
         ]
         print_report(results, show_problems=True, total_duration=1.0, json_output=True)
         data = json.loads(capsys.readouterr().out)
-        # solved_list is always in JSON regardless of show_problems
-        assert data["results"][0]["solved_list"] == ["1A", "2A"]
+        assert data["results"][0]["solved_list"] == ["1A", "2A"], (
+            "solved_list is always in JSON, regardless of show_problems"
+        )
 
 
 class TestPrintReportShowProblems:
diff --git a/tests/crawlers/aizu_test.py b/tests/crawlers/aizu_test.py
index 7afc167..6c29009 100644
--- a/tests/crawlers/aizu_test.py
+++ b/tests/crawlers/aizu_test.py
@@ -44,8 +44,10 @@ async def test_valid_user(session):
     assert result["submissions"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # Check that solved_list has the correct length
-    assert len(result["solved_list"]) == result["solved"]
+    assert len(result["solved_list"]) == result["solved"], (
+        "solved_list must hold one entry per solved problem"
+    )
 
-    # Check for known solved problem
-    assert "ALDS1_3_C" in result["solved_list"]
+    assert "ALDS1_3_C" in result["solved_list"], (
+        "a known solved problem must appear in solved_list"
+    )
diff --git a/tests/crawlers/atcoder_test.py b/tests/crawlers/atcoder_test.py
index 5b2b1ee..4d731a5 100644
--- a/tests/crawlers/atcoder_test.py
+++ b/tests/crawlers/atcoder_test.py
@@ -38,12 +38,13 @@ async def test_valid_user(session):
 
     assert isinstance(result["solved"], int)
     assert isinstance(result["submissions"], int)
-    assert (
-        result["solved_list"] is None
-    )  # kenkoooo API only provides AC count, not problem list
+    assert result["solved_list"] is None, (
+        "the kenkoooo API provides only an AC count, not a problem list"
+    )
 
     assert result["solved"] > 0
     assert result["submissions"] > 0
 
-    # AtCoder only returns AC count, so submissions == solved
-    assert result["submissions"] == result["solved"]
+    assert result["submissions"] == result["solved"], (
+        "AtCoder reports only an AC count, so submissions equals solved"
+    )
diff --git a/tests/crawlers/codechef_test.py b/tests/crawlers/codechef_test.py
index dd6ada2..6f562f8 100644
--- a/tests/crawlers/codechef_test.py
+++ b/tests/crawlers/codechef_test.py
@@ -44,8 +44,10 @@ async def test_valid_user(session):
     assert result["submissions"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # Check that solved_list has the correct length
-    assert len(result["solved_list"]) == result["solved"]
+    assert len(result["solved_list"]) == result["solved"], (
+        "solved_list must hold one entry per solved problem"
+    )
 
-    # Check for known solved problem
-    assert "KGOOD" in result["solved_list"]
+    assert "KGOOD" in result["solved_list"], (
+        "a known solved problem must appear in solved_list"
+    )
diff --git a/tests/crawlers/codeforces_test.py b/tests/crawlers/codeforces_test.py
index be301a5..89fc30f 100644
--- a/tests/crawlers/codeforces_test.py
+++ b/tests/crawlers/codeforces_test.py
@@ -45,8 +45,9 @@ async def test_valid_user(session):
     assert result["submissions"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # Check that solved_list has the correct length
-    assert len(result["solved_list"]) == result["solved"]
+    assert len(result["solved_list"]) == result["solved"], (
+        "solved_list must hold one entry per solved problem"
+    )
 
     # Check for known solved problems
     expected_problems = {
diff --git a/tests/crawlers/codewars_test.py b/tests/crawlers/codewars_test.py
index 627fbca..851c4cd 100644
--- a/tests/crawlers/codewars_test.py
+++ b/tests/crawlers/codewars_test.py
@@ -43,11 +43,14 @@ async def test_valid_user(session):
     assert result["solved"] > 0
     assert result["submissions"] > 0
 
-    # Codewars only returns completed kata count, so submissions == solved
-    assert result["submissions"] == result["solved"]
+    assert result["submissions"] == result["solved"], (
+        "Codewars reports only completed kata, so submissions equals solved"
+    )
 
-    # Check that solved_list has the correct length
-    assert len(result["solved_list"]) == result["solved"]
+    assert len(result["solved_list"]) == result["solved"], (
+        "solved_list must hold one entry per solved problem"
+    )
 
-    # Check for known solved problem
-    assert "equal-sides-of-an-array" in result["solved_list"]
+    assert "equal-sides-of-an-array" in result["solved_list"], (
+        "a known solved problem must appear in solved_list"
+    )
diff --git a/tests/crawlers/csu_test.py b/tests/crawlers/csu_test.py
index d0f1607..debd99c 100644
--- a/tests/crawlers/csu_test.py
+++ b/tests/crawlers/csu_test.py
@@ -44,8 +44,10 @@ async def test_valid_user(session):
     assert result["submissions"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # Check that solved_list has the correct length
-    assert len(result["solved_list"]) == result["solved"]
+    assert len(result["solved_list"]) == result["solved"], (
+        "solved_list must hold one entry per solved problem"
+    )
 
-    # Check for known solved problem
-    assert "1001" in result["solved_list"]
+    assert "1001" in result["solved_list"], (
+        "a known solved problem must appear in solved_list"
+    )
diff --git a/tests/crawlers/hdu_test.py b/tests/crawlers/hdu_test.py
index 57f6819..8da28b0 100644
--- a/tests/crawlers/hdu_test.py
+++ b/tests/crawlers/hdu_test.py
@@ -43,8 +43,10 @@ async def test_valid_user(session):
     assert result["submissions"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # Check that solved_list has the correct length
-    assert len(result["solved_list"]) == result["solved"]
+    assert len(result["solved_list"]) == result["solved"], (
+        "solved_list must hold one entry per solved problem"
+    )
 
-    # Check for known solved problem
-    assert "1001" in result["solved_list"]
+    assert "1001" in result["solved_list"], (
+        "a known solved problem must appear in solved_list"
+    )
diff --git a/tests/crawlers/leetcode_test.py b/tests/crawlers/leetcode_test.py
index 100dbef..86fe6f6 100644
--- a/tests/crawlers/leetcode_test.py
+++ b/tests/crawlers/leetcode_test.py
@@ -41,5 +41,6 @@ async def test_valid_user(session):
     assert result["solved"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # LeetCode does not expose the full solved list publicly
-    assert result["solved_list"] is None
+    assert result["solved_list"] is None, (
+        "LeetCode does not expose the full solved list publicly"
+    )
diff --git a/tests/crawlers/lightoj_test.py b/tests/crawlers/lightoj_test.py
index 1270650..72d6028 100644
--- a/tests/crawlers/lightoj_test.py
+++ b/tests/crawlers/lightoj_test.py
@@ -34,5 +34,6 @@ async def test_valid_user(session):
 
     assert result["solved"] > 0
     assert result["submissions"] >= result["solved"]
-    # solved_list is not available without authentication
-    assert result["solved_list"] is None
+    assert result["solved_list"] is None, (
+        "solved_list is unavailable without authentication"
+    )
diff --git a/tests/crawlers/loj_test.py b/tests/crawlers/loj_test.py
index 808c18e..c6e5344 100644
--- a/tests/crawlers/loj_test.py
+++ b/tests/crawlers/loj_test.py
@@ -37,8 +37,10 @@ async def test_valid_user(session):
     assert result["submissions"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # Check that solved_list has the correct length
-    assert len(result["solved_list"]) == result["solved"]
+    assert len(result["solved_list"]) == result["solved"], (
+        "solved_list must hold one entry per solved problem"
+    )
 
-    # Check for known solved problem
-    assert "103" in result["solved_list"]
+    assert "103" in result["solved_list"], (
+        "a known solved problem must appear in solved_list"
+    )
diff --git a/tests/crawlers/luogu_test.py b/tests/crawlers/luogu_test.py
index fd1cc0d..70ac698 100644
--- a/tests/crawlers/luogu_test.py
+++ b/tests/crawlers/luogu_test.py
@@ -41,14 +41,13 @@ async def test_valid_user(session):
 
     assert isinstance(result["solved"], int)
     assert isinstance(result["submissions"], int)
-    assert result["solved_list"] is None  # Luogu no longer exposes solved list
+    assert result["solved_list"] is None, "Luogu no longer exposes the solved list"
 
     assert result["solved"] > 0
     assert result["submissions"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # This user should have more than 100 solved problems
-    assert result["solved"] > 100
+    assert result["solved"] > 100, "the test user has solved more than 100 problems"
 
 
 @pytest.mark.asyncio
@@ -63,7 +62,7 @@ async def test_user_with_many_submissions(session):
 
     assert isinstance(result["solved"], int)
     assert isinstance(result["submissions"], int)
-    assert result["solved_list"] is None  # Luogu no longer exposes solved list
+    assert result["solved_list"] is None, "Luogu no longer exposes the solved list"
 
     assert result["solved"] > 0
     assert result["submissions"] > 1000
diff --git a/tests/crawlers/nbut_test.py b/tests/crawlers/nbut_test.py
index f8ae773..6c30b6b 100644
--- a/tests/crawlers/nbut_test.py
+++ b/tests/crawlers/nbut_test.py
@@ -44,8 +44,10 @@ async def test_valid_user(session):
     assert result["submissions"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # Check that solved_list has the correct length
-    assert len(result["solved_list"]) == result["solved"]
+    assert len(result["solved_list"]) == result["solved"], (
+        "solved_list must hold one entry per solved problem"
+    )
 
-    # Check for known solved problem
-    assert "1010" in result["solved_list"]
+    assert "1010" in result["solved_list"], (
+        "a known solved problem must appear in solved_list"
+    )
diff --git a/tests/crawlers/nit_test.py b/tests/crawlers/nit_test.py
index 862fbe3..81de4ea 100644
--- a/tests/crawlers/nit_test.py
+++ b/tests/crawlers/nit_test.py
@@ -68,12 +68,13 @@ async def test_valid_user(session):
     assert result["submissions"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # solved_list contains unique problems solved on NIT
-    # Note: solved count from page may differ from unique problems in solved_list
-    assert len(result["solved_list"]) > 0
+    assert len(result["solved_list"]) > 0, (
+        "solved_list holds the unique problems solved on NIT, and its length can "
+        "differ from the count the profile page reports"
+    )
     assert len(result["solved_list"]) <= result["solved"]
 
-    # Check for known solved problems (NIT includes problems from other OJs)
-    assert "nit-100" in result["solved_list"]
-    # NIT problem ID 2097 maps to HDU-2181
-    assert "hdu-2181" in result["solved_list"]
+    assert "nit-100" in result["solved_list"], (
+        "NIT lists problems from other judges alongside its own"
+    )
+    assert "hdu-2181" in result["solved_list"], "NIT problem 2097 maps to hdu-2181"
diff --git a/tests/crawlers/nod_test.py b/tests/crawlers/nod_test.py
index 4eaffa2..4989ab2 100644
--- a/tests/crawlers/nod_test.py
+++ b/tests/crawlers/nod_test.py
@@ -36,5 +36,6 @@ async def test_valid_user(session):
     assert result["solved"] > 0
     assert result["submissions"] >= result["solved"]
     assert isinstance(result["solved_list"], list)
-    # 51Nod may have 1 problem outside standard ProblemTables collections
-    assert len(result["solved_list"]) >= result["solved"] - 1
+    assert len(result["solved_list"]) >= result["solved"] - 1, (
+        "51Nod can hold one problem outside the standard ProblemTables collections"
+    )
diff --git a/tests/crawlers/nowcoder_test.py b/tests/crawlers/nowcoder_test.py
index 672a3a4..4ff5a9b 100644
--- a/tests/crawlers/nowcoder_test.py
+++ b/tests/crawlers/nowcoder_test.py
@@ -53,8 +53,10 @@ async def test_valid_user(session):
     assert result["submissions"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # Check that solved_list has the correct length
-    assert len(result["solved_list"]) == result["solved"]
+    assert len(result["solved_list"]) == result["solved"], (
+        "solved_list must hold one entry per solved problem"
+    )
 
-    # Check for known solved problem
-    assert "16632" in result["solved_list"]
+    assert "16632" in result["solved_list"], (
+        "a known solved problem must appear in solved_list"
+    )
diff --git a/tests/crawlers/poj_test.py b/tests/crawlers/poj_test.py
index a7bfb45..91cfaeb 100644
--- a/tests/crawlers/poj_test.py
+++ b/tests/crawlers/poj_test.py
@@ -44,8 +44,10 @@ async def test_valid_user(session):
     assert result["submissions"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # Check that solved_list has the correct length
-    assert len(result["solved_list"]) == result["solved"]
+    assert len(result["solved_list"]) == result["solved"], (
+        "solved_list must hold one entry per solved problem"
+    )
 
-    # Check for known solved problem
-    assert "1001" in result["solved_list"]
+    assert "1001" in result["solved_list"], (
+        "a known solved problem must appear in solved_list"
+    )
diff --git a/tests/crawlers/registry_test.py b/tests/crawlers/registry_test.py
index 3c6a822..a3e38af 100644
--- a/tests/crawlers/registry_test.py
+++ b/tests/crawlers/registry_test.py
@@ -64,6 +64,7 @@ def test_importing_one_crawler_does_not_discover_the_rest():
 def test_accessing_crawlers_discovers_them_all():
     imported = _crawlers_imported_by("from ojhunt.crawlers import crawlers")
 
-    # >=, not ==: _discover() imports every module in the package, and one need
-    # not carry __crawler_meta__ to be imported.
-    assert imported >= len(crawler_registry)
+    assert imported >= len(crawler_registry), (
+        "_discover() imports every module in the package, and a module need not "
+        "carry __crawler_meta__ to be imported — hence >=, not =="
+    )
diff --git a/tests/crawlers/sdutoj_test.py b/tests/crawlers/sdutoj_test.py
index f7d829a..0b6e87d 100644
--- a/tests/crawlers/sdutoj_test.py
+++ b/tests/crawlers/sdutoj_test.py
@@ -43,8 +43,10 @@ async def test_valid_user(session):
     assert result["submissions"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # Check that solved_list has the correct length
-    assert len(result["solved_list"]) == result["solved"]
+    assert len(result["solved_list"]) == result["solved"], (
+        "solved_list must hold one entry per solved problem"
+    )
 
-    # Check for known solved problem
-    assert "1000" in result["solved_list"]
+    assert "1000" in result["solved_list"], (
+        "a known solved problem must appear in solved_list"
+    )
diff --git a/tests/crawlers/timus_test.py b/tests/crawlers/timus_test.py
index e0ba5c2..20a3807 100644
--- a/tests/crawlers/timus_test.py
+++ b/tests/crawlers/timus_test.py
@@ -40,11 +40,13 @@ async def test_valid_user(session):
     assert isinstance(result["solved_list"], list)
 
     assert result["solved"] > 0
-    assert result["submissions"] > 10  # Specific assertion from test.js
+    assert result["submissions"] > 10, "carried over from the original test.js"
     assert result["submissions"] >= result["solved"]
 
-    # Check that solved_list has the correct length
-    assert len(result["solved_list"]) == result["solved"]
+    assert len(result["solved_list"]) == result["solved"], (
+        "solved_list must hold one entry per solved problem"
+    )
 
-    # Check for known solved problem
-    assert "1387" in result["solved_list"]
+    assert "1387" in result["solved_list"], (
+        "a known solved problem must appear in solved_list"
+    )
diff --git a/tests/crawlers/uoj_test.py b/tests/crawlers/uoj_test.py
index 9d73864..b42ef13 100644
--- a/tests/crawlers/uoj_test.py
+++ b/tests/crawlers/uoj_test.py
@@ -43,8 +43,10 @@ async def test_valid_user(session):
     assert result["submissions"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # Check that solved_list has the correct length
-    assert len(result["solved_list"]) == result["solved"]
+    assert len(result["solved_list"]) == result["solved"], (
+        "solved_list must hold one entry per solved problem"
+    )
 
-    # Check for known solved problem
-    assert "30" in result["solved_list"]
+    assert "30" in result["solved_list"], (
+        "a known solved problem must appear in solved_list"
+    )
diff --git a/tests/crawlers/uva_test.py b/tests/crawlers/uva_test.py
index ed0a63a..f6e9be8 100644
--- a/tests/crawlers/uva_test.py
+++ b/tests/crawlers/uva_test.py
@@ -43,8 +43,10 @@ async def test_valid_user(session):
     assert result["submissions"] > 0
     assert result["submissions"] >= result["solved"]
 
-    # Check that solved_list has the correct length
-    assert len(result["solved_list"]) == result["solved"]
+    assert len(result["solved_list"]) == result["solved"], (
+        "solved_list must hold one entry per solved problem"
+    )
 
-    # Check that solved_list contains valid problem labels
-    assert all(isinstance(p, str) for p in result["solved_list"])
+    assert all(isinstance(p, str) for p in result["solved_list"]), (
+        "every solved_list entry must be a problem label string"
+    )
diff --git a/tests/crawlers/vnoj_test.py b/tests/crawlers/vnoj_test.py
index e911e50..5282719 100644
--- a/tests/crawlers/vnoj_test.py
+++ b/tests/crawlers/vnoj_test.py
@@ -37,8 +37,9 @@ async def test_valid_user(session):
 
     assert isinstance(result["solved"], int)
     assert result["submissions"] == result["solved"], "no total published (ADR 0015)"
-    # VNOJ's API and per-user solved-list page are disabled; only the profile
-    # page count remains, so solved_list is unavailable.
-    assert result["solved_list"] is None
+    assert result["solved_list"] is None, (
+        "VNOJ disabled its API and per-user solved-list page; only the profile "
+        "page count remains"
+    )
 
     assert result["solved"] > 0
diff --git a/tests/e2e/test_pdf_workflow.py b/tests/e2e/test_pdf_workflow.py
index a229e49..42dfc9b 100644
--- a/tests/e2e/test_pdf_workflow.py
+++ b/tests/e2e/test_pdf_workflow.py
@@ -376,9 +376,8 @@ def test_upload_historical_pdf_entries_preserved_in_new_download(
     assert "2020-01-01" in keys, f"Old history entry missing; got keys: {keys}"
     assert "2020-01-02" in keys
     assert "2020-01-03" in keys
-    # And at least one entry from ~2026 (today) was added
     assert any(k.startswith("202") and k > "2020" for k in keys), (
-        f"No recent entry found; keys: {keys}"
+        f"today's run must add an entry of its own; keys: {keys}"
     )
 
 
diff --git a/tests/lint/comment_above_assert_test.py b/tests/lint/comment_above_assert_test.py
new file mode 100644
index 0000000..42141d7
--- /dev/null
+++ b/tests/lint/comment_above_assert_test.py
@@ -0,0 +1,218 @@
+"""Tests for the comment-above-assert lint rule (lint/rules/comment_above_assert.py).
+
+The edge cases are the point of this file. A trailing comment and an own-line
+comment are indistinguishable in the parse tree, so every case below pins which
+line the rule blames — the earlier YAML version of this rule reported three
+different outcomes for the same violation depending on what followed it.
+"""
+
+import importlib.util
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).parents[2]
+RULE_PATH = REPO_ROOT / "lint" / "rules" / "comment_above_assert.py"
+
+
+def _rule():
+    """Import the rule, which lives outside the package (mirrors docs_test.py)."""
+    spec = importlib.util.spec_from_file_location("comment_above_assert", RULE_PATH)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+rule = _rule()
+
+
+def _lines(source: str) -> list[int]:
+    return [f.line for f in rule.find_violations(source, Path("probe.py"))]
+
+
+# ---------------------------------------------------------------------------
+# Own-line comment above an assert — the case the rule exists for
+# ---------------------------------------------------------------------------
+
+
+def test_own_line_comment_mid_body():
+    source = """
+def test_x():
+    result = query()
+    # the crawler reports only an AC count
+    assert result["submissions"] == result["solved"]
+"""
+    assert _lines(source) == [5], "the assert below an own-line comment is flagged"
+
+
+def test_own_line_comment_as_first_statement():
+    source = """
+def test_x():
+    # the crawler reports only an AC count
+    assert result["submissions"] == result["solved"]
+"""
+    assert _lines(source) == [4], (
+        "a comment before the first statement attaches to the def, not the body — "
+        "the rule must still reach the assert inside the block"
+    )
+
+
+def test_own_line_comment_inside_a_method():
+    source = """
+class TestThing:
+    def test_x(self):
+        # explanation
+        assert value == 1
+"""
+    assert _lines(source) == [5], "nesting depth must not matter"
+
+
+def test_comment_block_reports_once():
+    source = """
+def test_x():
+    imported = discover()
+    # first line of the explanation
+    # second line of the explanation
+    assert imported >= len(registry)
+"""
+    assert _lines(source) == [6], "a multi-line comment block yields one finding"
+
+
+def test_flagged_even_when_the_assert_has_a_message():
+    source = """
+def test_x():
+    value = compute()
+    # this says something the message does not
+    assert value == 1, "value must be one"
+"""
+    assert _lines(source) == [5], "a message does not excuse a comment beside it"
+
+
+# ---------------------------------------------------------------------------
+# Trailing comments — reported on their own line, never on the one below
+# ---------------------------------------------------------------------------
+
+
+def test_trailing_comment_on_an_assert_is_blamed_on_that_assert():
+    source = """
+def test_x():
+    result = query()
+    assert result["solved"] > 0  # the judge under-reports by one
+    assert result["submissions"] > 0
+"""
+    assert _lines(source) == [4], (
+        "line 4 carries the comment; line 5 is innocent and must not be blamed"
+    )
+
+
+@pytest.mark.parametrize(
+    ("what_follows", "description"),
+    [
+        ("", "nothing — the assert ends the body"),
+        ("    cleanup()\n", "a statement that is not an assert"),
+        ("    assert other > 0\n", "another assert"),
+    ],
+)
+def test_trailing_comment_is_caught_whatever_follows(what_follows, description):
+    source = f"""
+def test_x():
+    result = query()
+    assert result["solved"] > 0  # the judge under-reports by one
+{what_follows}"""
+    assert _lines(source) == [4], f"must be caught when followed by {description}"
+
+
+# ---------------------------------------------------------------------------
+# Cases that must stay silent
+# ---------------------------------------------------------------------------
+
+
+def test_trailing_comment_on_a_non_assert_is_ignored():
+    source = """
+def test_x():
+    reset_env()
+    config = load_config()  # defaults come from .env
+    assert config.debug is False
+"""
+    assert _lines(source) == [], (
+        "the comment explains the assignment it sits on, not the assert below it"
+    )
+
+
+def test_comment_above_a_non_assert_is_ignored():
+    source = """
+def test_x():
+    # build the client once
+    client = TestClient(app)
+    assert client is not None
+"""
+    assert _lines(source) == [], "the comment explains the statement it sits above"
+
+
+def test_assert_with_a_message_and_no_comment_is_ignored():
+    source = """
+def test_x():
+    result = query()
+    assert result["solved"] > 0, "the test user has solved something"
+"""
+    assert _lines(source) == []
+
+
+@pytest.mark.parametrize(
+    "pragma",
+    ["# type: ignore[arg-type]", "# noqa: E501", "# fmt: skip", "# NOQA"],
+)
+def test_tool_pragmas_are_ignored(pragma):
+    source = f"""
+def test_x():
+    result = query()
+    assert isinstance(result, Mapping)  {pragma}
+"""
+    assert _lines(source) == [], (
+        f"{pragma} is addressed to another tool, so it cannot move into the message"
+    )
+
+
+def test_trailing_comment_at_the_end_of_a_body_is_ignored():
+    source = """
+def test_x():
+    assert value == 1
+    # a note that trails the whole body
+"""
+    assert _lines(source) == [], "no statement follows, so nothing is explained"
+
+
+# ---------------------------------------------------------------------------
+# Scope — the hook hands the rule whatever file just changed
+# ---------------------------------------------------------------------------
+
+
+def test_scope_covers_this_test_file():
+    covered = {path.resolve() for path in rule.scoped_files()}
+    assert Path(__file__).resolve() in covered, (
+        "a named file inside SCOPE must reach the scanner"
+    )
+
+
+def test_a_named_file_outside_the_scope_is_skipped(tmp_path):
+    stray = tmp_path / "stray_test.py"
+    stray.write_text(
+        "def test_x():\n    # explanation\n    assert value == 1\n", encoding="utf-8"
+    )
+    assert rule.find_violations(stray.read_text(encoding="utf-8"), stray), (
+        "the probe must violate the rule, or the next assertion proves nothing"
+    )
+    assert rule.main([str(stray)]) == 0, (
+        "only SCOPE decides what the rule covers — otherwise the hook blocks on "
+        "files ./doit.sh lint never looks at"
+    )
+
+
+# ---------------------------------------------------------------------------
+# The rule holds over the repository it guards
+# ---------------------------------------------------------------------------
+
+
+def test_repository_is_clean():
+    findings = rule.scan(sorted(REPO_ROOT.glob(rule.SCOPE)))
+    assert findings == [], "\n".join(str(f) for f in findings)
diff --git a/tests/lint/rules_are_tested_test.py b/tests/lint/rules_are_tested_test.py
new file mode 100644
index 0000000..33492d3
--- /dev/null
+++ b/tests/lint/rules_are_tested_test.py
@@ -0,0 +1,41 @@
+"""Every lint rule must ship with its own tests.
+
+Discovered from the directory rather than listed here: a hardcoded list would go
+stale on exactly the rule nobody remembered to add to it.
+"""
+
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).parents[2]
+RULES_DIR = REPO_ROOT / "lint" / "rules"
+YAML_TESTS_DIR = REPO_ROOT / "lint" / "rule-tests"
+PYTHON_TESTS_DIR = Path(__file__).parent
+
+
+def test_every_python_rule_has_a_pytest_file():
+    missing = [
+        rule.name
+        for rule in sorted(RULES_DIR.glob("*.py"))
+        if not (PYTHON_TESTS_DIR / f"{rule.stem}_test.py").exists()
+    ]
+    assert not missing, (
+        f"{missing} have no tests — add tests/lint/<rule>_test.py covering which "
+        "line each case is blamed on"
+    )
+
+
+def test_every_yaml_rule_has_an_ast_grep_test_file():
+    missing = [
+        rule.name
+        for rule in sorted(RULES_DIR.glob("*.yml"))
+        if not (YAML_TESTS_DIR / f"{rule.stem}-test.yml").exists()
+    ]
+    assert not missing, (
+        f"{missing} have no tests — add lint/rule-tests/<rule>-test.yml with valid "
+        "and invalid cases, then run ./doit.sh lint-rules"
+    )
+
+
+def test_at_least_one_rule_exists():
+    rules = list(RULES_DIR.glob("*.py")) + list(RULES_DIR.glob("*.yml"))
+    assert rules, "lint/rules/ is empty — did a rule get deleted by accident?"
diff --git a/tests/web/api_test.py b/tests/web/api_test.py
index d6e4d7d..12475cf 100644
--- a/tests/web/api_test.py
+++ b/tests/web/api_test.py
@@ -130,9 +130,10 @@ def test_to_model_unknown_crawler():
     )
     core = dto.to_model()
 
-    # Unknown crawler falls back to NullCrawler; result is still considered
-    # successful so its problems are included in merge (prefixed with crawler name)
-    assert core.success is True
+    assert core.success is True, (
+        "an unknown crawler falls back to NullCrawler but still counts as a success, "
+        "so its problems reach the merge under a crawler-name prefix"
+    )
     assert isinstance(core.crawler, NullCrawler)
     assert core.solved_list == ["1A"]
 
@@ -185,11 +186,11 @@ def test_list_crawlers_defaults_to_waiting():
     data = response.json()["data"]
     assert "codeforces" in data
     cf = data["codeforces"]
-    # Existing metadata fields are preserved alongside the new status fields.
-    assert "title" in cf
+    assert "title" in cf, "existing metadata survives alongside the status fields"
     assert "isAggregator" in cf
-    # Checker hasn't run under TestClient → default status, no error.
-    assert cf["status"] == "waiting"
+    assert cf["status"] == "waiting", (
+        "the checker does not run under TestClient, so status stays at its default"
+    )
     assert cf["statusError"] is None
 
 
diff --git a/tests/web/pages_test.py b/tests/web/pages_test.py
index aee4575..72a85f5 100644
--- a/tests/web/pages_test.py
+++ b/tests/web/pages_test.py
@@ -4,9 +4,13 @@
 TestClient and mock export_user_pdf where needed.
 """
 
+import re
+
+import pytest
 from fastapi.testclient import TestClient
 
 from ojhunt.web.app import app
+from ojhunt.web.pages import router as pages_router
 from ojhunt.web.pdf import (
     HistoryEntry,
     PdfQueryItem,
@@ -246,8 +250,9 @@ def test_security_headers_present_on_page():
     assert "default-src 'self'" in csp
     assert "frame-ancestors 'none'" in csp
     assert "upgrade-insecure-requests" in csp
-    # ReDoc spawns a blob: web worker; the worker-src directive must allow it.
-    assert "worker-src 'self' blob:" in csp
+    assert "worker-src 'self' blob:" in csp, (
+        "ReDoc spawns a blob: web worker, so worker-src must allow it"
+    )
 
 
 # ---------------------------------------------------------------------------
@@ -277,3 +282,137 @@ def test_docs_vendored_assets_are_served():
         "/assets/redoc.standalone-2.5.3.js",
     ):
         assert client.get(asset).status_code == 200, asset
+
+
+# ---------------------------------------------------------------------------
+# Search-engine metadata (base.html.jinja + render_page)
+# ---------------------------------------------------------------------------
+
+MAX_DESCRIPTION_LENGTH = 160
+
+STATIC_PAGE_PATHS = sorted(
+    route.path
+    for route in pages_router.routes
+    if "GET" in getattr(route, "methods", set()) and "{" not in route.path
+)
+
+INDEXED_PAGES = ["/", "/about", "/crawlers", "/pdf/legacy", "/pdf/merge"]
+
+
+def _meta_content(html: str, attr: str, name: str) -> str | None:
+    match = re.search(
+        rf'<meta {attr}="{re.escape(name)}" content="([^"]*)"',
+        html,
+    )
+    return match.group(1) if match else None
+
+
+def _description(html: str) -> str | None:
+    return _meta_content(html, "name", "description")
+
+
+def _canonical(html: str) -> str | None:
+    match = re.search(r'<link rel="canonical" href="([^"]*)"', html)
+    return match.group(1) if match else None
+
+
+def _html_response(path: str):
+    response = client.get(path)
+    is_html = response.status_code == 200 and "text/html" in response.headers.get(
+        "content-type", ""
+    )
+    return response if is_html else None
+
+
+def test_no_page_route_takes_path_parameters():
+    templated = [route.path for route in pages_router.routes if "{" in route.path]
+    assert not templated, (
+        f"{templated} take path parameters, and the metadata checks below only "
+        "reach static paths — extend them to cover dynamic pages"
+    )
+
+
+def test_discovery_found_the_known_pages():
+    assert set(INDEXED_PAGES) <= set(STATIC_PAGE_PATHS), (
+        "route discovery missed a page listed in sitemap.xml.jinja"
+    )
+
+
+@pytest.mark.parametrize("path", STATIC_PAGE_PATHS)
+def test_page_has_a_description(path):
+    response = _html_response(path)
+    if response is None:
+        pytest.skip(f"{path} does not answer with HTML")
+    description = _description(response.text)
+    assert description, (
+        f"{path} has no meta description, so a search engine writes its own "
+        "snippet out of whatever text comes first on the page"
+    )
+    assert len(description) <= MAX_DESCRIPTION_LENGTH, (
+        f"{path} description is {len(description)} characters — "
+        f"a search engine truncates it at {MAX_DESCRIPTION_LENGTH}"
+    )
+
+
+def test_home_and_about_share_the_project_summary():
+    home = _description(client.get("/").text)
+    about = _description(client.get("/about").text)
+    assert home == about, "both pages describe the project, not one page of it"
+    assert "Online Judge" in home, "the summary must name what the project queries"
+
+
+def test_other_pages_describe_themselves():
+    generic = _description(client.get("/").text)
+    specific = {
+        path: _description(client.get(path).text)
+        for path in ("/crawlers", "/pdf/legacy", "/pdf/merge")
+    }
+    for path, description in specific.items():
+        assert description != generic, f"{path} reuses the generic description"
+    assert len(set(specific.values())) == len(specific), "descriptions are not unique"
+
+
+@pytest.mark.parametrize("path", STATIC_PAGE_PATHS)
+def test_page_either_claims_a_canonical_url_or_says_noindex(path):
+    response = _html_response(path)
+    if response is None:
+        pytest.skip(f"{path} does not answer with HTML")
+    html = response.text
+    if _meta_content(html, "name", "robots") == "noindex":
+        assert _canonical(html) is None, f"{path} is noindex but claims a canonical URL"
+        return
+    assert _canonical(html) == f"http://testserver{path}", (
+        f"{path} is indexable, so it must be canonical to itself"
+    )
+    assert _meta_content(html, "property", "og:url") == _canonical(html), (
+        f"{path} disagrees with itself: og:url differs from the canonical URL"
+    )
+
+
+def test_home_page_has_open_graph_tags():
+    html = client.get("/").text
+    assert _meta_content(html, "property", "og:type") == "website"
+    assert _meta_content(html, "property", "og:site_name") == "OJHunt Lite"
+    assert _meta_content(html, "property", "og:title") == "OJHunt Lite"
+    assert _meta_content(html, "property", "og:description") == _description(html)
+    assert (
+        _meta_content(html, "property", "og:image")
+        == "http://testserver/assets/logo.png"
+    )
+    assert _meta_content(html, "name", "twitter:card") == "summary"
+
+
+def test_crawlers_page_description_counts_the_registry():
+    from ojhunt.crawlers import crawlers as registry
+
+    description = _description(client.get("/crawlers").text)
+    assert f"All {len(registry)} online judges" in description
+
+
+@pytest.mark.parametrize("path", ["/admin", "/.env", "/no-such-page"])
+def test_junk_page_is_excluded_from_the_index(path):
+    html = client.get(path).text
+    assert _meta_content(html, "name", "robots") == "noindex", (
+        f"{path} answers 200, so without noindex a search engine can index it"
+    )
+    assert _canonical(html) is None, f"{path} must not claim a canonical URL"
diff --git a/tests/web/pdf_test.py b/tests/web/pdf_test.py
index 11ffa1a..246d165 100644
--- a/tests/web/pdf_test.py
+++ b/tests/web/pdf_test.py
@@ -306,8 +306,9 @@ def test_api_generate_merges_previous_pdf():
 
     r3 = _extract(pdf2)
     assert r3.status_code == 200
-    # report_date should be the most recent entry (date from r2 since it ran after r1)
-    assert r3.json()["report_date"] is not None
+    assert r3.json()["report_date"] is not None, (
+        "report_date carries the most recent entry, which is r2 — it ran after r1"
+    )
     # Both day keys must appear in embedded history
     extracted = extract_data(pdf2)
     keys = {e.key for e in extracted.history}
diff --git a/uv.lock b/uv.lock
index 3131277..ed44dc4 100644
--- a/uv.lock
+++ b/uv.lock
@@ -160,6 +160,47 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/38/0e/27be9fdef66e72d64c0cdc3cc2823101b80585f8119b5c112c2e8f5f7dab/anyio-4.12.1-py3-none-any.whl", hash = "sha256:d405828884fc140aa80a3c667b8beed277f1dfedec42ba031bd6ac3db606ab6c", size = 113592, upload-time = "2026-01-06T11:45:19.497Z" },
 ]
 
+[[package]]
+name = "ast-grep-cli"
+version = "0.45.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/bd/31/e202db9b63bb2851f48d29c01aa27b74c5b7b36bc6c158f80f6443a7dbfa/ast_grep_cli-0.45.1.tar.gz", hash = "sha256:3b214f39554cb6fd51d0fd441eab9427c7dd8bfb12dbff5ef7618369c6a22628", size = 279952, upload-time = "2026-08-07T15:25:10.762Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/63/2f/5db21c7c3c61f758f0cde8ebbc60e5876d026857ca5a1ca41acb9607b18b/ast_grep_cli-0.45.1-py3-none-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl", hash = "sha256:3536a040aed9d95b29af27d2eea0c831a48ee151afa8de2c6a842b9fc75e8c87", size = 16028194, upload-time = "2026-08-07T15:24:51.186Z" },
+    { url = "https://files.pythonhosted.org/packages/86/52/4cd380e4fc56f8fc5e9d6526b6c353c7802d96b78624ecb49dca6cfe6a86/ast_grep_cli-0.45.1-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:befa0add772663a012d42e22bb28483ecb8558d66634fa364efe09a1c7187542", size = 8007620, upload-time = "2026-08-07T15:24:54.375Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/f8/2bb3e74a50e75b41a34d8f6f8e6d42867b088147a15fb7e73f5cb94d7f7f/ast_grep_cli-0.45.1-py3-none-manylinux_2_28_aarch64.whl", hash = "sha256:80caab89daefa0ddaf69f59f7838e6ff4480fd35daf6ea273fa3055506e992df", size = 7864976, upload-time = "2026-08-07T15:24:56.366Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/3e/193f347a7add7ba413a0f4169cc8185bd58ba0477e6947a683f4887c4872/ast_grep_cli-0.45.1-py3-none-manylinux_2_28_x86_64.whl", hash = "sha256:497810f387e9ab0624f72dd300557fb25a2a49b0429c71472e5d08180f16bdbc", size = 8166938, upload-time = "2026-08-07T15:24:58.593Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/f1/0d04cd5e0a5bdd1c1f1c8f78ec1efab30ad1d585bda207657d125e0613ef/ast_grep_cli-0.45.1-py3-none-win32.whl", hash = "sha256:bfd8aceeb6d6e8623a18a0804d22f9cdc67ad84d7dd1f03c3e8b6a33990189e3", size = 15198061, upload-time = "2026-08-07T15:25:02.014Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/96/5544e348c00381c7526462332dcb56ed1129de3402b0610a100fc683db84/ast_grep_cli-0.45.1-py3-none-win_amd64.whl", hash = "sha256:b3bbcdeb49db5a7942c4687c117c478be8e5eeb4bcfa79851d4154965f6c7402", size = 16177239, upload-time = "2026-08-07T15:25:05.528Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/52/d2644a91e78e876af197a05ff7bd499d2e0c615935f31756ab432cd157df/ast_grep_cli-0.45.1-py3-none-win_arm64.whl", hash = "sha256:0a945ef6495c2ce2e09001e25b81ad14ccbe7afe446467c4d912ac06271c6c13", size = 15566175, upload-time = "2026-08-07T15:25:08.702Z" },
+]
+
+[[package]]
+name = "ast-grep-py"
+version = "0.45.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/29/81/fa716e61d5be8acc7d1da0125cee2e0726307e4289b6410c6a9581d4f703/ast_grep_py-0.45.1.tar.gz", hash = "sha256:444f09a3928d966ee779b1ab9fbce881d4fa9a276c6e9fac6bb1746d2efc5714", size = 155677, upload-time = "2026-08-07T15:28:58.878Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/28/b7/c4f4bb38175eb78fc9f32ce103e2b42d387b6474d846890e1af01c011756/ast_grep_py-0.45.1-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:012b14be02f2683cc63645670359309ab6feed0e1876cc0901f7f6a72f7a8993", size = 5356973, upload-time = "2026-08-07T15:28:27.761Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/2a/b4d68dd42ed47dc26d6a875e23ff4ebf587bb3418ad282434cc5c8669b70/ast_grep_py-0.45.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:9caa33905cb352a62f5178e41c279f6cbe7fbfd8961ca5d76233d36b58f7e041", size = 5531320, upload-time = "2026-08-07T15:28:29.794Z" },
+    { url = "https://files.pythonhosted.org/packages/0d/2a/a55aff6091b75b9bfc9d2cfad6d5dbc17776f4fc3cc671dc8a85a27cacba/ast_grep_py-0.45.1-cp312-cp312-manylinux_2_28_aarch64.whl", hash = "sha256:dc5a35f1bc86daa3d1c79d322e9ec4d4380b6c72c141ce43879ee21856cea77c", size = 5353991, upload-time = "2026-08-07T15:28:31.664Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/00/2db8135f4826d55f3d8efa544521b73c16c176230b4802dcd0c9935cb572/ast_grep_py-0.45.1-cp312-cp312-manylinux_2_28_x86_64.whl", hash = "sha256:b018c762c1fa913d16e3396f06eb5c5f5f48728bd331cdc591880e62be3eb1ba", size = 5468480, upload-time = "2026-08-07T15:28:33.409Z" },
+    { url = "https://files.pythonhosted.org/packages/71/1e/4ee446c30c130e28589a553f4162f343f9c5256e149b16de4bb52465d3ef/ast_grep_py-0.45.1-cp312-cp312-win32.whl", hash = "sha256:357ff96e75fcc241c6f36a30a7178fbaa4c45e320a8cfa69d2dc87c81d148b06", size = 5076686, upload-time = "2026-08-07T15:28:34.93Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/d9/3f99c33b927192a18faca1ecbc6fd6588c4f6bb18c9c114d2bfb4cbd591d/ast_grep_py-0.45.1-cp312-cp312-win_amd64.whl", hash = "sha256:57fafff917a6f26c60d2e53faee7cbfaba9ccc633fdd69eb31a85abbedebf7cb", size = 5208597, upload-time = "2026-08-07T15:28:36.488Z" },
+    { url = "https://files.pythonhosted.org/packages/a4/1b/d7cfef152cd747306d2760a90b24f4913e07b7c84bd308db3f5268e7cec6/ast_grep_py-0.45.1-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:515e0b1d3f1474b0ee136068f343eb500e38ce055652114059c72a5f362998e2", size = 5360319, upload-time = "2026-08-07T15:28:38.075Z" },
+    { url = "https://files.pythonhosted.org/packages/3b/8a/c9b25e40648d6f21c4717d169d566cc4cb44fc215fa18f702b0885648992/ast_grep_py-0.45.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:35b796de0e8c9bc9454b1ef24f07c86bd182e4f80afc66d0bcd188fd88acd20b", size = 5531479, upload-time = "2026-08-07T15:28:39.869Z" },
+    { url = "https://files.pythonhosted.org/packages/c6/08/bc2179ce647429406a3f48cba7d1b93b8b0dc35ac0209af1820d57f77728/ast_grep_py-0.45.1-cp313-cp313-manylinux_2_28_aarch64.whl", hash = "sha256:955d00b7573738d29aa8f1ec889cec87d5802abc0e3b7fd4b2cfd95c066117cf", size = 5349958, upload-time = "2026-08-07T15:28:41.515Z" },
+    { url = "https://files.pythonhosted.org/packages/53/a1/96857476280ce36f21950856eb57def7b92c95583333106003262f7f93cb/ast_grep_py-0.45.1-cp313-cp313-manylinux_2_28_x86_64.whl", hash = "sha256:841ac568f9f4a94155e43e661367e7c55788c599683bb674ab5fe0b5dfcdb977", size = 5467676, upload-time = "2026-08-07T15:28:43.248Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/ea/c2951e0fd740293c82613f6956d3f9dad81eab1d16cdb3da8543c579f994/ast_grep_py-0.45.1-cp313-cp313-win32.whl", hash = "sha256:4c8581b059026ff4c4249751054a5823175db7f303f9a352f69af017177332b4", size = 5070691, upload-time = "2026-08-07T15:28:45.083Z" },
+    { url = "https://files.pythonhosted.org/packages/35/59/3c9a915405a9aef9bf90b706396bf0393a1e1177ab725b90654b0d6fd921/ast_grep_py-0.45.1-cp313-cp313-win_amd64.whl", hash = "sha256:0bfc05f252e99455296bbad4d87043973052d5c29ff5c08b1f7bbf80e81cad57", size = 5207779, upload-time = "2026-08-07T15:28:46.696Z" },
+    { url = "https://files.pythonhosted.org/packages/e6/19/3157219288b8135cfaeb51cb5a8a3d26cab3adc7484ac13be6aeb0d41915/ast_grep_py-0.45.1-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:48cc4d872ea5f7d60c55e7d19fc795d4e8ede156f675e87245c87efa94889993", size = 5358480, upload-time = "2026-08-07T15:28:48.308Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/c1/af430c2cc01e8f527da258f02e8b06fd7af0d8a9ef8cb181b99bd36049d8/ast_grep_py-0.45.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:0f296c015d618ab41840b4e08db5ba3618ed4e1739f7797002d5b00c64ad2aae", size = 5531104, upload-time = "2026-08-07T15:28:49.933Z" },
+    { url = "https://files.pythonhosted.org/packages/49/bd/4b6ababea21ec5d4a56c86b56959849f8cd5bdfbdc839279521c2be14a5c/ast_grep_py-0.45.1-cp314-cp314-manylinux_2_28_aarch64.whl", hash = "sha256:2534c6d8035fa2397fa7abe1b0b7c9c8ad6a69b57b0316828da2f5f92b41411c", size = 5349994, upload-time = "2026-08-07T15:28:51.601Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/f8/d603657858079fe9c856a23ce543da799c6e265d86e8b7731e6bd8c22531/ast_grep_py-0.45.1-cp314-cp314-manylinux_2_28_x86_64.whl", hash = "sha256:7b1ac42d8872059abe794fd0005a3ba6ebae72c2db72422765a376c56bdaac35", size = 5468660, upload-time = "2026-08-07T15:28:53.773Z" },
+    { url = "https://files.pythonhosted.org/packages/39/fd/26ed2b048fcdd1d81f6da21aa152215e03b390303b0c70c2b96e4108da46/ast_grep_py-0.45.1-cp314-cp314-win32.whl", hash = "sha256:c1c2cf472ef657e6aa3a57f1a7d824d790320a97d0c1245a5b8b060288d1f690", size = 5074686, upload-time = "2026-08-07T15:28:55.405Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/26/b34feb7f35f6d13e5244f67f526b87946e107d9d2ca7b534e927d06bf2b2/ast_grep_py-0.45.1-cp314-cp314-win_amd64.whl", hash = "sha256:00d89d7ae157f18319f897b9779cc449b2e97be4ccb7fc489ed6e41f6436b27f", size = 5207281, upload-time = "2026-08-07T15:28:57.077Z" },
+]
+
 [[package]]
 name = "attrs"
 version = "25.4.0"
@@ -1226,6 +1267,8 @@ dependencies = [
 
 [package.dev-dependencies]
 dev = [
+    { name = "ast-grep-cli" },
+    { name = "ast-grep-py" },
     { name = "hatchling" },
     { name = "pytest" },
     { name = "pytest-asyncio" },
@@ -1251,6 +1294,8 @@ requires-dist = [
 
 [package.metadata.requires-dev]
 dev = [
+    { name = "ast-grep-cli", specifier = ">=0.45.1" },
+    { name = "ast-grep-py", specifier = ">=0.45.1" },
     { name = "hatchling", specifier = ">=1.29.0" },
     { name = "pytest", specifier = ">=9.0.2" },
     { name = "pytest-asyncio", specifier = ">=1.3.0" },