rulemux 0.0.1 → 0.1.2

package/README.md

@@ -1,31 +1,257 @@
 # rulemux
 
-> 一份**中央真源**规则 → 投递到各家 AI coding agent（Claude Code / Trae / CodeBuddy / WorkBuddy / Codex / OpenCode / DeepSeek Harness）。
-> 效果与 token 与直接写 `AGENTS.md` 一致：**永不淡出、不累积、不用软链、加删文件自由**。
+> One set of rules, delivered to every AI coding agent.
+> Same effect and same token cost as writing `AGENTS.md` by hand — **never fades out, never accumulates, no symlinks, free to add and remove files**.
 
-## 这是什么
+[中文版](README.zh-CN.md) | [Design docs](docs/design/architecture.md)
 
-你有一份规则文档（编码约定、项目规矩……），希望每个 AI coding agent 在每个工作区都读到它，且效果和直接写进 `AGENTS.md` 一模一样。
-`rulemux` 负责把这份真源同步到各家 agent 的工作区规则目录 —— 一处管理，多处生效。
+---
 
-**核心做法**：hook 只当「投递员」，把真源文档**真实拷贝**进各 agent 原生加载的规则目录，由 harness 自己读 ⇒ 享有静态前缀语义，因此永不淡出、不累积。
-（为什么不靠 hook 注入：见 [`docs/design/architecture.md`](docs/design/architecture.md) §二）
+## 1. What is this
 
-## 安装
+You maintain a set of rule documents (coding conventions, project rules, …) and want every AI
+coding agent to read them in every workspace — with the exact same effect as if you had written
+`AGENTS.md` yourself.
 
-⬜ 待补（项目尚未落码）。
+`rulemux` takes the source files you list in a config and copies them into each agent's **native
+workspace rules directory**. You manage them in one place; they take effect everywhere.
 
-## 用法
+- rulemux **does not own or maintain any rule content**. Your source files stay yours — rulemux
+  only copies them. Which agents / workspaces they apply to is declared in your config.
+- **The session hook is only the courier.** It is not used to inject text. Files are really copied
+  into the directory the agent loads natively, so they enjoy static-prefix semantics: they never
+  fade out mid-conversation, and they never accumulate.
+- Invariants: **no symlinks** (real copies only) and **free add/remove** (delete a source from the
+  config and its copy disappears on the next sync).
 
-⬜ 待补（项目尚未落码）。
+> Why not "just inject with a hook"? Hook injection lands in the dynamic part of the context: it
+> gets summarised away on compaction (fades out) or re-appended every turn (token blow-up).
+> See [design/architecture.md](docs/design/architecture.md) §一.
 
-## 文档
+---
 
-| 想看 | 去哪 |
+## 2. Supported scope
+
+rulemux ships **one adapter per agent**, and an adapter is only installable once its rules
+directory and hook location have been confirmed by a real canary test. Today:
+
+| Agent | Tier | Rules directory | Status |
+|---|---|---|---|
+| **codebuddy** | Tier-1 (real copy) | `.codebuddy/rules/` | ✅ **Verified — installable** |
+| **workbuddy** | Tier-1 (real copy) | `.codebuddy/rules/` (shared with CodeBuddy) | ✅ **Verified — installable** |
+| claude (Claude Code) | Tier-1 | `.claude/rules/` | ⚠️ registered, **not verified yet** — cannot be installed |
+| trae (Trae) | Tier-1 | `.trae/rules/` | ⚠️ registered, **not verified yet** — cannot be installed |
+| codex | Tier-2 (injection) | none — injects into context | ⚠️ registered, **not verified yet** |
+| opencode | Tier-2 (injection) | none — injects into context | ⚠️ registered, **not verified yet** |
+
+- `rulemux init` **refuses** any agent that is not verified — it will not half-install an adapter
+  whose behaviour has not been proven. `rulemux doctor` marks unverified agents with ⚠.
+- **Tier-2 is a deliberate downgrade** for agents that have no rules directory (they only read a
+  single `AGENTS.md`). It injects via the session hook and never touches your own `AGENTS.md`, but
+  it cannot satisfy the "never fades out" bar. See
+  [design/features/hook-injection.md](docs/design/features/hook-injection.md).
+
+---
+
+## 3. Install
+
+rulemux is a **single Go binary with zero third-party dependencies**.
+
+```bash
+# a) from a GitHub Release (recommended): put the binary on your PATH
+#    e.g. /usr/local/bin/rulemux   (Windows: rulemux.exe)
+
+# b) from source
+go install github.com/cq-guojia/rulemux@latest
+# or
+git clone https://github.com/cq-guojia/rulemux.git && cd rulemux && go build -o rulemux .
+
+# c) via npm (convenience channel that puts the binary on your PATH)
+npm i -g rulemux
+```
+
+There is **no auto-update**. Upgrades are manual and handled by your package manager
+(`go install …@latest`, Homebrew/Scoop/apt later on). This is a deliberate decision — see
+[design/requirements.md](docs/design/requirements.md) §五.
+
+---
+
+## 4. Quick start
+
+```bash
+# 1. Install the session hook for an agent (--agent is REQUIRED)
+rulemux init --agent codebuddy
+#    First run also writes a sample config to ~/.rulemux/config.toml
+
+# 2. Edit ~/.rulemux/config.toml and point `path` at your real rule files
+
+rulemux doctor    # 3. Self-check: binary/PATH, agents, config validity
+rulemux verify    # 4. Canary check: drop a probe and ask the agent to recite its token
+
+# From now on every new session triggers `rulemux sync --agent codebuddy` automatically.
+
+rulemux uninstall --agent codebuddy   # remove rulemux again (--yes skips the confirmation)
+```
+
+**Where the hook goes:** into the **user-level host config** `~/.codebuddy/settings.json` (the same
+place a tool like Hindsight registers itself). **Install once, and it applies to every workspace** —
+you do *not* re-run `init` per project. When it fires, rulemux uses the current workspace (its cwd)
+to match the `workspace` entries in your config and decides what to deliver.
+
+---
+
+## 5. Configuration
+
+Config file: `~/.rulemux/config.toml` (override with `--config <path>` on any command).
+
+### 5.1 Each `[[source]]`
+
+| Field | Meaning |
+|---|---|
+| `path` | Source file(s), anywhere on disk. Single value or a list. A list shares the `agents`/`workspace` below. |
+| `agents` | Which agents receive this batch. Omitted = all supported agents. |
+| `workspace` | Which workspaces these rules apply to. Omitted / `"*"` / `"**"` / `"all"` = every workspace. Single value, a list, or a glob. |
+
+Globbing follows the usual rules: `*` is one path segment, `**` spans segments and may appear in
+the middle — e.g. `workspace = "/abs/**/B"` matches a directory named `B` at any depth.
+
+```toml
+[[source]]
+path = ["/your/rules/a.md", "/your/rules/b.md"]
+agents = ["codebuddy"]              # omit to target every supported agent
+# workspace is omitted => every workspace
+# workspace = ["/path/to/proj-a", "/path/to/proj-b"]
+# workspace = "/abs/**/B"           # glob: any depth, named B
+```
+
+### 5.2 Bundling with "groups" (optional)
+
+When you have many files, bundle them and reference the bundle by name.
+
+```toml
+# ---- File groups ---------------------------------------------------------
+[[file_group]]
+name  = "base"
+path  = ["/your/rules/team-conventions.md", "/your/rules/style.md"]
+
+[[file_group]]
+name = "proj"
+use  = ["base"]                     # nests the base group (a list: ["base", "dev"])
+path = ["/your/rules/project-a.md"]
+
+# ---- Workspace groups ----------------------------------------------------
+[[workspace_group]]
+name      = "dev"
+workspace = ["/path/to/proj-1", "/path/to/proj-2"]
+
+# ---- Use them ------------------------------------------------------------
+[[source]]
+groups           = ["base", "proj"]      # expands to every file in those groups
+path             = ["/your/rules/extra.md"]   # mixing is allowed: groups + standalone files
+agents           = ["codebuddy"]
+workspace_groups = ["dev"]               # expands to every workspace in the group
+workspace        = ["/path/to/standalone"]    # also allowed alongside workspace_groups
+```
+
+Things worth knowing:
+
+- **`use` is a list** — `use = ["dev", "qa"]` reuses several groups at once, and groups nest
+  (A pulls in B plus its own files).
+- **Mixing is allowed**: `groups` with `path`, and `workspace_groups` with `workspace`, in the same
+  source. The result is the union.
+- **Duplicates are harmless** — everything is deduplicated by value, so each file is processed once.
+- File groups and workspace groups are **separate namespaces**; the same name may be used in both.
+
+### 5.3 What sync does, and what it never touches
+
+On every sync rulemux computes the set of prefixed files that should exist, then removes any
+`.rulemux__*` file that is not in that set, copies/overwrites the ones that are missing or changed,
+and skips the rest.
+
+- Destination name: `.rulemux__` + source basename (a short hash is appended on name collisions).
+- **Your source files are only ever read** — never modified or deleted.
+- **Files without the `.rulemux__` prefix in the rules directory are never touched**, so your own
+  rule files stay safe.
+
+---
+
+## 6. Uninstalling
+
+```bash
+rulemux uninstall --agent codebuddy          # one agent (comma-separated for several)
+rulemux uninstall --off                      # every agent (--all is the same)
+rulemux uninstall --agent codebuddy --yes    # skip the confirmation prompt
+```
+
+It removes rulemux's own hook entry (other tools' hooks in the same file are preserved) and deletes
+the `.rulemux__*` files it previously delivered. Because the hook lives in the user-level config,
+rulemux also **revisits every workspace recorded in its ledger** (`~/.rulemux/workspaces.json`) and
+cleans those too — otherwise, with the hook gone, that residue could never be removed again. You are
+shown the list of workspaces before anything is deleted.
+
+---
+
+## 7. Commands
+
+| Command | What it does |
+|---|---|
+| `rulemux sync [--agent <id>] [--config <path>] [--workspace <dir>]` | Sync rules (called by each agent's SessionStart hook) |
+| `rulemux inject --agent <id> [--config <path>]` | Tier-2: print rules to stdout for hook injection |
+| `rulemux init --agent <id[,id...]> [--config <path>] [--workspace <dir>]` | Write a sample config and install the SessionStart hook |
+| `rulemux doctor [--config <path>] [--workspace <dir>]` | Environment self-check |
+| `rulemux verify --agent <id> [--clean] [--workspace <dir>]` | Canary acceptance test |
+| `rulemux uninstall --agent <id[,id...]> \| --off \| --all [--yes]` | Remove hooks and delivered files |
+
+Run `rulemux` with no arguments for the full help.
+
+---
+
+## 8. Roadmap
+
+Ongoing work and what comes next are tracked in [docs/PROGRESS.md](docs/PROGRESS.md). In short:
+
+- **More agents** — finish the adapters that are already registered but unverified:
+  - **Trae** (`.trae/rules/`) and **Claude Code** (`.claude/rules/`) as Tier-1;
+  - **Codex** and **OpenCode** as Tier-2 injection.
+  Each one needs its rules directory and hook location confirmed by a real canary run before it is
+  switched on. The checklist for adding an agent lives in
+  [design/features/agent-onboarding.md](docs/design/features/agent-onboarding.md).
+- **Distribution** — GitHub Actions cross-compilation plus Release artifacts (this also feeds the
+  npm package), and publishing the npm package properly.
+- **Verification tooling** — make the canary check repeatable per agent.
+- Rule content transformation, templating, and automatic self-update are **explicitly out of scope**
+  ([design/requirements.md](docs/design/requirements.md) §五).
+
+---
+
+## 9. Releasing (maintainers)
+
+```bash
+npm version patch|minor|major   # bumps package.json and creates the git tag v0.x.y
+git push --follow-tags
+```
+
+Pushing the tag triggers [`.github/workflows/release.yml`](.github/workflows/release.yml):
+cross-compile all platform binaries, attach them to a GitHub Release, and publish the
+npm package with the tag's version. Set the `NPM_TOKEN` repository secret to enable
+the npm step (it is skipped with a warning if absent). A plain CI run
+([`ci.yml`](.github/workflows/ci.yml)) runs build/vet/tests/smoke on every push.
+
+---
+
+## 10. License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+## 10. Documentation
+
+| Want to read | Where |
 |---|---|
-| 现在做到哪、欠什么 | [`docs/PROGRESS.md`](docs/PROGRESS.md) |
-| 文档怎么摆、怎么写 | [`docs/README.md`](docs/README.md) |
-| **用户要什么**（需求 / 验收标准） | [`docs/design/requirements.md`](docs/design/requirements.md) |
-| 设计（核心原理 / 选型 / 命名） | [`docs/design/architecture.md`](docs/design/architecture.md) |
-| 功能列表 | [`docs/design/features.md`](docs/design/features.md) |
-| 各家 agent 的规则目录 | [`docs/design/external/agent-rules-dirs.md`](docs/design/external/agent-rules-dirs.md) |
+| What the user actually wants (requirements / acceptance) | [docs/design/requirements.md](docs/design/requirements.md) |
+| Why it is designed this way | [docs/design/architecture.md](docs/design/architecture.md) |
+| Feature list | [docs/design/features.md](docs/design/features.md) |
+| Checklist for adding a new agent | [docs/design/features/agent-onboarding.md](docs/design/features/agent-onboarding.md) |
+| Each agent's rules directory (external facts) | [docs/design/external/agent-rules-dirs.md](docs/design/external/agent-rules-dirs.md) |
+| Current progress and open items | [docs/PROGRESS.md](docs/PROGRESS.md) |

package/README.zh-CN.md

@@ -0,0 +1,241 @@
+# rulemux
+
+> 一份规则，投递到各家 AI coding agent。
+> 效果与 token 与直接写 `AGENTS.md` 一致：**永不淡出、不累积、不用软链、加删文件自由**。
+
+[English](README.md) | [设计文档](docs/design/architecture.md)
+
+---
+
+## 1. 这是什么
+
+你维护着一套规则文档（编码约定、项目规矩……），希望每个 AI coding agent 在每个工作区都读到它，
+且效果和直接写进 `AGENTS.md` 一模一样。
+
+`rulemux` 把你在配置里列出的源文件，复制进各 agent **原生的工作区规则目录** —— 一处管理，多处生效。
+
+- rulemux **不持有、不维护任何规则内容**。源文件完全由你维护，rulemux 只负责复制；
+  「适用于哪些 agent / 哪些工作区」在你的配置里声明。
+- **会话钩子只当「投递员」，不用来注入文本**。文件是真正拷进 agent 原生加载的目录，
+  因此享有静态前缀语义 —— 不会随对话老化淡出，也不会每轮累积。
+- 底线：**不用软链**（一律真实拷贝）、**加删自由**（配置里删掉某源文件，下次同步它的副本即消失）。
+
+> 为什么不直接用钩子注入？注入落在上下文的动态区，压缩时会被摘要掉（淡出），
+> 或每轮追加（token 爆炸）。见 [`docs/design/architecture.md`](docs/design/architecture.md) §一。
+
+---
+
+## 2. 支持范围
+
+rulemux **每个 agent 一套适配器**；只有「规则目录 + 钩子落点」经真实 canary 实测坐实的 agent
+才允许安装。当前：
+
+| Agent | 层级 | 规则目录 | 状态 |
+|---|---|---|---|
+| **codebuddy** | Tier-1（真实拷贝） | `.codebuddy/rules/` | ✅ **已验证，可安装** |
+| **workbuddy** | Tier-1（真实拷贝） | `.codebuddy/rules/`（与 CodeBuddy 共用） | ✅ **已验证，可安装** |
+| claude（Claude Code） | Tier-1 | `.claude/rules/` | ⚠️ 已注册，**尚未验证**，不可安装 |
+| trae（Trae） | Tier-1 | `.trae/rules/` | ⚠️ 已注册，**尚未验证**，不可安装 |
+| codex | Tier-2（注入） | 无 —— 注入上下文 | ⚠️ 已注册，**尚未验证** |
+| opencode | Tier-2（注入） | 无 —— 注入上下文 | ⚠️ 已注册，**尚未验证** |
+
+- `rulemux init` **会拒绝**未验证的 agent —— 不会给你装一个行为未经验证的半成品。
+  `rulemux doctor` 会给未验证的 agent 标 ⚠。
+- **Tier-2 是刻意的降级**：面向没有规则目录、只认单个 `AGENTS.md` 的 agent，走会话钩子注入，
+  且绝不碰你自己的 `AGENTS.md`；但它满足不了「永不淡出」。见
+  [`docs/design/features/hook-injection.md`](docs/design/features/hook-injection.md)。
+
+---
+
+## 3. 安装
+
+rulemux 是**零第三方依赖的 Go 单二进制**。
+
+```bash
+# a) 从 GitHub Release 取预编译产物（推荐），放到 PATH
+#    例如 /usr/local/bin/rulemux（Windows 用 rulemux.exe）
+
+# b) 从源码
+go install github.com/cq-guojia/rulemux@latest
+# 或
+git clone https://github.com/cq-guojia/rulemux.git && cd rulemux && go build -o rulemux .
+
+# c) 通过 npm（把二进制放进 PATH 的便捷通道）
+npm i -g rulemux
+```
+
+**没有自动更新**。升级手动、交给包管理器（`go install …@latest`，将来 Homebrew / Scoop / apt）。
+这是刻意决策，见 [`docs/design/requirements.md`](docs/design/requirements.md) §五。
+
+---
+
+## 4. 快速开始
+
+```bash
+# 1. 为指定 agent 安装会话钩子（--agent 必填）
+rulemux init --agent codebuddy
+#    首次运行还会生成示例配置 ~/.rulemux/config.toml
+
+# 2. 编辑 ~/.rulemux/config.toml，把 path 改成你真实的规则文件
+
+rulemux doctor    # 3. 自检：二进制/PATH、各 agent 状态、配置合法性
+rulemux verify    # 4. canary 验收：投放探针，开新会话让 agent 念出暗号
+
+# 此后每次开新会话，都会自动触发 rulemux sync --agent codebuddy
+
+rulemux uninstall --agent codebuddy   # 卸载（--yes 跳过确认）
+```
+
+**钩子装在哪**：装进 **user 级 host 配置** `~/.codebuddy/settings.json`（与 Hindsight 的落点同类）。
+**一次安装、对所有工作区生效**，不必每个项目再跑一次 `init`。触发时 rulemux 以当前工作区（cwd）
+去匹配配置里的 `workspace` 条目，决定投递哪些规则。
+
+---
+
+## 5. 配置说明
+
+配置文件：`~/.rulemux/config.toml`（各命令均可用 `--config <path>` 指定其它路径）。
+
+### 5.1 每条 `[[source]]`
+
+| 字段 | 含义 |
+|---|---|
+| `path` | 源文件，磁盘任意位置；单个值或数组。数组内文件共享下面的 `agents` / `workspace` |
+| `agents` | 投递给哪些 agent；省略 = 全部已支持的 agent |
+| `workspace` | 适用哪些工作区；省略 / `"*"` / `"**"` / `"all"` = 所有工作区；单个值、数组或 glob |
+
+glob 沿用业界惯例：`*` 匹配单个路径段，`**` 跨段递归且可出现在中间 ——
+例如 `workspace = "/abs/**/B"` 匹配任意深度下名为 `B` 的目录。
+
+```toml
+[[source]]
+path = ["/你的规则/a.md", "/你的规则/b.md"]
+agents = ["codebuddy"]              # 省略则投递给全部已支持 agent
+# workspace 省略 => 所有工作区
+# workspace = ["/path/to/proj-a", "/path/to/proj-b"]
+# workspace = "/abs/**/B"           # glob：任意深度、名为 B
+```
+
+### 5.2 用「组」打包（可选）
+
+文件多了之后，可以打包成组，按组名引用。
+
+```toml
+# ---- 文件组 --------------------------------------------------------------
+[[file_group]]
+name  = "base"
+path  = ["/你的规则/team-conventions.md", "/你的规则/style.md"]
+
+[[file_group]]
+name = "proj"
+use  = ["base"]                     # 嵌套引用 base 组（数组：["base", "dev"]）
+path = ["/你的规则/project-a.md"]
+
+# ---- 工作区分组 ----------------------------------------------------------
+[[workspace_group]]
+name      = "dev"
+workspace = ["/path/to/proj-1", "/path/to/proj-2"]
+
+# ---- 引用它们 ------------------------------------------------------------
+[[source]]
+groups           = ["base", "proj"]        # 展开成这些组里的所有文件
+path             = ["/你的规则/extra.md"]   # 允许混合：组 + 单独文件
+agents           = ["codebuddy"]
+workspace_groups = ["dev"]                 # 展开成组内的所有工作区
+workspace        = ["/path/to/standalone"] # 也可与 workspace_groups 同时写
+```
+
+要点：
+
+- **`use` 是数组** —— `use = ["dev", "qa"]` 一次复用多个组，且支持嵌套（A 组引入 B 组再加自己的文件）。
+- **允许混合书写**：同一条 source 里 `groups` 可与 `path` 并存，`workspace_groups` 可与 `workspace` 并存，结果取并集。
+- **重复无害** —— 最终按值去重，每个文件只处理一次。
+- 文件组与工作区分组是**两套独立命名空间**，允许同名。
+
+### 5.3 同步做了什么，以及绝不碰什么
+
+每次同步：算出「应该存在的带前缀文件集合」，目标目录里不在这个集合中的 `.rulemux__*` 一律删除（删残留），
+缺失或内容不一致的复制/覆盖，其余跳过。
+
+- 目标文件名：`.rulemux__` + 源 basename（同名冲突时追加短 hash）。
+- **源文件只被读取** —— 绝不修改、绝不删除。
+- **规则目录里不带 `.rulemux__` 前缀的文件绝不触碰**，你自己的规则文件始终安全。
+
+---
+
+## 6. 卸载
+
+```bash
+rulemux uninstall --agent codebuddy          # 单个 agent（逗号分隔可多个）
+rulemux uninstall --off                      # 全部 agent（--all 等价）
+rulemux uninstall --agent codebuddy --yes    # 跳过交互确认
+```
+
+它会移除 rulemux 自己的钩子条目（同一文件里其它工具的钩子会保留），并删掉此前投递的 `.rulemux__*` 文件。
+由于钩子在 user 级配置里，rulemux 还会**按账本（~/.rulemux/workspaces.json）回访所有记录过的工作区**
+一并清理 —— 否则钩子一去，那些残留就再没机会被删掉了。删除前会把要回访的工作区列表给你确认。
+
+---
+
+## 7. 命令一览
+
+| 命令 | 作用 |
+|---|---|
+| `rulemux sync [--agent <id>] [--config <path>] [--workspace <dir>]` | 同步规则（由各 agent 的 SessionStart 钩子调用） |
+| `rulemux inject --agent <id> [--config <path>]` | Tier-2：把规则输出到 stdout 供钩子注入 |
+| `rulemux init --agent <id[,id...]> [--config <path>] [--workspace <dir>]` | 生成示例配置并安装 SessionStart 钩子 |
+| `rulemux doctor [--config <path>] [--workspace <dir>]` | 环境自检 |
+| `rulemux verify --agent <id> [--clean] [--workspace <dir>]` | canary 验收 |
+| `rulemux uninstall --agent <id[,id...]> \| --off \| --all [--yes]` | 移除钩子与已投递文件 |
+
+直接运行 `rulemux`（不带参数）可看完整帮助。
+
+---
+
+## 8. 后续计划
+
+在办事项见 [`docs/PROGRESS.md`](docs/PROGRESS.md)。概要：
+
+- **接入更多 agent** —— 补齐已注册但尚未验证的适配器：
+  - **Trae**（`.trae/rules/`）、**Claude Code**（`.claude/rules/`）走 Tier-1；
+  - **Codex**、**OpenCode** 走 Tier-2 注入。
+  每个 agent 都要先经真实 canary 坐实「规则目录 + 钩子落点」才开放。
+  接入一个新 agent 的完整清单见
+  [`docs/design/features/agent-onboarding.md`](docs/design/features/agent-onboarding.md)。
+- **分发** —— GitHub Actions 交叉编译 + Release 产物（同时供 npm 包使用），并正式发布 npm 包。
+- **验证工具** —— 让 canary 验收对每个 agent 可重复执行。
+- 规则内容改写/模板渲染、以及自动自我更新，**明确不做**
+  （[`docs/design/requirements.md`](docs/design/requirements.md) §五）。
+
+---
+
+## 9. 发版（维护者）
+
+```bash
+npm version patch|minor|major   # 更新 package.json 并创建 git tag v0.x.y
+git push --follow-tags
+```
+
+推送 tag 会触发 [`.github/workflows/release.yml`](.github/workflows/release.yml)：
+自动交叉编译全部平台二进制、挂到 GitHub Release、并按 tag 版本发布 npm 包。
+需在仓库 Secrets 里配置 `NPM_TOKEN` 才会发布 npm（未配置时跳过并告警）。
+普通的 CI（[`ci.yml`](.github/workflows/ci.yml)）在每次 push 时跑 build/vet/测试/冒烟。
+
+---
+
+## 10. 许可证
+
+MIT —— 见 [LICENSE](LICENSE)。
+
+---
+
+## 10. 文档索引
+
+| 想看什么 | 去哪 |
+|---|---|
+| 用户到底要什么（需求 / 验收标准） | [`docs/design/requirements.md`](docs/design/requirements.md) |
+| 为什么这么设计 | [`docs/design/architecture.md`](docs/design/architecture.md) |
+| 功能列表 | [`docs/design/features.md`](docs/design/features.md) |
+| 接入新 agent 的清单 | [`docs/design/features/agent-onboarding.md`](docs/design/features/agent-onboarding.md) |
+| 各家 agent 的规则目录（外部事实） | [`docs/design/external/agent-rules-dirs.md`](docs/design/external/agent-rules-dirs.md) |
+| 当前进度与未决项 | [`docs/PROGRESS.md`](docs/PROGRESS.md) |

package/bin/rulemux.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+"use strict";
+
+// npm launcher for rulemux.
+//
+// rulemux itself is a single Go binary with no runtime dependencies. This shim
+// exists only so that `npm i -g rulemux` puts a working `rulemux` command on your
+// PATH. It resolves the real binary in this order:
+//
+//   1. a binary bundled for this platform in ../dist/ (produced by scripts/build-dist.sh)
+//   2. a `rulemux` binary already on your PATH (e.g. installed from a GitHub Release)
+//   3. otherwise: print install instructions and exit non-zero
+//
+// It never rewrites your arguments and always forwards the child's exit code.
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+function platformKey() {
+  const plat = process.platform === "win32" ? "windows" : process.platform;
+  let arch = process.arch;
+  if (arch === "x64") arch = "amd64";
+  else if (arch === "ia32") arch = "386";
+  return `${plat}-${arch}`;
+}
+
+function bundledCandidates() {
+  const ext = process.platform === "win32" ? ".exe" : "";
+  const key = platformKey();
+  return [
+    path.join(__dirname, "..", "dist", `rulemux-${key}${ext}`),
+    // Some cross-builds use the Go default naming; keep a couple of aliases.
+    path.join(__dirname, "..", "dist", `rulemux-${process.platform}-${process.arch}${ext}`),
+  ];
+}
+
+function onPath() {
+  const cmd = process.platform === "win32" ? "where" : "which";
+  const r = spawnSync(cmd, ["rulemux"], { stdio: "ignore" });
+  return r.status === 0 ? "rulemux" : null;
+}
+
+function resolve() {
+  for (const c of bundledCandidates()) {
+    if (fs.existsSync(c)) return c;
+  }
+  return onPath();
+}
+
+function main() {
+  const bin = resolve();
+  if (!bin) {
+    process.stderr.write(
+      "rulemux: no rulemux binary found.\n" +
+        "\n" +
+        "Install one of these first:\n" +
+        "  go install github.com/cq-guojia/rulemux@latest\n" +
+        "  or download a binary from https://github.com/cq-guojia/rulemux/releases\n" +
+        "  and make sure it is on your PATH.\n"
+    );
+    process.exit(1);
+  }
+
+  // npm tarballs do not always preserve the executable bit; be defensive.
+  if (process.platform !== "win32" && fs.existsSync(bin)) {
+    try {
+      fs.chmodSync(bin, 0o755);
+    } catch (_) {
+      /* ignore: it may already be fine, or the fs may be read-only */
+    }
+  }
+
+  const r = spawnSync(bin, process.argv.slice(2), { stdio: "inherit" });
+  if (r.error) {
+    process.stderr.write(`rulemux: failed to run ${bin}: ${r.error.message}\n`);
+    process.exit(1);
+  }
+  process.exit(r.status === null ? 1 : r.status);
+}
+
+main();

package/package.json

@@ -1,18 +1,42 @@
 {
   "name": "rulemux",
-  "version": "0.0.1",
-  "description": "一份中央真源规则 → 同步到各家 AI coding agent 的工作区规则目录；效果与 token 与直接写 AGENTS.md 一致。",
+  "version": "0.1.2",
+  "description": "One set of rules, delivered to every AI coding agent: copies the rule files you declare into each agent's native workspace rules directory, with the same effect and token cost as writing AGENTS.md by hand.",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cq-guojia/rulemux.git"
   },
+  "homepage": "https://github.com/cq-guojia/rulemux#readme",
+  "bugs": {
+    "url": "https://github.com/cq-guojia/rulemux/issues"
+  },
+  "bin": {
+    "rulemux": "bin/rulemux.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build:dist": "bash scripts/build-dist.sh",
+    "prepublishOnly": "npm run build:dist"
+  },
+  "engines": {
+    "node": ">=16"
+  },
   "keywords": [
-    "agents",
+    "rulemux",
     "rules",
+    "agents",
     "agents-md",
-    "claude-code",
+    "ai-coding-agent",
     "codebuddy",
+    "workbuddy",
+    "claude-code",
     "trae",
     "codex",
     "opencode",