whygit 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 whygit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,268 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# whygit
+
+**Git blame tells you *who*. whygit tells you *why*.**
+
+Point it at any repository. It turns the reasons already buried in git history
+into answers you and your coding agent can cite 鈥?file, line, commit, author, date.
+
+[![npm](https://img.shields.io/npm/v/whygit?color=cb3837)](https://www.npmjs.com/package/whygit)
+[![tests](https://github.com/carefreebit/whygit/actions/workflows/ci.yml/badge.svg)](https://github.com/carefreebit/whygit/actions/workflows/ci.yml)
+[![node](https://img.shields.io/badge/node-%3E%3D22.5-3c873a)](https://nodejs.org)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![MCP](https://img.shields.io/badge/MCP-ready-6b46c1)](#give-it-to-your-agent)
+
+[涓枃](README.zh-CN.md) 路 [Quickstart](#quickstart) 路 [Commands](#commands) 路 [Agents](#give-it-to-your-agent) 路 [How it works](#how-it-works)
+
+</div>
+
+---
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/carefreebit/whygit/main/docs/demo.svg" alt="whygit why &quot;cookie jar&quot; in a terminal" width="900">
+</p>
+
+<p align="center"><sub>Real output: <code>whygit why "cookie jar"</code> on <code>psf/requests</code> 鈥?4,884 commits indexed in 3s, answered in 21ms.</sub></p>
+
+That answer existed all along 鈥?in a commit body from 2015 that nobody has read since.
+whygit found it in 21 milliseconds, without an LLM, an API key, or a network call.
+
+## The problem
+
+Every codebase is full of lines that look wrong but are not. A retry that seems
+redundant. A guard that seems paranoid. A `sleep(2)` that looks like laziness.
+
+- `git blame` tells you **who** touched the line and **when**. Not why.
+- `git log` is a write-only database. The reason is in the body of a commit from 2016.
+- LLM summaries of history **invent plausible reasons**. In a codebase, a plausible
+  wrong reason is worse than no reason.
+- Coding agents are the worst affected: they rewrite the guard, delete the retry, and
+  the bug comes back six months later 鈥?because nothing told them the line was load-bearing.
+
+whygit reads what your repository already wrote down, extracts the sentences that
+actually explain a decision, and makes them retrievable in the two places that matter:
+**your terminal** and **your agent's context window**.
+
+## Quickstart
+
+```bash
+npx whygit init                     # one pass over history, ~2s for 5k commits
+npx whygit why "retry on 503"       # natural-language question
+npx whygit why src/client.js:42     # what is this exact line doing here?
+npx whygit cursed                   # the files that keep coming back
+npx whygit story src/client.js      # one file, birth to HEAD
+npx whygit whylog --write           # write WHYLOG.md, the file agents read
+```
+
+Requires **Node 22.5+** (for the built-in `node:sqlite`). Zero runtime dependencies.
+No config file, no account, no telemetry.
+
+The first command builds a local index at `.git/whygit/index.db`. Every command after
+it is incremental: new commits are picked up automatically on the next run.
+
+## Commands
+
+| Command | What it answers |
+| --- | --- |
+| `whygit why <words>` | Why does this behaviour exist? Ranked decisions with citations. |
+| `whygit why <file>:<line>` | Why is *this line* still here? Blame + the decision behind it + how much of that change is still alive. |
+| `whygit story <file>` | The biography of one file: birth, commits per year, the chapters that mattered, who kept it alive. |
+| `whygit cursed` | Ranked risk map: churn 脳 fix density 脳 author spread 脳 freshness. Read before refactoring. |
+| `whygit whylog --write` | Generate `WHYLOG.md`: load-bearing decisions + cursed files, in Markdown. |
+| `whygit check --base origin/main` | CI gate: what fraction of newly added lines trace to a commit that said why. |
+| `whygit mcp` | MCP server over stdio for Claude Code, Cursor, Codex, and any MCP client. |
+| `whygit install <agent>` | Writes the MCP config (`claude`, `cursor`, `vscode`, `agents`, `all`). |
+| `whygit doctor` | Checks git, index freshness, shallow clones, missing WHYLOG. |
+
+Every command takes `--json` for scripting, and `--cwd <path>` to point at another repo.
+
+### `why <file>:<line>`
+
+```console
+$ whygit why src/requests/models.py:120
+
+   1. basics working
+    2012-12-15 路 366e8e84 路 Kenneth Reitz 路 change
+    line 120 is 78 lines of this change, still in HEAD
+
+   2. Add hasattr checks for remaining protocol isinstance checks (#7505)
+    2026-06-09 路 6f66281a 路 change
+```
+
+The line itself is unremarkable. What matters is that 78 lines around it are still
+the original 2012 change 鈥?so the surrounding shape is load-bearing, not incidental.
+
+### `story <file>`
+
+```console
+$ whygit story src/requests/models.py
+
+  born 2011-05-14 路 package refactor
+
+    2011  鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅路路路路路路  217
+    2012  鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅  254
+    2013  鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅路路路路路路路路路路路路路路路路路路路路路路路路路路   86
+    ...
+
+  717 commits 路 202 authors 路 154 fixes 路 0 TODO markers
+  鈹€鈹€鈹€ the plot 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+
+  2015-04-06  Copy a PreparedRequest's CookieJar reliably
+            By adding _copy_cookie_jar we can reliably copy cookie jars so that we
+            have an actual copy instead of the same instance on different prepared
+            requests.
+```
+
+### `cursed`
+
+```console
+$ whygit cursed
+
+   1  src/requests/models.py          鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅    8.1  717 commits 路 202 authors 路 154 fixes
+   2  src/requests/sessions.py        鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻埪?   7.5  334 commits 路 110 authors 路 79 fixes
+   3  tests/test_requests.py          鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅鈻堚枅路路    7.2  366 commits 路 104 authors 路 76 fixes
+```
+
+Not a code-quality judgement 鈥?a map of where history is dense enough that a
+confident rewrite is likely to be wrong.
+
+## Give it to your agent
+
+An agent without history rewrites load-bearing code. An agent with history asks
+better questions. One command wires it up:
+
+```bash
+npx whygit install claude     # .mcp.json
+npx whygit install cursor     # .cursor/mcp.json
+npx whygit install vscode     # .vscode/mcp.json
+npx whygit install agents     # appends a block to AGENTS.md (works with any agent)
+npx whygit install all
+```
+
+Add `--local` if `whygit` is on your `PATH` (otherwise the config uses `npx -y whygit@latest`).
+
+The MCP server exposes five tools:
+
+| Tool | Use it when |
+| --- | --- |
+| `why_search` | The agent is about to change behaviour it does not understand. |
+| `why_line` | The agent is editing a specific line and needs the decision behind it. |
+| `why_file` | The agent is refactoring a file and needs every decision that shaped it. |
+| `why_risk` | The agent is choosing where to start, or where *not* to. |
+| `whylog_read` | The agent wants the whole distilled history in one read. |
+
+Add one line to your agent instructions, and the behaviour changes:
+
+```markdown
+Before changing a line you do not understand, call `why_line` (MCP: whygit).
+If a past decision contradicts your plan, say so before editing.
+```
+
+### WHYLOG.md 鈥?history your agent reads without being asked
+
+`whygit whylog --write` produces a Markdown file that is small enough to live in a
+repo and specific enough to change a decision:
+
+- **Load-bearing decisions** 鈥?ranked, each with the verbatim reason, date, commit, author, and the files it touches.
+- **The cursed files** 鈥?a table of where history is thickest.
+- **House rule** 鈥?the one-line convention (`WHY: ...`) that makes future commits explain themselves.
+
+It is generated from git, never hand-edited, and it diffs cleanly in review.
+Commit it, and every agent that starts in the repo gets the context for free 鈥?no MCP required.
+
+### CI gate
+
+```yaml
+- run: npx whygit check --base origin/main --min 0.6
+```
+
+Fails when fewer than 60% of newly added lines trace to a commit that stated a reason.
+It is a nudge, not a linter: the fix is one sentence in the commit body.
+
+## How it works
+
+```text
+git log (two passes: metadata + numstat)
+        鈹?        鈻?  signals: strip trailers, drop bot noise, de-duplicate squash-merge subjects,
+           keep sentences that contain a reason ("because", "so that", "to avoid",
+           "鐢变簬", "閬垮厤", "鍥炴粴" ...)
+        鈹?        鈻?  SQLite  .git/whygit/index.db   commits 路 files 路 decisions 路 FTS5 路 risk
+        鈹?        鈻?  ranking: BM25 脳 confidence 脳 churn 脳 recency 脳 fix-density 脳 noise penalties
+        鈹?        鈹溾攢鈹€ whygit why / story / cursed        (terminal)
+        鈹溾攢鈹€ whygit whylog                      (WHYLOG.md)
+        鈹斺攢鈹€ whygit mcp                         (agents)
+```
+
+**What a "decision" is:** a commit whose message contains a sentence explaining a
+choice. whygit does not interpret that sentence 鈥?it quotes it. If the message says
+nothing, the decision has low confidence and ranks below the ones that do.
+
+**Why it can be fast:** the whole index is built from two `git log` passes, and
+queries run against FTS5 in the same process. On a laptop, 4,884 commits index in
+~3 seconds and a query takes ~20 ms. No network, no model, no cache to warm.
+
+**What it will not do:** invent a reason, summarise code, or judge quality. If the
+history is silent, whygit says so 鈥?silence is a finding too.
+
+## Compared to
+
+| | Answers "why" | Cites the source | Works offline | Agent-native |
+| --- | :---: | :---: | :---: | :---: |
+| `git blame` | no | 鈥?| yes | no |
+| `git log` | only if you already know where to look | yes | yes | no |
+| LLM-generated docs | sometimes | rarely | no | partly |
+| **whygit** | **yes** | **yes (sha + file + line)** | **yes** | **yes (MCP + WHYLOG.md)** |
+
+## FAQ
+
+**Does it send my code anywhere?** No. whygit reads local git data and writes one
+SQLite file inside `.git/`. There is no network code path.
+
+**Does it need an LLM?** No. That is the point: a cited sentence from 2016 beats a
+confident paraphrase from a model.
+
+**Does it work on a shallow clone?** It runs, and it tells you the history is
+truncated (`whygit doctor`). Results are only as good as the history present.
+
+**Squash merges?** Handled: the repeated subject line is removed and the PR body is
+treated as the rationale.
+
+**Monorepos?** Yes. Paths are indexed as-is; `why <file>:<line>` works from any depth.
+
+**Does it modify my repository?** Only if you ask: `whylog --write`, `install`, and the
+index under `.git/`. History is read-only.
+
+## Limitations
+
+- Rationale can only be as good as commit messages. whygit makes silence visible; it cannot fill it.
+- Very large histories (500k+ commits) index in minutes, not seconds.
+- Renames are followed by path, not by content similarity: a file moved twice may have two histories.
+- The ranking is heuristic. It is tuned to prefer cited reasons over churn, and it will still be wrong sometimes 鈥?each result shows its citations so you can check.
+
+## Contributing
+
+```bash
+git clone https://github.com/carefreebit/whygit && cd whygit
+npm test          # 17 tests, no network
+npm run lint
+node bin/whygit.js why "..." --cwd /path/to/any/repo
+```
+
+Issues and PRs welcome 鈥?especially real-world ranking failures. Paste the query, the
+repo, and what should have ranked first.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+---
+
+<div align="center">
+
+If whygit saved you from deleting a load-bearing line, a star helps the next person
+find it.
+
+**[猸?Star whygit](https://github.com/carefreebit/whygit)**
+
+</div>

package/README.zh-CN.md

@@ -0,0 +1,264 @@
+<div align="center">
+
+# whygit
+
+**git blame 告诉你「谁」改的。whygit 告诉你「为什么」。**
+
+对着任意仓库跑一次，它把散落在 git 历史里的理由变成可引用的答案：
+文件、行号、commit、作者、日期，一个都不少。
+
+[![npm](https://img.shields.io/npm/v/whygit?color=cb3837)](https://www.npmjs.com/package/whygit)
+[![tests](https://github.com/carefreebit/whygit/actions/workflows/ci.yml/badge.svg)](https://github.com/carefreebit/whygit/actions/workflows/ci.yml)
+[![node](https://img.shields.io/badge/node-%3E%3D22.5-3c873a)](https://nodejs.org)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![MCP](https://img.shields.io/badge/MCP-ready-6b46c1)](#交给你的-agent)
+
+[English](README.md) · [快速开始](#快速开始) · [命令](#命令) · [Agent 接入](#交给你的-agent) · [原理](#它是怎么做到的)
+
+</div>
+
+---
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/carefreebit/whygit/main/docs/demo.svg" alt="whygit why &quot;cookie jar&quot; 终端演示" width="900">
+</p>
+
+<p align="center"><sub>真实输出：在 <code>psf/requests</code> 上执行 <code>whygit why "cookie jar"</code> —— 4,884 个 commit 索引 3 秒，回答 21 毫秒。</sub></p>
+
+这个答案一直躺在仓库里——2015 年某次 commit 的正文，此后九年没人读过。
+whygit 用 21 毫秒把它找出来：没有大模型，没有 API key，没有网络请求。
+
+## 它解决什么问题
+
+每个代码库里都有一批「看起来很蠢、其实很关键」的代码：
+一次显得多余的重试、一个看起来神经质的判空、一句像偷懒的 `sleep(2)`。
+
+- `git blame` 只回答**谁**、**什么时候**动了这一行，不回答为什么；
+- `git log` 是个只写不读的数据库，理由埋在 2016 年某条 commit 正文里；
+- 让大模型去总结 git 历史，它会**编出看起来合理的理由**。在代码库里，一个听起来对的错理由，比没有理由更危险；
+- 编码 Agent 受害最深：它们删掉重试、改写判空，半年后同一个 bug 回来——因为没有任何东西告诉它「这行是承重的」。
+
+whygit 只做一件事：把仓库**已经写下的**理由读出来，提取真正在解释决策的句子，
+送到两个真正有用的地方——**你的终端**，和 **Agent 的上下文窗口**。
+
+## 快速开始
+
+```bash
+npx whygit init                     # 扫一遍历史，5k commit 约 2 秒
+npx whygit why "retry on 503"       # 用自然语言问
+npx whygit why src/client.js:42     # 这一行到底为什么在这里
+npx whygit cursed                   # 反复出问题的文件排行
+npx whygit story src/client.js      # 单个文件从诞生到 HEAD 的一生
+npx whygit whylog --write           # 生成 WHYLOG.md，给 Agent 读的历史笔记
+```
+
+需要 **Node 22.5+**（用到内置的 `node:sqlite`）。零运行时依赖，无配置文件，
+无账号，无遥测。
+
+第一次运行会在 `.git/whygit/index.db` 建本地索引；之后每次都是增量更新，
+新 commit 会被自动补进来。
+
+## 命令
+
+| 命令 | 回答什么 |
+| --- | --- |
+| `whygit why <关键词>` | 这个行为为什么存在？按相关度排序，每条都带出处。 |
+| `whygit why <文件>:<行号>` | 这一行为什么还活着？blame + 背后的决策 + 这次改动还剩多少行在 HEAD。 |
+| `whygit story <文件>` | 一个文件的传记：出生、按年提交量、关键章节、谁一直在维护它。 |
+| `whygit cursed` | 风险地图：改动量 × 修复密度 × 作者分散度 × 新鲜度。重构前先看。 |
+| `whygit whylog --write` | 生成 `WHYLOG.md`：承重决策 + 高危文件，纯 Markdown。 |
+| `whygit check --base origin/main` | CI 门禁：新增代码行里，有多大比例能追溯到「说过为什么」的 commit。 |
+| `whygit mcp` | 基于 stdio 的 MCP 服务，Claude Code、Cursor、Codex 及任何 MCP 客户端可用。 |
+| `whygit install <agent>` | 写入 MCP 配置（`claude` / `cursor` / `vscode` / `agents` / `all`）。 |
+| `whygit doctor` | 自检：git、索引是否过期、是否浅克隆、WHYLOG 是否缺失。 |
+
+所有命令都支持 `--json`（给脚本用）和 `--cwd <path>`（指向别的仓库）。
+
+### `why <文件>:<行号>`
+
+```console
+$ whygit why src/requests/models.py:120
+
+   1. basics working
+    2012-12-15 · 366e8e84 · Kenneth Reitz · change
+    line 120 is 78 lines of this change, still in HEAD
+
+   2. Add hasattr checks for remaining protocol isinstance checks (#7505)
+    2026-06-09 · 6f66281a · change
+```
+
+这一行本身平平无奇。真正重要的是：它周围 78 行仍然来自 2012 年那次改动——
+也就是说，这里的结构是承重的，不是随手写的。
+
+### `story <文件>`
+
+```console
+$ whygit story src/requests/models.py
+
+  born 2011-05-14 · package refactor
+
+    2011  ██████████████████████████████████······  217
+    2012  ████████████████████████████████████████  254
+    2013  ██████████████··························   86
+    ...
+
+  717 commits · 202 authors · 154 fixes · 0 TODO markers
+  ─── the plot ──────────────────────────────────────────────────
+
+  2015-04-06  Copy a PreparedRequest's CookieJar reliably
+            By adding _copy_cookie_jar we can reliably copy cookie jars so that we
+            have an actual copy instead of the same instance on different prepared
+            requests.
+```
+
+### `cursed`
+
+```console
+$ whygit cursed
+
+   1  src/requests/models.py          ██████████████    8.1  717 commits · 202 authors · 154 fixes
+   2  src/requests/sessions.py        █████████████·    7.5  334 commits · 110 authors · 79 fixes
+   3  tests/test_requests.py          ████████████··    7.2  366 commits · 104 authors · 76 fixes
+```
+
+这不是代码质量评分，而是一张地图：标出历史密度最高的地方——在那里自信地重写，
+大概率是错的。
+
+## 交给你的 Agent
+
+不知道历史的 Agent 会重写承重代码；知道历史的 Agent 会先问对问题。一条命令接好：
+
+```bash
+npx whygit install claude     # .mcp.json
+npx whygit install cursor     # .cursor/mcp.json
+npx whygit install vscode     # .vscode/mcp.json
+npx whygit install agents     # 往 AGENTS.md 追加一段（任何 Agent 都认）
+npx whygit install all
+```
+
+如果 `whygit` 已在 `PATH` 里，加 `--local`（否则配置里用 `npx -y whygit@latest`）。
+
+MCP 服务暴露五个工具：
+
+| 工具 | 什么时候用 |
+| --- | --- |
+| `why_search` | Agent 即将改动一段它并不理解的行为。 |
+| `why_line` | Agent 正在编辑某一行，需要这行背后的决策。 |
+| `why_file` | Agent 要重构一个文件，需要塑造过它的全部决策。 |
+| `why_risk` | Agent 在挑起点，或者在挑「别碰哪里」。 |
+| `whylog_read` | Agent 想一口气读完蒸馏后的历史。 |
+
+在 Agent 的指令文件里加一行，行为就变了：
+
+```markdown
+改动任何你不理解的行之前，先调用 `why_line`（MCP：whygit）。
+如果历史决策和你的方案冲突，先说出来，再动手。
+```
+
+### WHYLOG.md —— Agent 不用被提醒就会读的历史
+
+`whygit whylog --write` 生成一份 Markdown：小到可以进仓库，具体到能改变一次决策。
+
+- **承重决策**：按重要性排序，每条都带原文理由、日期、commit、作者、涉及文件；
+- **高危文件**：历史最稠密的地方；
+- **仓库规矩**：一行约定（`WHY: ...`），让以后的 commit 自己解释自己。
+
+它由 git 生成、永不手改、在 review 里 diff 干净。提交进仓库后，
+每个在这个仓库里启动的 Agent 都免费获得上下文——**不需要 MCP**。
+
+### CI 门禁
+
+```yaml
+- run: npx whygit check --base origin/main --min 0.6
+```
+
+当新增代码行中能追溯到「说过理由」的 commit 的比例低于 60% 时失败。
+它不是 linter，只是提醒：修复方式是在 commit 正文里写一句话。
+
+## 它是怎么做到的
+
+```text
+git log（两遍：元数据 + numstat）
+        │
+        ▼
+  信号提取：去掉 trailer、过滤机器人噪音、去重 squash-merge 重复标题，
+           保留含因果词的句子（because / so that / to avoid / 由于 / 避免 / 回滚 ...）
+        │
+        ▼
+  SQLite  .git/whygit/index.db   commits · files · decisions · FTS5 · risk
+        │
+        ▼
+  排序：BM25 × 置信度 × 改动量 × 新鲜度 × 修复密度 × 噪音惩罚
+        │
+        ├── whygit why / story / cursed        （终端）
+        ├── whygit whylog                      （WHYLOG.md）
+        └── whygit mcp                         （Agent）
+```
+
+**什么叫一条「决策」**：commit message 里存在解释选择的句子。
+whygit 不解释这句话，只引用它。如果 message 什么都没说，这条决策置信度就低，
+排在说过理由的后面。
+
+**为什么快**：整个索引只来自两遍 `git log`，查询在同一个进程里打 FTS5。
+在普通笔记本上，4,884 个 commit 建索引约 3 秒，单次查询约 20 毫秒。
+没有网络、没有模型、没有缓存要预热。
+
+**它不会做什么**：编理由、总结代码、评判质量。历史沉默时，whygit 就说沉默——
+沉默本身也是一种结论。
+
+## 和其他方案比
+
+| | 回答「为什么」 | 给出处 | 可离线 | 为 Agent 而生 |
+| --- | :---: | :---: | :---: | :---: |
+| `git blame` | 否 | — | 是 | 否 |
+| `git log` | 只有你已经知道去哪找时 | 是 | 是 | 否 |
+| 大模型生成的文档 | 有时 | 很少 | 否 | 部分 |
+| **whygit** | **是** | **是（sha + 文件 + 行）** | **是** | **是（MCP + WHYLOG.md）** |
+
+## 常见问题
+
+**会把我的代码传到网上吗？** 不会。whygit 只读本地 git 数据，只往 `.git/` 里写一个 SQLite 文件，
+代码里没有任何网络调用路径。
+
+**需要大模型吗？** 不需要，这正是重点：一句 2016 年带出处的原话，胜过模型的自信转述。
+
+**浅克隆能用吗？** 能跑，但会明确告诉你历史被截断了（`whygit doctor`）。结果只和现存历史一样好。
+
+**squash merge 呢？** 已处理：去掉正文里重复的标题行，把 PR 描述当作理由。
+
+**monorepo？** 支持。路径按原样索引，`why <文件>:<行号>` 在任意层级都可用。
+
+**会改我的仓库吗？** 只在你明确要求时：`whylog --write`、`install`，以及 `.git/` 下的索引。
+历史始终只读。
+
+## 局限
+
+- 理由的上限就是 commit message 的质量。whygit 让沉默可见，但没法替你补上；
+- 超大历史（50 万+ commit）建索引是分钟级，不是秒级；
+- 重命名按路径追踪，不做内容相似度匹配：一个文件搬过两次，可能有两段历史；
+- 排序是启发式的，偏向「有出处的理由」而不是改动量，仍会出错——每条结果都带引用，方便你自己核对。
+
+## 参与贡献
+
+```bash
+git clone https://github.com/carefreebit/whygit && cd whygit
+npm test          # 17 个测试，不联网
+npm run lint
+node bin/whygit.js why "..." --cwd /path/to/any/repo
+```
+
+欢迎 issue 和 PR——尤其是真实的排序失败案例。请附上查询、仓库，以及你认为本应排第一的结果。
+
+## 许可证
+
+MIT，见 [LICENSE](LICENSE)。
+
+---
+
+<div align="center">
+
+如果 whygit 帮你拦下了一次「删掉承重代码」的操作，点个 star，能让下一个人找到它。
+
+**[⭐ Star whygit](https://github.com/carefreebit/whygit)**
+
+</div>

package/bin/whygit.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import process from 'node:process';
+import { main } from '../src/cli.js';
+
+main(process.argv.slice(2))
+  .then(function (code) { process.exitCode = code || 0; })
+  .catch(function (err) {
+    process.stderr.write('whygit: ' + (err && err.message ? err.message : String(err)) + '\n');
+    if (process.env.WHYGIT_DEBUG) console.error(err);
+    process.exitCode = 1;
+  });

package/docs/demo.svg

@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="900" height="570" viewBox="0 0 900 570" role="img" aria-label="whygit terminal demo">
+<defs><linearGradient id="bg" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#161b22"/><stop offset="1" stop-color="#0d1117"/></linearGradient></defs>
+<rect width="900" height="570" rx="14" fill="url(#bg)" stroke="#30363d"/>
+<rect width="900" height="42" rx="14" fill="#21262d"/><rect y="28" width="900" height="14" fill="#21262d"/>
+<circle cx="24" cy="21" r="6" fill="#ff5f56"/><circle cx="46" cy="21" r="6" fill="#ffbd2e"/><circle cx="68" cy="21" r="6" fill="#27c93f"/>
+<text x="450" y="26" text-anchor="middle" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="12" fill="#8b949e">whygit — psf/requests</text>
+<text x="30" y="74" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="13.5" fill="#7ee787" font-weight="600" xml:space="preserve">$ whygit why "cookie jar"</text>
+<text x="30" y="116" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="13.5" fill="#e6edf3" font-weight="600" xml:space="preserve">  whygit  psf/requests  4,884 commits</text>
+<text x="30" y="137" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="13.5" fill="#30363d" xml:space="preserve">  ────────────────────────────────────</text>
+<text x="30" y="200" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="13.5" fill="#f0f6fc" font-weight="600" xml:space="preserve">   1. Copy a PreparedRequest's CookieJar reliably</text>
+<text x="30" y="221" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="13.5" fill="#8b949e" xml:space="preserve">    2015-04-06 · 36093e69 · Ian Cordasco · change · 100% match</text>
+<text x="30" y="263" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="13.5" fill="#c9d1d9" xml:space="preserve">    By adding _copy_cookie_jar we can reliably copy cookie jars so that we have an</text>
+<text x="30" y="284" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="13.5" fill="#c9d1d9" xml:space="preserve">    actual copy instead of the same instance on different prepared requests.</text>
+<text x="30" y="326" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="13.5" fill="#79c0ff" xml:space="preserve">    requests/cookies.py  requests/models.py</text>
+<text x="30" y="347" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="13.5" fill="#58a6ff" text-decoration="underline" xml:space="preserve">    → https://github.com/psf/requests/commit/36093e69c70b9b24dd1e007befa35ad891313f51</text>
+<text x="30" y="389" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="13.5" fill="#f0f6fc" font-weight="600" xml:space="preserve">   2. Test and perfection for cookie handling.</text>
+<text x="30" y="410" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="13.5" fill="#8b949e" xml:space="preserve">    2013-02-11 · 2e316961 · Ian Cordasco · fix · 71% match</text>
+<text x="30" y="452" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="13.5" fill="#c9d1d9" xml:space="preserve">    I also fixed up some of the RequestsCookieJar methods so using</text>
+<text x="30" y="473" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="13.5" fill="#c9d1d9" xml:space="preserve">    jar.update(other_jar) works without a problem.</text>
+<text x="30" y="515" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="13.5" fill="#8b949e" xml:space="preserve">  2 of 15 decisions · 21ms · whygit why "cookie jar"</text>
+</svg>

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "whygit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Git blame tells you who. whygit tells you why. Turn git history into cited, agent-readable context.",
+  "type": "module",
+  "bin": {
+    "whygit": "bin/whygit.js"
+  },
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "files": [
+    "bin",
+    "src",
+    "docs",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/signals.test.js test/index.test.js",
+    "lint": "node scripts/lint.js"
+  },
+  "keywords": [
+    "git",
+    "blame",
+    "archaeology",
+    "why",
+    "mcp",
+    "ai-agents",
+    "claude-code",
+    "codex",
+    "cursor",
+    "context",
+    "knowledge-base",
+    "code-review",
+    "onboarding"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/carefreebit/whygit.git"
+  },
+  "homepage": "https://github.com/carefreebit/whygit#readme",
+  "bugs": {
+    "url": "https://github.com/carefreebit/whygit/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "lxh"
+}