john-the-dev · john-the-dev · Aug 31, 2026 · Aug 31, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -18,6 +18,6 @@ Thanks for helping keep AI-agent engineering knowledge accurate and fresh.
 - **Lessons are public-only.** `category: lessons` entries must come from famous, publicly-documented projects/post-mortems. Never include private, proprietary, or non-public project details (anyone's).
 - **Primary sources first** — official docs / papers / release notes over secondhand blogs.
 
-## The maintainer bot
+## The maintainer bot (planned)
 
-An automated maintainer (Sutando) also opens PRs — proposing new entries from the latest releases/research and flagging entries whose `last_verified` is >90 days old. Bot PRs are reviewed and merged by a human, same as any other.
+An automated maintainer that proposes new entries and flags entries whose `last_verified` is >90 days old is planned but **not running yet**. Until it exists, both jobs are human: `scripts/validate.mjs` warns on every `unrated` entry, and stale ones are found by the same rubric a bot would apply. Bot PRs, when they arrive, will be reviewed and merged by a human like any other.
diff --git a/GRADING.md b/GRADING.md
@@ -10,7 +10,7 @@ Grades exist so "bad tech" and "outdated knowledge" are **evidence-based, not op
 | **B** | Solid and useful, with caveats. Maintained but niche, or accurate-but-aging, or best-for-specific-cases. Note the caveat in `evidence`. |
 | **C** | Use with caution. Slowing maintenance, partial adoption, known rough edges, or partially superseded. |
 | **D** | Discouraged. Deprecated, abandoned, superseded, or carrying unresolved security/correctness issues. Kept for the historical record and to warn readers — set `status: deprecated` (or `superseded`) and fill `superseded_by`. |
-| **unrated** | Seeded or newly-added, not yet evidence-graded. The maintainer bot grades these on its next pass. |
+| **unrated** | Seeded or newly-added, not yet evidence-graded. `scripts/validate.mjs` warns on each one; grading them is open contribution work. |
 
 ## Signals (what `evidence` should cite)
 
@@ -35,4 +35,4 @@ Each `evidence` item should be a dated, checkable statement, e.g.:
 
 ## Staleness
 
-An entry is **stale** when `last_verified` is more than **90 days** old. The maintainer bot flags stale entries in a `review-needed` PR; a human (or the bot with evidence) re-verifies and updates `last_verified` + `grade`.
+An entry is **stale** when `last_verified` is more than **90 days** old. Re-verify it and update `last_verified` + `grade` with fresh evidence. (Automated flagging is planned; today this is a manual check — as of the last measurement no entry was over 90 days.)
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 A continuously-maintained, **quality-graded** knowledge base of AI-agent engineering — frameworks, orchestration, evaluation, memory, tools, protocols, security, and research.
 
-Most "awesome" lists rot: agent tooling ships breaking changes monthly, and stale entries mislead more than they help. This repo's differentiator is **freshness + grading**: every entry carries a `status`, a `last_verified` date, and an evidence-backed `grade`, and an automated maintainer bot proposes additions and flags stale entries for review.
+Most "awesome" lists rot: agent tooling ships breaking changes monthly, and stale entries mislead more than they help. This repo's differentiator is **freshness + grading**: every entry carries a `status`, a `last_verified` date, and an evidence-backed `grade`. An automated maintainer that proposes additions and flags stale entries is planned, not yet running — grading is done by maintainers and contributors today.
 
 It's **dual-use**:
 - **Human-browsable** — one markdown file per entry under [`entries/`](entries/).
@@ -23,7 +23,7 @@ It's CC BY 4.0: any surface using this content must visibly credit **The Agent L
 ```
 entries/*.md   ──build──▶   dist/kb.json   ──ingest──▶   agent-loop.xyz RAG
    ▲                                                          
-   └── humans (PRs) + Sutando maintainer-bot (auto-PRs new entries, flags stale)
+   └── humans (PRs)   [maintainer-bot: planned, not yet running]
 ```
 
 ## Entry format
@@ -55,7 +55,9 @@ Entries are graded **A/B/C/D** on an evidence-based rubric (see [`GRADING.md`](G
 
 ## Contributing
 
-PRs welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md). CI validates every entry against the schema + rubric. The maintainer bot opens PRs too; humans review and merge.
+PRs welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md). CI validates every entry against the schema + rubric.
+
+**Good first contribution:** any entry `scripts/validate.mjs` still flags as `grade: unrated`, or any entry whose `evidence` you can strengthen — or contradict — with a dated, checkable source. [`GRADING.md`](GRADING.md) is the rubric, and re-grading against it counts as much as first-grading. One entry, evidenced, is a complete and useful PR.
 
 ## Status