Reposition awesome-python as a shortlist, not a catalog

.claude/skills/audit-the-list/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: audit-the-list
+description: Audit README.md sections against the shortlist rules — re-verify every entry's verdict with live data, promote or demote challengers, restructure oversized use cases, prune, and evaluate proposed additions. Fire when the maintainer asks to audit, sweep, prune, re-check, or maintain sections, or asks whether an entry (or a proposed one) deserves its slot.
+argument-hint: [all or specific sections]
+---
+
+# Audit the list
+
+An Audit re-runs the admission test over live sections of README.md: every entry re-verified against current data, tiers reassessed, structure reconsidered, then the maintainer adjudicates and the result is committed. The rules live in CONTRIBUTING.md (Admission, Evidence, Entry Ordering) and CONTEXT.md (vocabulary) — this skill is the process that applies them, not a second copy of them. Entry changes land only on the maintainer's explicit go.
+
+## 1. Scope
+
+Resolve the scope from the arguments. Named sections mean exactly those, whether or not they were audited before (a re-run is how a past verdict gets rechecked). `all` is ambiguous — `AskUserQuestion` whether it means every section or only never-audited ones; prior audits are recorded in git history (`git log --oneline --grep="sweep\|audit"`). With no arguments, AskUserQuestion listing the never-audited Thematic Groups. Batch the work one Thematic Group per sitting. Done when the section list is settled.
+
+## 2. Evidence
+
+Fetch live evidence for every entry in scope before judging anything (CLAUDE.md verification rule):
+
+- **Downloads/month**: `cd website && UV_PYTHON=3.13 uv run python fetch_pypi_downloads_via_clickpy.py` — free keyless ClickPy sweep of the full README, sole writer of `data/pypi_downloads.tsv` (rewritten from scratch each run; header row, every row stamped with its `fetched_at` date). A cache whose `fetched_at` is within the last 7 days is current enough for verdicts — skip the sweep; older than that, re-run it (costs ~1s). Cross-checks print to stdout, take explicit names, and never touch the cache: `fetch_pypi_downloads_via_bigquery.py <name> ...` (canonical source, maintainer's own GCP account, `--dry-run` first — the docstring carries the cost constraints; full-README sweeps exceed the free tier, keep name lists small), `fetch_pypi_downloads_via_pepy.py <name> ...` (needs `PEPY_TECH_API_KEY` in repo-root `.env`, throttled to 5 requests/minute), or `https://pypistats.org/api/packages/{name}/recent` paced 8s or slower. pypistats excludes mirror/CI traffic; ClickPy, BigQuery, and pepy include it — never mix sources within one comparison.
+- **Repo state**: archived flag, last push, created date, stars, description — `gh api repos/{owner}/{repo}`, GitLab API for GitLab-hosted projects.
+- **PyPI metadata** (`https://pypi.org/pypi/{name}/json`) wherever a name might not be the canonical package — ownership collisions and wrong display names surface here. Wrong-package cache rows are common: the sweep looks up README display names, so when the display name differs from the canonical package, the row silently measures an unrelated squatter or a dead predecessor. When a famous entry shows a count that looks off (too small, or absurdly round), verify identity before citing it, and fetch the canonical package's count via pepy.
+
+Done when every entry in scope has downloads (or a stated no-signal reason), repo state, and a confirmed PyPI name.
+
+## 3. Verdicts
+
+Draft a verdict and reason for every entry, restructure before cap: decide Splits, mints, and re-homes first — cutting before restructuring destroys entries — then apply the cap tier by tier, including promotions and demotions between obvious choice and challenger. Ground every reason in the fetched evidence; label anything unverifiable as a judgment call. Where fresh evidence contradicts the standing verdict, say so in the reason instead of silently keeping the seed.
+
+## 4. Review and go
+
+Run the `preview-verdicts` skill: it generates the interactive review page and defines how the maintainer's feedback JSON comes back and gets processed. Their verdicts are final. Before touching README.md, surface what the feedback implies but does not decide — cap overflows, homeless entries after a Split, tier for a tierless flip — as named assumptions or questions, then get an explicit go.
+
+## 5. Execute
+
+One commit per section: body lists each removal with its reason and downloads figure; restructures, tier moves, and reorders ride the same commit. Format-only outcomes (no removals) are a single style commit. `UV_PYTHON=3.13 make test` before every commit, `UV_PYTHON=3.13 make build` after the last one. Generic commit helpers tend to split a section audit into structural and per-subcategory commits — if that happens, squash back to one commit per section. Done when the tree is clean, tests passed before each commit, and the build count reconciles with the adjudicated changes.
+
+## 6. Record
+
+A conclusion that outlives the sitting goes into the repo before the audit ends: admission or evidence rules into CONTRIBUTING.md, repo process and environment facts into CLAUDE.md and AGENTS.md (kept in sync), vocabulary into CONTEXT.md. Done when nothing the next audit needs is stranded in conversation.

.claude/skills/preview-verdicts/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: preview-verdicts
+description: Generate the interactive keep/drop verdict preview (HTML page with per-row feedback controls) whenever a prune sweep, batch entry edit, or restructure needs maintainer review before touching README.md — and process the feedback JSON the maintainer pastes back.
+---
+
+# Verdict preview
+
+Maintainer review happens through an interactive HTML page: one row per entry with your seeded verdict and reason, a Keep/Drop toggle and a reason field for the maintainer, and a **Copy feedback** button that exports only changed or commented rows as JSON. Generate the page, wait for the pasted JSON, then apply it. Entry changes land in README.md only after the review — and only on an explicit go.
+
+## Generate the preview
+
+1. Build the `DATA` array. A group is `[section, subcategory, rows]`; a row is `[entry, url, downloads, verdict, reason]`.
+   - `subcategory` may carry a note after ` — ` (rendered muted): use it for proposed splits, re-homes, or anything the maintainer should weigh for the whole group.
+   - `downloads` is PyPI last-month as a comma-formatted string; use `—` when no signal exists (e.g. agent skill packs), `stdlib` for standard-library modules, `fetch failed` when the lookup failed. State the fetch date in the sub-header.
+   - `verdict` is `keep` or `drop`, seeded from the current adjudication or dry-run.
+   - `reason` is plain language the maintainer reads cold — no invented shorthand. When fresh evidence contradicts the seeded verdict (a big download count on a drop, a dead repo on a keep), say so in that row's reason instead of silently changing the seed.
+2. Copy `template.html` (sibling of this file) and replace the placeholders: `__TITLE__` (page title), `__SUB__` (sub-header: scope, seed provenance, fetch date, and the standing instruction to flip/comment then Copy feedback), `__KEY__` (localStorage key), `__DATA__` (the array). `__KEY__` must be unique per review — slug plus date, e.g. `awesome-python-science-2026-09-01` — because saved state under a reused key bleeds a previous review's flips into rows with the same section and entry name.
+3. Write the page to `tmp/awesome-python-<slug>-preview.html` in the repo root (git-ignored; create the directory if needed), `open` it, and tell the maintainer the path and the return path: flip or comment rows (they highlight yellow), press **Copy feedback**, paste the JSON into the chat. Done when the page is open and the return path is stated.
+
+## Process the pasted feedback
+
+Each JSON row is `{section, subcategory, entry, my_verdict, your_verdict, reason}`. The maintainer's verdict is final — apply it, never re-argue it. An empty reason means the verdict stands unexplained; that is enough.
+
+Before executing, surface anything the flips imply that the maintainer has not decided: a use case pushed past its cap, an entry left homeless by a proposed split, a request that is already satisfied (a no-op). Ask, then execute on their go. Done when every pasted row is either applied or surfaced back — none silently dropped.

.claude/skills/preview-verdicts/template.html

@@ -0,0 +1,160 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>__TITLE__</title>
+<style>
+  :root {
+    --ink: #1c1917; --paper: #faf9f7; --muted: #78716c; --line: #e7e5e4;
+    --keep: #1d4ed8; --keep-bg: #eff4ff; --drop: #b42318; --drop-bg: #fdf1ef;
+    --changed: #fffbeb; --changed-line: #f5c518;
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--paper); color: var(--ink); font: 16px/1.5 -apple-system, "SF Pro Text", "Helvetica Neue", Arial, sans-serif; }
+  .wrap { padding: 2rem 2.5rem 6rem; }
+  h1 { font-size: 1.7rem; margin: 0 0 .3rem; }
+  .sub { color: var(--muted); margin: 0 0 1.6rem; font-size: 1rem; }
+  .sub b { color: var(--ink); }
+  .sub code { background: #f0eeec; padding: .1em .35em; border-radius: 4px; font-size: .92em; }
+  h2 { font-size: 1.35rem; margin: 2.2rem 0 .2rem; border-bottom: 2px solid var(--ink); padding-bottom: .3rem; }
+  h3 { font-size: 1.05rem; margin: 1.3rem 0 .4rem; color: var(--ink); }
+  h3 .note { font-weight: 400; color: var(--muted); font-size: .92rem; }
+  table { width: 100%; border-collapse: collapse; }
+  th { text-align: left; font-size: .82rem; text-transform: uppercase; letter-spacing: .04em; color: var(--muted); padding: .35rem .6rem; border-bottom: 1px solid var(--line); }
+  td { padding: .5rem .6rem; border-bottom: 1px solid var(--line); vertical-align: top; }
+  tr.changed td { background: var(--changed); border-bottom-color: var(--changed-line); }
+  td.name { white-space: nowrap; font-weight: 600; }
+  td.name a { color: var(--ink); text-decoration: none; border-bottom: 1px solid #c8c4c0; }
+  td.name a:hover { border-bottom-color: var(--ink); }
+  td.dl { white-space: nowrap; font-variant-numeric: tabular-nums; color: var(--muted); text-align: right; }
+  td.mine { white-space: nowrap; }
+  .badge { display: inline-block; font-size: .78rem; font-weight: 700; letter-spacing: .03em; padding: .12em .5em; border-radius: 4px; }
+  .badge.keep { color: var(--keep); background: var(--keep-bg); }
+  .badge.drop { color: var(--drop); background: var(--drop-bg); }
+  td.reason { color: #44403c; font-size: .95rem; max-width: 34rem; }
+  td.yours { white-space: nowrap; }
+  .seg { display: inline-flex; border: 1px solid var(--line); border-radius: 6px; overflow: hidden; }
+  .seg button { border: 0; background: #fff; padding: .3rem .8rem; font: inherit; font-size: .88rem; cursor: pointer; color: var(--muted); }
+  .seg button + button { border-left: 1px solid var(--line); }
+  .seg button.on.k { background: var(--keep); color: #fff; font-weight: 700; }
+  .seg button.on.d { background: var(--drop); color: #fff; font-weight: 700; }
+  td.fb input { width: 100%; min-width: 14rem; font: inherit; font-size: .92rem; padding: .3rem .5rem; border: 1px solid var(--line); border-radius: 6px; background: #fff; }
+  td.fb input:focus { outline: 2px solid var(--keep); outline-offset: 0; }
+  .bar { position: fixed; bottom: 0; left: 0; right: 0; background: var(--ink); color: #fafaf9; display: flex; align-items: center; gap: 1.4rem; padding: .7rem 2.5rem; font-size: .95rem; }
+  .bar .counts b { font-variant-numeric: tabular-nums; }
+  .bar button { font: inherit; font-weight: 700; padding: .45rem 1.1rem; border: 0; border-radius: 6px; background: #fafaf9; color: var(--ink); cursor: pointer; }
+  .bar button:hover { background: #e7e5e4; }
+  .bar .hint { color: #a8a29e; }
+  #out { display: none; width: 100%; height: 9rem; margin-top: 1rem; font: 13px/1.4 ui-monospace, monospace; }
+</style>
+</head>
+<body>
+<div class="wrap">
+  <h1>__TITLE__</h1>
+  <p class="sub">__SUB__</p>
+  <div id="app"></div>
+  <textarea id="out" readonly></textarea>
+</div>
+<div class="bar">
+  <span class="counts" id="counts"></span>
+  <button onclick="copyFeedback()">Copy feedback</button>
+  <span class="hint" id="hint">Copies only rows you changed or commented, as JSON.</span>
+</div>
+<script>
+const DATA = __DATA__;
+
+const KEY = "__KEY__";
+let state = {};
+try { state = JSON.parse(localStorage.getItem(KEY) || "{}"); } catch (e) {}
+
+function rowId(section, name) { return section + "::" + name; }
+
+function render() {
+  const app = document.getElementById("app");
+  let html = "", lastSection = "";
+  for (const [section, subcat, rows] of DATA) {
+    if (section !== lastSection) { html += `<h2>${section}</h2>`; lastSection = section; }
+    const parts = subcat.split(" — ");
+    html += `<h3>${parts[0]}${parts[1] ? ` <span class="note">— ${parts[1]}</span>` : ""}</h3>`;
+    html += `<table><tr><th>Entry</th><th style="text-align:right">Downloads/mo</th><th>My verdict</th><th>My reason</th><th>Yours</th><th>Your reason (optional)</th></tr>`;
+    for (const [name, url, dl, mine, reason] of rows) {
+      const id = rowId(section, name);
+      const s = state[id] || {};
+      const yours = s.verdict || mine;
+      const changed = yours !== mine || (s.feedback || "").trim() !== "";
+      html += `<tr id="${cssId(id)}" class="${changed ? "changed" : ""}">
+        <td class="name"><a href="${url}" target="_blank" rel="noopener">${name}</a></td>
+        <td class="dl">${dl}</td>
+        <td class="mine"><span class="badge ${mine}">${mine.toUpperCase()}</span></td>
+        <td class="reason">${reason}</td>
+        <td class="yours"><span class="seg">
+          <button class="k ${yours === "keep" ? "on" : ""}" onclick="setV('${esc(id)}','keep')">Keep</button>
+          <button class="d ${yours === "drop" ? "on" : ""}" onclick="setV('${esc(id)}','drop')">Drop</button>
+        </span></td>
+        <td class="fb"><input value="${(s.feedback || "").replace(/"/g, "&quot;")}" oninput="setF('${esc(id)}', this.value)" placeholder="why…"></td>
+      </tr>`;
+    }
+    html += `</table>`;
+  }
+  app.innerHTML = html;
+  updateCounts();
+}
+
+function cssId(id) { return "r-" + id.replace(/[^a-zA-Z0-9]/g, "_"); }
+function esc(id) { return id.replace(/'/g, "\\'"); }
+
+function setV(id, v) { state[id] = state[id] || {}; state[id].verdict = v; save(); render(); }
+function setF(id, f) {
+  state[id] = state[id] || {}; state[id].feedback = f; save();
+  const [section, name] = id.split("::");
+  const mine = findMine(section, name);
+  const yours = state[id].verdict || mine;
+  document.getElementById(cssId(id)).className = (yours !== mine || f.trim() !== "") ? "changed" : "";
+  updateCounts();
+}
+function findMine(section, name) {
+  for (const [s, , rows] of DATA) if (s === section) for (const r of rows) if (r[0] === name) return r[3];
+}
+function save() { localStorage.setItem(KEY, JSON.stringify(state)); }
+
+function collect() {
+  const out = [];
+  for (const [section, subcat, rows] of DATA) {
+    for (const [name, , , mine] of rows) {
+      const id = rowId(section, name);
+      const s = state[id] || {};
+      const yours = s.verdict || mine;
+      const fb = (s.feedback || "").trim();
+      if (yours !== mine || fb) out.push({ section, subcategory: subcat.split(" — ")[0], entry: name, my_verdict: mine, your_verdict: yours, reason: fb });
+    }
+  }
+  return out;
+}
+
+function updateCounts() {
+  let keeps = 0, total = 0, changed = 0;
+  for (const [section, , rows] of DATA) for (const [name, , , mine] of rows) {
+    total++;
+    const s = state[rowId(section, name)] || {};
+    const yours = s.verdict || mine;
+    if (yours === "keep") keeps++;
+    if (yours !== mine) changed++;
+  }
+  document.getElementById("counts").innerHTML = `<b>${keeps}</b> keep · <b>${total - keeps}</b> drop of <b>${total}</b> &nbsp;|&nbsp; <b>${changed}</b> verdicts flipped`;
+}
+
+function copyFeedback() {
+  const fb = collect();
+  const text = fb.length ? JSON.stringify(fb, null, 1) : "(no changes — all verdicts accepted as-is)";
+  const hint = document.getElementById("hint");
+  navigator.clipboard.writeText(text).then(
+    () => { hint.textContent = `Copied ${fb.length ? fb.length + " row(s)" : "acceptance note"} — paste into the chat.`; },
+    () => { const o = document.getElementById("out"); o.style.display = "block"; o.value = text; o.select(); hint.textContent = "Clipboard blocked — select & copy the box above."; }
+  );
+}
+
+render();
+</script>
+</body>
+</html>

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,24 +1,26 @@
 ## Project
 
-[Project Name](url)
+[project-name](url)
 
 ## Checklist
 
+- [ ] I read [CONTRIBUTING.md](https://github.com/vinta/awesome-python/blob/master/CONTRIBUTING.md) - awesome-python is a shortlist, not a catalog
 - [ ] One project per PR
 - [ ] PR title format: `Add project-name`
-- [ ] Entry format: `- [project-name](url) - Description ending with period.`
-- [ ] Description is concise and short
+- [ ] Entry format: `- [pypi-name](https://github.com/owner/repo) - Description ending with period.`
+- [ ] Display name is the PyPI package name
+- [ ] Placed in an existing use case (new sections and subcategories are maintainer-only)
+- [ ] Meets all Quality Requirements: active, stable, documented, at least 1 month old
 
-## Why This Project Is Awesome
+## Which Tier
 
-Which criterion does it meet? (pick one)
+Pick one:
 
-- [ ] **Industry Standard** - The go-to tool for a specific use case
-- [ ] **Rising Star** - 5000+ stars in < 2 years, significant adoption
-- [ ] **Hidden Gem** - Exceptional quality, solves niche problems elegantly
+- [ ] **Obvious choice** - a tool an experienced Python developer would name when asked "what do I use for this?"
+- [ ] **Challenger** - not yet the obvious choice, but a credible successor to one. Give adoption-trajectory evidence, not popularity alone.
 
 Explain:
 
-## How It Differs
+## Displacement
 
-If similar entries exist, what makes this one unique?
+If the use case is at its cap, name the entry your project replaces and argue that yours does that entry's job better. One in, one out.

.github/workflows/deploy-website.yml

@@ -71,6 +71,25 @@ jobs:
           fi
           python -m json.tool website/data/github_stars.json > /dev/null
 
+      - name: Restore PyPI download data cache
+        uses: actions/cache/restore@v4
+        with:
+          path: website/data/pypi_downloads.tsv
+          key: pypi-downloads-${{ steps.date.outputs.today }}
+          restore-keys: pypi-downloads-
+
+      - name: Fetch PyPI downloads
+        id: fetch-downloads
+        continue-on-error: true
+        run: make fetch_pypi_downloads
+
+      - name: Save PyPI download data cache
+        if: steps.fetch-downloads.outcome == 'success'
+        uses: actions/cache/save@v4
+        with:
+          path: website/data/pypi_downloads.tsv
+          key: pypi-downloads-${{ steps.date.outputs.today }}
+
       - name: Build website
         run: make build
 

.gitignore

@@ -11,14 +11,9 @@ __pycache__/
 
 # website
 website/output/
-website/data/
-
-# docs
-docs/
+website/data/*
+!website/data/pypi_name_overrides.json
 
 # agents
-.agents/
-.claude/skills/
-.superpowers/
 .playwright-cli/
-skills-lock.json
+tmp/