jammyfu · Oct 30, 2026 · Oct 30, 2026
diff --git a/.github/workflows/daily-update.yml b/.github/workflows/daily-update.yml
@@ -91,6 +91,6 @@ jobs:
           fi
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git add data rankings latest README*.md docs/HOW_IT_WORKS*.md
+          git add data rankings latest README*.md docs/HOW_IT_WORKS*.md docs/DETAILS*.md
           git commit -m "chore(data): daily star update $(date -u +%F)"
           git push origin HEAD:main
diff --git a/AGENTS.md b/AGENTS.md
@@ -5,11 +5,12 @@ Project harness follows `jammyfu/CoderSkills` → `skills/continuous-project-loo
 - Single plan entry: `CURRENT_PLAN.md`. Long-term route: `MASTER_PLAN.md`. Candidates: `TODO_BACKLOG.md`. Records: `docs/project-governance/`.
 - Verify before claiming done: `python3 tools/verify.py` (explicit interpreter, no PATH reliance).
 - Star data must come from the GitHub API only (`python3 tools/update_stars.py`). Never type or estimate numbers; mark missing data as missing.
-- Never edit the generated files by hand: `README*.md`, `docs/HOW_IT_WORKS*.md`, `data/stats.json`, `latest/`, `rankings/` (history snapshots are append-only; never edit or delete them by hand). Edit `data/projects.json`, `data/categories.json`, `tools/i18n.py`, then re-run the tools.
+- Never edit the generated files by hand: `README*.md`, `docs/HOW_IT_WORKS*.md`, `docs/DETAILS*.md`, `data/stats.json`, `latest/`, `rankings/` (history snapshots are append-only; never edit or delete them by hand). Edit `data/projects.json`, `data/categories.json`, `tools/i18n.py`, then re-run the tools.
 - Zero telemetry: no analytics, tracking or beacon scripts, ever.
 - `data/projects.json` `desc` and `data/categories.json` `name`/`desc` need all five languages: en, zh-Hans, zh-Hant, ja, ko.
 - Changes go through pull requests. Do not push or merge to `main` without the owner's approval (the daily workflow/script is the only automated writer of `data/` and `README*`).
 - Generated too: `rankings/README*.md`, `latest/rankings*.md`, `rankings/<date>/<slot>/rankings.<lang>.md` (all from `tools/i18n.py` + `stats.json`). Translations of new-repo descriptions live in the translation library `data/translation_library.json` (repo + source hash + language; fixed terms in `data/glossary.json`); list the gaps and the hit rate with `python3 tools/newcomer_i18n.py`. The README is only a first screen (top 10 per board; the full top 20 is in `latest/`; it links `docs/FAQ.md`, `docs/FACTS.md`, `CITATION.cff`, `.github/social-preview.png`, which the GEO work owns: never generate or overwrite them from the generator) (headline, one sentence, this round's #1s, the boards): change its wording in `tools/i18n.py` / `tools/render_readme.py`, and put explanations in `render_docs` (`docs/HOW_IT_WORKS*.md`).
+- Ranking tables show ONE short hook per project (`tools/hooks.py`; zh <= ~15 characters, en <= 60, ja/ko equally short): `hook` in `data/projects.json`, and `hook` inside each `data/translation_library.json` entry. `desc` and every stored translation are the detailed intro, are never shortened or re-translated, and are listed on `docs/DETAILS*.md`.
 - The "hottest new repos (7 days)" ranking is discovered by `tools/newcomers.py` from the search API; it must never repeat a project from another ranking (see `docs/NEW_ARRIVALS.md`).
 
 - Categories (AI primary + others) are defined in `data/categories.json` and documented in `docs/CATEGORIES.md`. Newcomers are per-category; see `docs/NEW_ARRIVALS.md`.

diff --git a/README.ja.md b/README.ja.md
diff --git a/README.ko.md b/README.ko.md
diff --git a/README.md b/README.md
diff --git a/README.zh-Hans.md b/README.zh-Hans.md
diff --git a/README.zh-Hant.md b/README.zh-Hant.md
diff --git a/data/projects.json b/data/projects.json
diff --git a/data/translation_library.json b/data/translation_library.json
diff --git a/docs/DETAILS.ja.md b/docs/DETAILS.ja.md
diff --git a/docs/DETAILS.ko.md b/docs/DETAILS.ko.md
diff --git a/docs/DETAILS.md b/docs/DETAILS.md
diff --git a/docs/DETAILS.zh-Hans.md b/docs/DETAILS.zh-Hans.md
diff --git a/docs/DETAILS.zh-Hant.md b/docs/DETAILS.zh-Hant.md
diff --git a/docs/FACTS.md b/docs/FACTS.md
@@ -10,6 +10,7 @@ A one-page, quotable summary. Details live in [CATEGORIES.md](CATEGORIES.md), [N
 | Main board | AI (LLMs, agents, MCP, coding copilots, generative AI) |
 | Other boards | Developer Tools, Security, Web / Frontend, Infrastructure, Design / Creative, Data |
 | Boards per category | 1. Hottest new repos (created in the last 7 days) 2. Fastest rising this week 3. This month 4. This year 5. Total stars (always last). Up to the top 20 each |
+| Descriptions | Each ranking row shows one short hook (about 15 Chinese characters or 60 English letters). The full description of every project, in all five languages, is on [DETAILS.md](DETAILS.md) |
 | Growth windows | 7, 30 and 365 complete UTC days before the run day |
 | Growth formula | `per_day = stars gained in the window / days used`. A repo younger than the window uses its own age as the divisor and is marked young |
 | New-repo hotness | `stars / max(age in days, 1)`, repos created in the last 7 days, at least 100 stars, not a fork, not archived |

diff --git a/docs/I18N_PIPELINE.md b/docs/I18N_PIPELINE.md
@@ -4,7 +4,7 @@ Runs inside `python3 tools/update_stars.py --slot ...` (the daily workflow and `
 discovered and before the READMEs are rendered. Skip it with `--no-i18n`. Polish can also be run on its own: `tools/polish_local.sh`.
 
 ```
-discover new repos ─▶ 1 translate (only what is missing) ─▶ [2 polish, local only] ─▶ render
+discover new repos ─▶ 1 translate (only what is missing) ─▶ 2 hooks (only what is missing) ─▶ [3 polish, local only] ─▶ render
 ```
 
 Everything here is **fail-safe**: no key / sign-in, no CLI, model not offered, a failed call, a reply that breaks a guard — the
@@ -48,7 +48,26 @@ every identifier-like name (`TinyPNG`, `gpt-2`, `Node.js`...). Rules sent to the
 keep names/links/code/emoji/`…`, star = 星标 (zh-Hans) / 星號 (zh-Hant), agent = 智能体 / 代理 / エージェント / 에이전트,
 Traditional Chinese in Taiwan/Hong Kong wording.
 
-## 2. Polish
+## 2. One-line hooks (`tools/hooks.py`)
+
+The ranking tables show ONE short, plain, catchy line per repo, not the full description: for example
+`morluto/rea` is "Let AI reverse-engineer and clone any software" / 「让 AI 帮你逆向、复刻任何软件」. The long text stays,
+unchanged, as the detailed intro, and every translation stays too: both are listed on `docs/DETAILS*.md`
+(one page per language, linked from the README).
+
+- **Where**: `hook` ({lang: text}) next to `desc` in `data/projects.json`, and `hook` inside the translation-library entry
+  of the same repo + source hash. A hook is a separate field: adding it never changes or re-translates an existing entry,
+  and the old entries keep matching for reuse (`tests/test_hooks.py` checks that they survive byte for byte).
+- **Limits** (display width, CJK characters count double; enforced by `check_hook` and by the tests for every stored hook):
+  zh-Hans / zh-Hant <= 18 characters (aim for ~15), ja <= 28, ko <= 30, en <= 60. No `!`, no hype words, no trailing `…`,
+  no number that is not in the source. Suspected cracked / pirated repos get a flat literal label.
+- **Stage**: `python3 tools/i18n_pipeline.py --hooks` (also part of the default run). Only repos whose current text has no
+  valid hook, in only the missing languages, go to the model (`HOOK_PROMPT`, which embeds `HOOK_RULE`). Backend:
+  `I18N_HOOK_BACKEND`, default = the translate backend, so scheduled new repos get a hook in CI too; `tools/polish_local.sh`
+  uses `agy`. A hook that fails the guard is rejected and the row falls back to the translation until the next run.
+- Hooks are not polished; the polish stage only rewrites the detailed texts.
+
+## 3. Polish
 
 Voice: plain spoken words, short-video host style, lead with the point, one sentence for what it does and why it is
 worth a look, condensed, never clickbait, never exaggerated, nothing invented.

diff --git a/docs/project-governance/CHANGELOG.md b/docs/project-governance/CHANGELOG.md
@@ -26,6 +26,11 @@
 - READMEs in all five languages are now a first screen: headline, one sentence, update stamp, the category leaders table (rows link to the category boards), then the category boards. Intro, schedule, "how it is produced", categories table and contributing moved to generated `docs/HOW_IT_WORKS*.md`; the long new-repo explanation moved there too.
 - README first screen reworked (generator only): first line `GitHub 涨星榜 / GitHub Risers` (English: `GitHub Risers: Ranked by Stars Gained per Day`), header image `.github/social-preview.png`, three badges (MIT, CI, last updated), website link, three Q&A subheads linking `docs/FAQ.md`, a star prompt, a "how to cite" line (`CITATION.cff`) and a link to `docs/FACTS.md`. Each board shows the top 10 in the README; the full top 20 stays in `latest/`. Those linked files come from the GEO pull request (#9); the generator only links them, and a test checks the FAQ anchors.
 
+## 2026-10-30 (one-line hooks)
+
+- Ranking tables show ONE short hook per project (`tools/hooks.py`: zh <= ~15 characters, en <= 60, ja/ko equally short) instead of the full description. Hooks are a separate field (`hook` in `data/projects.json` and inside each `data/translation_library.json` entry); every long description and translation is kept unchanged and listed on the new generated `docs/DETAILS*.md`.
+- `tools/i18n_pipeline.py --hooks` stage (rule embedded in the prompt, length/hype/number guards); `tests/test_hooks.py` checks the limits per language and that every old entry survives (`tests/fixtures/pre_hook_baseline.json`).
+
 ## 2026-10-30 (categories)
 
 - Rebranded to GitHub Risers with categories (AI first, then developer tools, security, web, infrastructure, design, data), each with new-repo, week, month, year and total boards.