From ba25f96fdddda32c41b1a14413a82af57c54dee8 Mon Sep 17 00:00:00 2001
From: justincasher <justinchadwickasher@gmail.com>
Date: Sat, 9 May 2026 12:05:19 -0700
Subject: [PATCH] Scaffold aggregator/candidates and move manifest cache out of
 python/

Adds the aggregator/candidates/ directory that future PRs will populate
with one curated file per candidate package, plus an auto-generated
summary table in README.md.

Moves the local Reservoir manifest cache from python/cache/ to
aggregator/candidates/raw_data/, gitignored. The aggregator CLI's
default --output now resolves to that path regardless of cwd. No raw
data is committed; if we later want a stable snapshot we will publish
it as a GitHub Releases asset.
---
 .gitignore                              |  6 +++++-
 aggregator/candidates/README.md         | 23 +++++++++++++++++++++++
 aggregator/candidates/packages/.gitkeep |  0
 python/lean_pool/aggregator/__main__.py |  5 ++++-
 4 files changed, 32 insertions(+), 2 deletions(-)
 create mode 100644 aggregator/candidates/README.md
 create mode 100644 aggregator/candidates/packages/.gitkeep

diff --git a/.gitignore b/.gitignore
index dca4334122..72f298c0e7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,5 +6,9 @@ __pycache__/
 .venv/
 .ruff_cache/
 .pytest_cache/
-cache/
+
+# Aggregator: the Reservoir manifest is fetched on demand and kept
+# locally only. Curated per-package files in candidates/packages/
+# are the source of truth that gets committed.
+/aggregator/candidates/raw_data/
 
diff --git a/aggregator/candidates/README.md b/aggregator/candidates/README.md
new file mode 100644
index 0000000000..37ffc4fc85
--- /dev/null
+++ b/aggregator/candidates/README.md
@@ -0,0 +1,23 @@
+# Candidates
+
+Tracking which Lean packages we are considering for inclusion in
+`lean-pool`, along with the reasoning behind each decision.
+
+## Layout
+
+- `packages/` — one file per candidate package, holding the curated
+  metadata and review status. The per-package files are the source of
+  truth for everything in this directory and are populated by a
+  follow-up PR.
+- `raw_data/` (gitignored) — local-only Reservoir manifest snapshots.
+  Running `uv run python -m lean_pool.aggregator` from `python/`
+  downloads `manifest.json` here. Nothing in this folder is committed;
+  if we later want a stable snapshot we will publish it as a GitHub
+  Releases asset rather than tracking it in git.
+
+The summary table below is auto-generated from `packages/` and should
+not be edited by hand.
+
+<!-- BEGIN AUTOGENERATED TABLE -->
+<!-- The aggregator will populate this section in a follow-up PR. -->
+<!-- END AUTOGENERATED TABLE -->
diff --git a/aggregator/candidates/packages/.gitkeep b/aggregator/candidates/packages/.gitkeep
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/python/lean_pool/aggregator/__main__.py b/python/lean_pool/aggregator/__main__.py
index de236a4299..ec4f50c9eb 100644
--- a/python/lean_pool/aggregator/__main__.py
+++ b/python/lean_pool/aggregator/__main__.py
@@ -13,6 +13,9 @@
     save_manifest,
 )
 
+REPO_ROOT = Path(__file__).resolve().parents[3]
+DEFAULT_OUTPUT = REPO_ROOT / "aggregator" / "candidates" / "raw_data" / "manifest.json"
+
 
 @click.command()
 @click.option(
@@ -24,7 +27,7 @@
 @click.option(
     "--output",
     type=click.Path(dir_okay=False, path_type=Path),
-    default=Path("cache/manifest.json"),
+    default=DEFAULT_OUTPUT,
     show_default=True,
     help="Where to save the downloaded manifest.",
 )