jammyfu · Nov 1, 2026 · Nov 1, 2026
diff --git a/CURRENT_PLAN.md b/CURRENT_PLAN.md
@@ -2,32 +2,32 @@
 
 ## Plan ID
 
-PLAN-002
+PLAN-003
 
 ## Goal
 
-Raise the Verify `history_total` vs `stars` slack so a 3-star GitHub discrepancy no longer blocks the daily data push, without dropping the integrity check.
+Polish the generated README first screen and stop baking an update date into the badge URL; the date must come from `data/stats.json` and refresh on every daily-update run.
 
 ## In Scope
 
-- The absolute-delta assertion in `tests/test_repo.py` (and a named constant for it)
-- A regression test that a 3-star gap is accepted and a larger gap still fails
-- Docs that currently claim the history sum equals `stargazers_count` exactly
+- `tools/render_readme.py` and `tools/i18n.py` (README / HOW_IT_WORKS / DETAILS copy)
+- Regenerated `README*.md` (and the other generated pages the renderer writes)
+- Tests that the update badge is dynamic and the stamp text is filled from `stats.json`
+- Concise first-screen copy: what the list is, the Actions schedule, how numbers are computed, how to use or contribute, links
 
 ## Out of Scope
 
-- Ranking logic, categories, newcomers, hooks, translations, GEO files
-- Disabling `tools/verify.py` or skipping the history cross-check
-- Secrets, workflow credentials, merging to `main`
+- Ranking logic, categories, the ⚠ suspected-crack rules, `data/stats.json` numbers
+- Secrets, the daily-update cron times, GEO files (`docs/FAQ.md`, `docs/FACTS.md`, `CITATION.cff`, social preview)
+- Merging to `main`
 
 ## Tasks
 
-- [x] Confirm the 2026-11-01 daily-update failure is `assertLessEqual(..., 2)` on `affaan-m/ECC` (diff 3)
-- [x] Raise the allowed absolute delta from 2 to 5 via a named constant; keep the check
-- [x] Add a unit test that delta 3 passes and delta > 5 still fails
-- [x] Document the slack (why 5, why not exact) and record the decision
-- [x] Run `python3 tools/verify.py` and `python3 tools/next_plan.py --check`
-- [x] Open a PR against `main` (do not merge)
+- [x] Replace the static `updated-YYYY--MM--DD` shields badge with a dynamic badge that reads `today_utc` from `data/stats.json`
+- [x] Keep the stamp line filled from `stats.generated_at` on every `render_readme` / daily-update run
+- [x] Add two first-screen FAQ items (how numbers are computed; how to use or contribute) linking existing `docs/FAQ.md` anchors
+- [x] Add a test that templates contain no hard-coded update date and that the rendered stamp follows `generated_at`
+- [ ] Owner reviews the PR; merge only with approval
 
 ## Verification
 

diff --git a/README.ja.md b/README.ja.md
@@ -4,11 +4,11 @@
 
 <img src=".github/social-preview.png" alt="GitHub スター急上昇ランキング / GitHub Risers" width="640">
 
-[![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![CI](https://github.com/jammyfu/github-risers/actions/workflows/ci.yml/badge.svg)](https://github.com/jammyfu/github-risers/actions/workflows/ci.yml) [![updated](https://img.shields.io/badge/updated-2026--10--31-brightgreen.svg)](latest/rankings.ja.md)
+[![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![CI](https://github.com/jammyfu/github-risers/actions/workflows/ci.yml/badge.svg)](https://github.com/jammyfu/github-risers/actions/workflows/ci.yml) [![updated](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fjammyfu%2Fgithub-risers%2Fmain%2Fdata%2Fstats.json&query=%24.today_utc&label=updated&color=brightgreen)](latest/rankings.ja.md)
 
 総スター数ではなく、1 日あたりに増えたスター数で GitHub リポジトリを並べます。AI が先頭で、開発者ツール、セキュリティ、Web / フロントエンド、インフラ、デザイン / クリエイティブ、データが続きます。1 日 2 回更新。
 
-2026-10-31 04:53（UTC）更新、1 日 2 回（北京時間 0 時、ロサンゼルス時間 0 時）。
+データ取得 2026-10-31 04:53（UTC）。1 日 2 回：北京時間 0 時（UTC+8）、ロサンゼルス時間 0 時（America/Los_Angeles）。
 
 [ウェブサイト](https://jammyfu.github.io/github-risers/) · [仕組み](docs/HOW_IT_WORKS.ja.md) · [ファクト](docs/FACTS.md) · [履歴](rankings/README.ja.md) · [最新](latest/rankings.ja.md)
 
@@ -42,6 +42,14 @@ GitHub Trending は GitHub 公式のページです。GitHub Risers は独立し
 
 1 日 2 回、北京時間 0 時とロサンゼルス時間 0 時です。実行のたびに保存します。 [詳しく見る](docs/FAQ.md#how-often-is-it-updated)
 
+### 数値はどう出す？
+
+直近 7・30・365 の完了した UTC 日の増加スターを日数で割ります。数値はすべて GitHub API から取得し、手入力や推定はしません。 [詳しく見る](docs/FAQ.md#how-is-the-growth-rate-computed)
+
+### 使い方と参加方法は？
+
+下のランキングを見るか、latest/ の上位 20 件を見てください。収録プロジェクトを足すには data/projects.json（5 言語）を編集して pull request を出します。 [詳しく見る](docs/FAQ.md#how-can-i-suggest-a-project-or-report-a-mistake)
+
 ## AI
 
 > LLM・エージェント・MCP・コーディング助手・生成 AI
@@ -521,4 +529,4 @@ GitHub Trending は GitHub 公式のページです。GitHub Risers は独立し
 
 引用の仕方：[CITATION.cff](CITATION.cff) を見てください。
 
-数字の出し方と参加方法：[docs/HOW_IT_WORKS.ja.md](docs/HOW_IT_WORKS.ja.md)。新規リポジトリのルール：[docs/NEW_ARRIVALS.md](docs/NEW_ARRIVALS.md)。カテゴリ：[docs/CATEGORIES.md](docs/CATEGORIES.md)。
+数字の出し方と参加方法：[docs/HOW_IT_WORKS.ja.md](docs/HOW_IT_WORKS.ja.md)。新規リポジトリのルール：[docs/NEW_ARRIVALS.md](docs/NEW_ARRIVALS.md)。カテゴリ：[docs/CATEGORIES.md](docs/CATEGORIES.md)。プルリクエスト：[CONTRIBUTING.md](CONTRIBUTING.md)。
diff --git a/README.ko.md b/README.ko.md
@@ -4,11 +4,11 @@
 
 <img src=".github/social-preview.png" alt="GitHub 스타 급상승 랭킹 / GitHub Risers" width="640">
 
-[![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![CI](https://github.com/jammyfu/github-risers/actions/workflows/ci.yml/badge.svg)](https://github.com/jammyfu/github-risers/actions/workflows/ci.yml) [![updated](https://img.shields.io/badge/updated-2026--10--31-brightgreen.svg)](latest/rankings.ko.md)
+[![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![CI](https://github.com/jammyfu/github-risers/actions/workflows/ci.yml/badge.svg)](https://github.com/jammyfu/github-risers/actions/workflows/ci.yml) [![updated](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fjammyfu%2Fgithub-risers%2Fmain%2Fdata%2Fstats.json&query=%24.today_utc&label=updated&color=brightgreen)](latest/rankings.ko.md)
 
 총 스타 수가 아니라 하루에 늘어난 스타 수로 GitHub 저장소를 줄 세웁니다. AI가 맨 앞이고 개발자 도구, 보안, Web / 프론트엔드, 인프라, 디자인 / 크리에이티브, 데이터가 뒤따릅니다. 하루 두 번 갱신합니다.
 
-2026-10-31 04:53(UTC) 갱신, 하루 두 번(베이징 0시, 로스앤젤레스 0시).
+데이터 시각 2026-10-31 04:53(UTC). 하루 두 번: 베이징 0시(UTC+8), 로스앤젤레스 0시(America/Los_Angeles).
 
 [웹사이트](https://jammyfu.github.io/github-risers/) · [작동 방식](docs/HOW_IT_WORKS.ko.md) · [팩트](docs/FACTS.md) · [지난 랭킹](rankings/README.ko.md) · [최신](latest/rankings.ko.md)
 
@@ -42,6 +42,14 @@ GitHub Trending은 GitHub 공식 페이지입니다. GitHub Risers는 독립적
 
 하루 두 번, 베이징 시간 0시와 로스앤젤레스 시간 0시입니다. 실행할 때마다 보관합니다. [더 보기](docs/FAQ.md#how-often-is-it-updated)
 
+### 숫자는 어떻게 계산하나요?
+
+최근 7·30·365개의 완료된 UTC 일에 늘어난 스타를 그 일수로 나눕니다. 숫자는 모두 GitHub API에서 가져오며 손으로 넣거나 추정하지 않습니다. [더 보기](docs/FAQ.md#how-is-the-growth-rate-computed)
+
+### 어떻게 보고 어떻게 기여하나요?
+
+아래 랭킹을 보거나 latest/의 상위 20개를 보세요. 수록 프로젝트를 추가하려면 data/projects.json(다섯 언어)을 고친 뒤 pull request를 보내세요. [더 보기](docs/FAQ.md#how-can-i-suggest-a-project-or-report-a-mistake)
+
 ## AI
 
 > LLM, 에이전트, MCP, 코딩 어시스턴트, 생성형 AI
@@ -521,4 +529,4 @@ GitHub Trending은 GitHub 공식 페이지입니다. GitHub Risers는 독립적
 
 인용 방법: [CITATION.cff](CITATION.cff)를 보세요.
 
-숫자를 만드는 방법과 참여 방법: [docs/HOW_IT_WORKS.ko.md](docs/HOW_IT_WORKS.ko.md). 신규 저장소 규칙: [docs/NEW_ARRIVALS.md](docs/NEW_ARRIVALS.md). 카테고리: [docs/CATEGORIES.md](docs/CATEGORIES.md).
+숫자를 만드는 방법과 참여 방법: [docs/HOW_IT_WORKS.ko.md](docs/HOW_IT_WORKS.ko.md). 신규 저장소 규칙: [docs/NEW_ARRIVALS.md](docs/NEW_ARRIVALS.md). 카테고리: [docs/CATEGORIES.md](docs/CATEGORIES.md). 풀 리퀘스트: [CONTRIBUTING.md](CONTRIBUTING.md).
diff --git a/README.md b/README.md
@@ -4,11 +4,11 @@
 
 <img src=".github/social-preview.png" alt="GitHub Risers: Ranked by Stars Gained per Day" width="640">
 
-[![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![CI](https://github.com/jammyfu/github-risers/actions/workflows/ci.yml/badge.svg)](https://github.com/jammyfu/github-risers/actions/workflows/ci.yml) [![updated](https://img.shields.io/badge/updated-2026--10--31-brightgreen.svg)](latest/rankings.md)
+[![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![CI](https://github.com/jammyfu/github-risers/actions/workflows/ci.yml/badge.svg)](https://github.com/jammyfu/github-risers/actions/workflows/ci.yml) [![updated](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fjammyfu%2Fgithub-risers%2Fmain%2Fdata%2Fstats.json&query=%24.today_utc&label=updated&color=brightgreen)](latest/rankings.md)
 
 Trending GitHub repos ranked by star growth (stars gained per day), not total stars: AI first, then developer tools, security, web, infrastructure, design and data.
 
-Updated 2026-10-31 04:53 UTC, twice a day (00:00 Beijing, 00:00 Los Angeles).
+Data from 2026-10-31 04:53 UTC. Twice a day: 00:00 Beijing (UTC+8) and 00:00 Los Angeles (America/Los_Angeles).
 
 [Website](https://jammyfu.github.io/github-risers/) · [How it works](docs/HOW_IT_WORKS.md) · [Facts](docs/FACTS.md) · [History](rankings/README.md) · [Latest](latest/rankings.md)
 
@@ -42,6 +42,14 @@ GitHub Trending is GitHub's own page. GitHub Risers is an independent open-sourc
 
 Twice a day, at 00:00 Beijing time and 00:00 Los Angeles time. Every run is archived. [Read more](docs/FAQ.md#how-often-is-it-updated)
 
+### How is the data computed?
+
+Stars gained in the last 7, 30 or 365 complete UTC days, divided by those days. All numbers come from the GitHub API; nothing is typed or estimated. [Read more](docs/FAQ.md#how-is-the-growth-rate-computed)
+
+### How do I use or contribute?
+
+Read the boards below, or the full top 20 in latest/. To add a tracked project, edit data/projects.json (five languages) and open a pull request. [Read more](docs/FAQ.md#how-can-i-suggest-a-project-or-report-a-mistake)
+
 ## AI
 
 > LLMs, agents, MCP, coding copilots and generative AI
@@ -521,4 +529,4 @@ If this saved you time, give the repo a star so others can find it.
 
 How to cite: see [CITATION.cff](CITATION.cff).
 
-How the numbers are produced and how to contribute: [docs/HOW_IT_WORKS.md](docs/HOW_IT_WORKS.md). New-repo rules: [docs/NEW_ARRIVALS.md](docs/NEW_ARRIVALS.md). Categories: [docs/CATEGORIES.md](docs/CATEGORIES.md).
+How the numbers are produced and how to contribute: [docs/HOW_IT_WORKS.md](docs/HOW_IT_WORKS.md). New-repo rules: [docs/NEW_ARRIVALS.md](docs/NEW_ARRIVALS.md). Categories: [docs/CATEGORIES.md](docs/CATEGORIES.md). Pull requests: [CONTRIBUTING.md](CONTRIBUTING.md).
diff --git a/README.zh-Hans.md b/README.zh-Hans.md
@@ -4,11 +4,11 @@
 
 <img src=".github/social-preview.png" alt="GitHub 涨星榜 / GitHub Risers" width="640">
 
-[![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![CI](https://github.com/jammyfu/github-risers/actions/workflows/ci.yml/badge.svg)](https://github.com/jammyfu/github-risers/actions/workflows/ci.yml) [![updated](https://img.shields.io/badge/updated-2026--10--31-brightgreen.svg)](latest/rankings.zh-Hans.md)
+[![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![CI](https://github.com/jammyfu/github-risers/actions/workflows/ci.yml/badge.svg)](https://github.com/jammyfu/github-risers/actions/workflows/ci.yml) [![updated](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fjammyfu%2Fgithub-risers%2Fmain%2Fdata%2Fstats.json&query=%24.today_utc&label=updated&color=brightgreen)](latest/rankings.zh-Hans.md)
 
 按每天新增星标（而不是总星标）给 GitHub 仓库排名：AI 在前，其后是开发者工具、安全、Web / 前端、基础设施、设计 / 创意和数据；每天更新两次。
 
-更新于 2026-10-31 04:53（UTC），每天两次（北京时间 0 点、洛杉矶时间 0 点）。
+数据取自 2026-10-31 04:53（UTC）。每天两次：北京时间 0 点（UTC+8）、洛杉矶时间 0 点（America/Los_Angeles）。
 
 [网站](https://jammyfu.github.io/github-risers/) · [运作方式](docs/HOW_IT_WORKS.zh-Hans.md) · [事实速查](docs/FACTS.md) · [历史榜单](rankings/README.zh-Hans.md) · [最新快照](latest/rankings.zh-Hans.md)
 
@@ -42,6 +42,14 @@ GitHub Trending 是 GitHub 官方页面；GitHub 涨星榜是独立的开源项
 
 每天两次，北京时间 0 点和洛杉矶时间 0 点；每次运行都会存档。 [了解更多](docs/FAQ.md#how-often-is-it-updated)
 
+### 数据怎么算？
+
+取最近 7、30 或 365 个完整 UTC 日的新增星标，再除以天数。数字全部来自 GitHub API，没有手填或估算。 [了解更多](docs/FAQ.md#how-is-the-growth-rate-computed)
+
+### 怎么看、怎么参与？
+
+看下面的榜，完整前 20 名在 latest/。要收录项目，改 data/projects.json（五种语言）并发 pull request。 [了解更多](docs/FAQ.md#how-can-i-suggest-a-project-or-report-a-mistake)
+
 ## 人工智能
 
 > 大模型、智能体、MCP、编程助手与生成式 AI
@@ -521,4 +529,4 @@ GitHub Trending 是 GitHub 官方页面；GitHub 涨星榜是独立的开源项
 
 如何引用：见 [CITATION.cff](CITATION.cff)。
 
-数据怎么算和如何参与：[docs/HOW_IT_WORKS.zh-Hans.md](docs/HOW_IT_WORKS.zh-Hans.md)。新仓库规则：[docs/NEW_ARRIVALS.md](docs/NEW_ARRIVALS.md)。分类说明：[docs/CATEGORIES.md](docs/CATEGORIES.md)。
+数据怎么算和如何参与：[docs/HOW_IT_WORKS.zh-Hans.md](docs/HOW_IT_WORKS.zh-Hans.md)。新仓库规则：[docs/NEW_ARRIVALS.md](docs/NEW_ARRIVALS.md)。分类说明：[docs/CATEGORIES.md](docs/CATEGORIES.md)。提交改动：[CONTRIBUTING.md](CONTRIBUTING.md)。
diff --git a/README.zh-Hant.md b/README.zh-Hant.md
@@ -4,11 +4,11 @@
 
 <img src=".github/social-preview.png" alt="GitHub 漲星榜 / GitHub Risers" width="640">
 
-[![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![CI](https://github.com/jammyfu/github-risers/actions/workflows/ci.yml/badge.svg)](https://github.com/jammyfu/github-risers/actions/workflows/ci.yml) [![updated](https://img.shields.io/badge/updated-2026--10--31-brightgreen.svg)](latest/rankings.zh-Hant.md)
+[![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![CI](https://github.com/jammyfu/github-risers/actions/workflows/ci.yml/badge.svg)](https://github.com/jammyfu/github-risers/actions/workflows/ci.yml) [![updated](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fjammyfu%2Fgithub-risers%2Fmain%2Fdata%2Fstats.json&query=%24.today_utc&label=updated&color=brightgreen)](latest/rankings.zh-Hant.md)
 
 依每天新增星號（而不是總星號）替 GitHub 儲存庫排名：AI 在前，接著是開發者工具、資安、Web / 前端、基礎建設、設計 / 創意與資料；每天更新兩次。
 
-更新於 2026-10-31 04:53（UTC），每天兩次（北京時間 0 點、洛杉磯時間 0 點）。
+資料取自 2026-10-31 04:53（UTC）。每天兩次：北京時間 0 點（UTC+8）、洛杉磯時間 0 點（America/Los_Angeles）。
 
 [網站](https://jammyfu.github.io/github-risers/) · [運作方式](docs/HOW_IT_WORKS.zh-Hant.md) · [事實速查](docs/FACTS.md) · [歷史榜單](rankings/README.zh-Hant.md) · [最新快照](latest/rankings.zh-Hant.md)
 
@@ -42,6 +42,14 @@ GitHub Trending 是 GitHub 官方頁面；GitHub 漲星榜是獨立的開源專
 
 每天兩次，北京時間 0 點和洛杉磯時間 0 點；每次執行都會存檔。 [了解更多](docs/FAQ.md#how-often-is-it-updated)
 
+### 資料怎麼算？
+
+取最近 7、30 或 365 個完整 UTC 日的新增星號，再除以天數。數字全部來自 GitHub API，沒有手填或估算。 [了解更多](docs/FAQ.md#how-is-the-growth-rate-computed)
+
+### 怎麼看、怎麼參與？
+
+看下面的榜，完整前 20 名在 latest/。要收錄專案，改 data/projects.json（五種語言）並發 pull request。 [了解更多](docs/FAQ.md#how-can-i-suggest-a-project-or-report-a-mistake)
+
 ## 人工智慧
 
 > 大型語言模型、代理、MCP、程式設計助手與生成式 AI
@@ -521,4 +529,4 @@ GitHub Trending 是 GitHub 官方頁面；GitHub 漲星榜是獨立的開源專
 
 如何引用：見 [CITATION.cff](CITATION.cff)。
 
-數據怎麼算與如何參與：[docs/HOW_IT_WORKS.zh-Hant.md](docs/HOW_IT_WORKS.zh-Hant.md)。新儲存庫規則：[docs/NEW_ARRIVALS.md](docs/NEW_ARRIVALS.md)。分類說明：[docs/CATEGORIES.md](docs/CATEGORIES.md)。
+資料怎麼算與如何參與：[docs/HOW_IT_WORKS.zh-Hant.md](docs/HOW_IT_WORKS.zh-Hant.md)。新儲存庫規則：[docs/NEW_ARRIVALS.md](docs/NEW_ARRIVALS.md)。分類說明：[docs/CATEGORIES.md](docs/CATEGORIES.md)。提交改動：[CONTRIBUTING.md](CONTRIBUTING.md)。
diff --git a/docs/project-governance/ACCEPTANCE.md b/docs/project-governance/ACCEPTANCE.md
@@ -18,6 +18,12 @@
 - Every scheduled entry (both Beijing and Los Angeles crons, `workflow_dispatch`, local launchd) runs `tools/update_stars.py` (`tests/test_spam.py::ScheduledPathTests`)
 - README is a first screen (top 10 per board); the full top 20 is in `latest/`; GEO files exist and are linked
 
+## README update date
+
+- The `updated` badge is dynamic (`shields.io` JSON → `data/stats.json` `today_utc`); i18n templates contain no `YYYY-MM-DD`
+- The stamp line is written from `stats.generated_at` on every `python3 tools/render_readme.py` run
+- First screen states what the list is, the Beijing / Los Angeles schedule, how numbers are computed, and how to use or contribute
+
 ## Phase 4: harness
 
 - `CURRENT_PLAN.md` passes `python3 tools/next_plan.py --check` (one Plan ID, one Goal, 3-7 tasks, Out of Scope, Verification, Next Candidates)

diff --git a/docs/project-governance/CHANGELOG.md b/docs/project-governance/CHANGELOG.md
@@ -1,5 +1,10 @@
 # CHANGELOG.md
 
+## 2026-11-01 (README date and first screen)
+
+- The README `updated` badge is a dynamic shields.io JSON badge that reads `today_utc` from `data/stats.json`. The stamp line is filled from `generated_at` on every daily-update render. No update date is typed into `tools/i18n.py`.
+- First screen adds two short Q&As: how the numbers are computed, and how to use or contribute. Footer links `CONTRIBUTING.md`. Schedule on the stamp matches Actions: Beijing 00:00 (UTC+8) and Los Angeles 00:00 (`America/Los_Angeles`).
+
 ## 2026-10-29
 
 - Rankings by stars/day (week, month, year) with total stars last, all from the GitHub API.