docsweep 0.1.0__tar.gz → 0.2.0__tar.gz

{docsweep-0.1.0 → docsweep-0.2.0}/CHANGELOG.md

@@ -3,6 +3,43 @@
 本ファイルは [Keep a Changelog](https://keepachangelog.com/ja/1.1.0/) の考え方を緩く参照しています。
 バージョニングは [SemVer](https://semver.org/lang/ja/) に従います。
 
+## [0.2.0] - 2026-07-03
+
+### Added
+
+- **Web UI の英語対応**（plan_v0.2.0-english-support）。看板・設定モーダル・ピッカー・
+  brief / capture / cross / graph / resurrect の全画面文言を ja / en 二言語化
+  （サーバー側 `docsweep/server/i18n.py`・JS 側 `static/i18n.js` の二層辞書）。
+  言語は設定モーダル（⚙）の「日本語 / English」トグルで切替でき、cookie
+  `docsweep_lang` に保存される（`~/.docsweep/config.yaml` の `lang:` は変更しない）。
+  解決順は `?lang=` クエリ > cookie > `config.lang` > ja。ピッカーの状態ラベルは
+  `.docsweep.yaml` の states 二言語辞書から lang 解決するようになった。
+- **README.en.md**（英語版 README）を追加し、README.md と相互リンク。
+- **About & Licenses 表記**を設定モーダル末尾に追加（アプリ情報・MIT ライセンス表記・
+  同梱 OSS: htmx / CDN 参照: cytoscape.js / pip 依存の三層を UI から確認できる。
+  正本は NOTICES.md — CDN 節を追記）。
+- **Web UI からのスキャンルート管理**（plan_web-roots-management）。設定モーダルに
+  Scan roots セクションを追加し、親ディレクトリ・個別プロジェクトフォルダのどちらも
+  追加・削除できる（`POST /api/config/roots`）。runtime に即反映しつつ
+  `~/.docsweep/config.yaml` の `roots:` キーだけを surgical に書き換えて永続化する
+  （他キー・コメントは温存）。最後の 1 個の root は削除不可。
+
+- 注入文言（inject）の英語対応。guidance 導線・due ルール節・ラベル節・AGENTS.md ポインタ・
+  管理注記・`.docsweep.yaml` / `~/.docsweep/config.yaml` ひな型コメントを ja / en の二言語化し、
+  CLI `inject --lang {ja,en}`（プロジェクト注入では preset の言語を上書き、`--global` の既定は ja）と
+  MCP `inject` / `inject_global` の `lang` パラメータを追加。状態ラベルは従来から二言語辞書を
+  持っていたため、`lang: en` でラベルも `[Planned]` / `[Done]` 等の英語表記になる。
+
+### Changed
+
+- トップバーの「看板（カンバン）/ Kanban」サブタイトル表記を撤去（バージョン表示のみ残す）。
+- `inject --global` の guidance に対応期日（`due:`）ルール節を同梱（guidance_version 3）。
+  従来 due ルールはプロジェクト inject のラベル節にのみ含まれ、プロジェクト注入していない
+  リポジトリでは AI が frontmatter を付けられなかった。due 節をラベル節から導線（guidance）側へ
+  移設し、既定=グローバル 1 回で全プロジェクトに効く／グローバルに寄せたくない場合は
+  プロジェクト inject（既定）で同内容が入る、の切り分けを既存フラグ（`--global` / `--no-guidance`）
+  だけで完結させた。
+
 ## [0.1.0] - 2026-07-03
 
 初回リリース。AI コーディングツール（Claude Code / Codex 等）が生成する

{docsweep-0.1.0 → docsweep-0.2.0}/NOTICES.md

@@ -30,6 +30,15 @@ Permission to use, copy, modify, and/or distribute this software for any purpose
 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 ```
 
+## Loaded from CDN (not bundled)
+
+### cytoscape.js 3.30.0
+
+- 用途: Web UI の graph ページのネットワーク可視化
+- 読込元: `https://unpkg.com/cytoscape@3.30.0/dist/cytoscape.min.js`（実行時に CDN から取得・配布物には含まれない）
+- 出典: https://github.com/cytoscape/cytoscape.js
+- ライセンス: **MIT License**（同梱していないため転載義務はないが、利用の透明性のため記録）
+
 ## Runtime dependencies (not bundled — pulled by pip)
 
 参考。これらは wheel に含まれず、ユーザーの `pip install` 時に PyPI から個別に取得されます。

{docsweep-0.1.0 → docsweep-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docsweep
-Version: 0.1.0
+Version: 0.2.0
 Summary: Sweep, triage and archive AI coding agents' plan/bugfix/pending Markdown across projects.
 Project-URL: Homepage, https://github.com/ishizakahiroshi/docsweep
 Project-URL: Repository, https://github.com/ishizakahiroshi/docsweep
@@ -52,6 +52,8 @@ Description-Content-Type: text/markdown
 
 # docsweep
 
+> English version: [README.en.md](README.en.md)
+
 AI コーディングツール（Claude Code / Codex 等）が生成する `plan_*.md` / `bugfix_*.md` /
 `pending_*.md` の **蓄積・陳腐化問題を解決する** クロスプラットフォーム CLI + Web UI ツール。
 
@@ -326,9 +328,10 @@ python -m docsweep inject --project ./foo --preset claude-jp
 python -m docsweep inject --project ./foo --no-guidance   # 導線を省きラベル節だけ（導線をグローバルに寄せる場合）
 python -m docsweep eject  --project ./foo                  # 管理ブロックだけ剥がす（手書きは温存。--purge で .docsweep.yaml も）
 
-# 個人グローバルへ「セッション開始時に triage を読む」導線を一度だけ注入（全プロジェクトで有効）
+# 個人グローバルへ「セッション開始時に triage を読む」導線＋due ルールを一度だけ注入（全プロジェクトで有効）
 python -m docsweep inject --global                         # 既定 agent=claude（~/.claude/CLAUDE.md に @import 1 行）
 python -m docsweep inject --global --agent codex           # ~/.codex/AGENTS.md にインライン（CODEX_HOME 尊重）
+python -m docsweep inject --global --lang en               # 注入文言を英語で生成（プロジェクト注入でも --lang 可）
 python -m docsweep eject  --global
 
 python -m docsweep list                                    # 注入済み（プロジェクト＋グローバル）一覧

docsweep-0.2.0/README.en.md

@@ -0,0 +1,458 @@
+# docsweep
+
+> 日本語版: [README.md](README.md)
+
+A cross-platform CLI + Web UI tool that **solves the accumulation and staleness problem** of
+`plan_*.md` / `bugfix_*.md` / `pending_*.md` files generated by AI coding tools
+(Claude Code / Codex, etc.).
+
+It mechanically reads H1 status labels (`[Done]` / `[Planned]` / `[Discarded]`, etc. — Japanese
+labels such as `[完了]` / `[計画]` / `[廃止]` are supported out of the box), automatically moves
+completed docs into each project's `archive/`, surfaces stale ones with a "needs decision" flag,
+and gives you a cross-project INDEX at a glance.
+
+## OKF (Open Knowledge Format) compatibility
+
+docsweep adopts the **machine-readable type / status / related frontmatter** from
+[OKF (Open Knowledge Format)](https://zenn.dev/knowledgesense/articles/14a874a9f423bb).
+The YAML frontmatter at the top of each md file makes `type` / `status` / `tags` / `owner` /
+`review_status` / `related` / `last_reviewed` machine-readable, so the files stay meaningful
+even when read by tools that don't have docsweep installed.
+
+docsweep adds only two conventions of its own:
+
+- **The type set is fixed to `plan` / `bugfix` / `pending`** (slightly stricter than OKF).
+  This constraint enables archive automation; arbitrary type values are treated as unmanaged.
+- **H1 status labels are kept alongside, not deprecated**. They preserve the human-facing value
+  of seeing the state the moment you open the file, and files without frontmatter fall back to
+  the H1 label (100% backward compatible).
+
+See [docs/okf-mapping.md](docs/okf-mapping.md) for the full mapping table.
+`docsweep export --okf` demonstrates that "your md files won't rot even if you leave docsweep"
+([docs/okf-export-format.md](docs/okf-export-format.md)).
+
+## Installation
+
+```bash
+pip install docsweep                  # Core + CLI (the main "wings" commands and the SQLite index included)
+pip install 'docsweep[all]'           # Also includes Web UI / interactive review / MCP / watch / resurrect
+pip install 'docsweep[watch]'         # Adds index-watch only (watchdog)
+pip install 'docsweep[resurrect]'     # Embedding path for resurrect (sentence-transformers)
+```
+
+docsweep is designed to work **without putting a `docsweep` command on PATH**.
+The CLI / Web UI / MCP can all be launched as a module from the Python executable.
+
+```bash
+python -m docsweep triage
+python -m docsweep mcp
+python -m docsweep serve --root ~/dev
+```
+
+When registering with an MCP client, we recommend `python -m docsweep mcp` rather than
+`docsweep mcp`. For maximum reproducibility, use the absolute path of the Python executable
+as `command`.
+
+```json
+{
+  "mcpServers": {
+    "docsweep": {
+      "command": "C:\\Users\\you\\AppData\\Local\\Programs\\Python\\Python312\\python.exe",
+      "args": ["-m", "docsweep", "mcp"]
+    }
+  }
+}
+```
+
+> Replace `Python312` above with **the Python version actually installed on your machine**.
+> To check: `where python` on Windows, `which python3` on macOS / Linux.
+> Or get the full path with `python -c "import sys; print(sys.executable)"`.
+
+`docsweep ...` is a shorthand for environments where Python's Scripts/bin directory is on PATH.
+
+## Where it goes after install, and how to use it (per OS)
+
+`pip install docsweep` **places the library in Python's site-packages**.
+No separate binary is produced; launching with `python -m docsweep ...` is the standard path.
+
+### Common behavior
+
+- **The `docsweep/` package itself**: installed into the site-packages resolved by the running Python
+- **Config and state**: `~/.docsweep/` (the same logical path on every OS)
+- **MCP setup**: register a single `python -m docsweep mcp` line in your AI client's config (Claude Code, etc.)
+- **No PATH setup required**: every feature is reachable via `python -m docsweep ...` without putting `docsweep` on PATH
+
+### Windows
+
+| Item | Location |
+|---|---|
+| Python itself (standard per-user install) | `C:\Users\<you>\AppData\Local\Programs\Python\Python3XX\python.exe` |
+| docsweep package (after pip install) | `C:\Users\<you>\AppData\Local\Programs\Python\Python3XX\Lib\site-packages\docsweep\` |
+| docsweep config and state | `C:\Users\<you>\.docsweep\` (= `%USERPROFILE%\.docsweep\` = `~/.docsweep`) |
+| `docsweep` launcher | `...\Python3XX\Scripts\docsweep.exe` (runs as plain `docsweep` if Scripts is on PATH) |
+
+> **Avoid the Microsoft Store version of Python**. With the Store build behind
+> `%LOCALAPPDATA%\Microsoft\WindowsApps\python.exe`, virtual-store placement restrictions can
+> **block writes to the `Scripts/` directory** — `pip install` itself may succeed, yet the
+> `docsweep.exe` launcher ends up missing or off PATH. The python.org installer (per-user)
+> or pyenv-win is the safe choice.
+
+```powershell
+# Install
+pip install 'docsweep[all]'
+
+# Launch (always works regardless of PATH)
+python -m docsweep triage
+python -m docsweep serve --root C:\dev
+python -m docsweep mcp
+
+# MCP registration example (~\.claude\mcp.json) — an absolute path stays stable across Python switches
+# {
+#   "mcpServers": {
+#     "docsweep": {
+#       "command": "C:\\Users\\you\\AppData\\Local\\Programs\\Python\\Python312\\python.exe",
+#       "args": ["-m", "docsweep", "mcp"]
+#     }
+#   }
+# }
+# Replace Python312 with your actual version. Check: `where python` or `python -c "import sys; print(sys.executable)"`
+```
+
+### macOS
+
+| Item | Location |
+|---|---|
+| Python itself (Homebrew example) | `/opt/homebrew/bin/python3` (Apple Silicon) / `/usr/local/bin/python3` (Intel) |
+| docsweep package | `/opt/homebrew/lib/python3.XX/site-packages/docsweep/` etc. (check with `python3 -m site`) |
+| docsweep config and state | `~/.docsweep/` (= `/Users/<you>/.docsweep/`) |
+| `docsweep` launcher | `/opt/homebrew/bin/docsweep` etc. (often already on PATH) |
+
+```bash
+# Install (if PEP 668 protects the system Python, choose --user or a venv)
+pip3 install 'docsweep[all]'
+
+# Launch
+python3 -m docsweep triage
+python3 -m docsweep serve --root ~/dev
+python3 -m docsweep mcp
+
+# MCP registration example (~/.claude/mcp.json)
+# {
+#   "mcpServers": {
+#     "docsweep": {
+#       "command": "/opt/homebrew/bin/python3",
+#       "args": ["-m", "docsweep", "mcp"]
+#     }
+#   }
+# }
+# Find your Python path with `which python3`
+```
+
+### Linux
+
+> **PEP 668 note (Ubuntu 23.04+ / Debian 12+ / Fedora 38+, etc.)**: recent distros protect the
+> system Python, so a bare `pip install` is rejected with `error: externally-managed-environment`.
+> The fix is one of **venv**, **`--user`**, or **pipx** (as in the commands below).
+> Forcing it with `--break-system-packages` invites conflicts with OS-managed packages and is
+> not recommended.
+
+| Item | Location |
+|---|---|
+| Python itself (distro pkg / pyenv, etc.) | `/usr/bin/python3` / `~/.pyenv/versions/3.XX.X/bin/python` etc. |
+| docsweep package | `/usr/lib/python3.XX/site-packages/docsweep/` or `~/.local/lib/python3.XX/site-packages/docsweep/` (with `--user`) |
+| docsweep config and state | `~/.docsweep/` |
+| `docsweep` launcher | `/usr/local/bin/docsweep` / `~/.local/bin/docsweep` (add `~/.local/bin` to PATH on distros that don't) |
+
+```bash
+# Most distros keep pip away from the system Python. Prefer venv, --user, or pipx
+python3 -m venv ~/.venvs/docsweep && source ~/.venvs/docsweep/bin/activate
+pip install 'docsweep[all]'
+
+# Or
+pip install --user 'docsweep[all]'
+
+# Launch
+python3 -m docsweep triage
+python3 -m docsweep serve --root ~/dev
+python3 -m docsweep mcp
+
+# MCP registration example (~/.claude/mcp.json) — point to the absolute path of the venv Python
+# {
+#   "mcpServers": {
+#     "docsweep": {
+#       "command": "/home/you/.venvs/docsweep/bin/python",
+#       "args": ["-m", "docsweep", "mcp"]
+#     }
+#   }
+# }
+# Find your Python path with `which python3`
+```
+
+### Choosing an install style
+
+| Style | Best for |
+|---|---|
+| **Direct `pip install`** (into your user Python) | Casual use as a personal tool. Fewest steps |
+| **venv isolation** (dedicated env via `python -m venv ...`) | Keeping dependencies out of your user Python. Point MCP config at the venv Python's absolute path |
+| **pipx** (isolated CLI install) | Using only the docsweep CLI. For MCP, point to pipx's internal venv Python by absolute path |
+| **`pip install -e .`** (clone the repo, editable install) | Developing or extending docsweep yourself. Source edits take effect immediately |
+
+### Uninstall
+
+```bash
+pip uninstall docsweep
+# To remove config as well
+rm -rf ~/.docsweep                # macOS / Linux
+Remove-Item -Recurse ~/.docsweep  # Windows PowerShell
+```
+
+## Usage
+
+> **`brief` is your morning entry point**: even when you remember nothing, `python -m docsweep brief`
+> decisively gives you "today's one item". For cross-project view use `python -m docsweep cross`.
+> Details: [docs/ai-agent-integration.md](docs/ai-agent-integration.md).
+
+```bash
+# === Main new commands in wings (v0.2 series) ===
+
+# Morning entry point — decide on "just one thing to do today" (cwd project)
+python -m docsweep brief
+python -m docsweep brief --all              # Summary across all projects
+python -m docsweep brief --continue         # Skip the trailing dialog and copy context straight to the clipboard
+
+# Bird's-eye view across all projects — top_pick + freeze candidates + project_summaries
+python -m docsweep cross
+python -m docsweep cross --project alpha,beta
+python -m docsweep cross --explain plan_x.md   # Score breakdown
+
+# Extract plan/bugfix/pending drafts from conversation history (heuristic / LLM mock)
+python -m docsweep capture --from clipboard
+python -m docsweep capture --from file ./conv.md --save-all
+
+# Check consistency between a plan's "files to change" and the actual implementation
+python -m docsweep linkcheck --json
+
+# Suggest state transitions (ruleset / future LLM delegation) + bulk apply
+python -m docsweep auto-triage --suggest > decisions.json
+python -m docsweep auto-triage --apply decisions.json --dry-run
+
+# Relationship network (graph of plan/bugfix/pending and frontmatter related)
+python -m docsweep graph --json
+
+# Extract similar pairs between archive and active docs (embedding opt-in / Jaccard by default)
+python -m docsweep resurrect --threshold 0.5
+
+# SQLite index at ~/.docsweep/index.db
+python -m docsweep index-sync               # Incremental ingest (fast)
+python -m docsweep index-rebuild            # Full rebuild
+python -m docsweep index-watch              # Auto-sync via file watching (requires watchdog)
+
+# === Existing commands (backward compatible) ===
+
+# Scan (by default shows only needs-decision + pending)
+python -m docsweep --root ~/dev
+python -m docsweep ./thisproject            # One-off scan, no config needed
+python -m docsweep scan --all --json        # Everything as machine-readable JSON
+
+# Auto-archive (non-interactive, for cron / CI / AI delegation). Done/discarded only; watching is protected
+python -m docsweep sweep --dry-run
+python -m docsweep sweep
+
+# Regenerate the cross-project INDEX (.docsweep/INDEX.md and INDEX.json)
+python -m docsweep index
+python -m docsweep pending                  # Show only [Pending] items across all projects at once
+python -m docsweep report                   # Human-facing weekly report
+python -m docsweep summary                  # Compressed JSON to hand to an AI
+
+# Release cleanup (promote watching items to done in bulk and archive them)
+python -m docsweep promote --state watching --to done
+
+# Interactive checklist (humans only)
+python -m docsweep review
+
+# Instant template generation
+python -m docsweep new plan my-topic
+python -m docsweep new bugfix crash-on-start
+
+# Export as an OKF-compatible zip (proof that your md files won't rot if you leave docsweep)
+python -m docsweep export --okf                          # ./docsweep-okf-<date>.zip
+python -m docsweep export --okf --out /tmp/snapshot.zip  # Explicit output path
+python -m docsweep export --okf --include-archive        # Include archive/ as well
+
+# Inject / remove the operating rules per project (CLAUDE.md = source of truth, AGENTS.md is a pointer to it)
+python -m docsweep inject --project ./foo --preset claude-jp
+python -m docsweep inject --project ./foo --no-guidance   # Label section only, no entry-point wiring (when wiring lives in the global config)
+python -m docsweep eject  --project ./foo                  # Strip only the managed block (hand-written parts kept; --purge also removes .docsweep.yaml)
+
+# One-time injection into your personal global config: a "read triage at session start" entry point + due rules (effective in all projects)
+python -m docsweep inject --global                         # Default agent=claude (one @import line in ~/.claude/CLAUDE.md)
+python -m docsweep inject --global --agent codex           # Inline into ~/.codex/AGENTS.md (respects CODEX_HOME)
+python -m docsweep inject --global --lang en               # Generate the injected text in English (--lang also works for project injection)
+python -m docsweep eject  --global
+
+python -m docsweep list                                    # List injected targets (projects + global)
+
+# Web UI (the UX centerpiece; 127.0.0.1, token-bearing URL). Inject/eject also available from the dashboard (preview required)
+# UI language can be switched from the settings modal (Japanese / English), or via ?lang=en
+python -m docsweep serve --root ~/dev
+
+# MCP server (AI agent surface, stdio)
+python -m docsweep mcp
+```
+
+## State model (linear, single source of truth)
+
+```
+plan:    [Pending] → [Planned] → [In Progress] → [Watching] → [Done]
+bugfix:              [In Progress] → [Watching] → [Done]
+         (either can branch to [Discarded] from any state)
+```
+
+The Japanese label set (`[保留]` → `[計画]` → `[実行中]` → `[様子見]` → `[完了]` / `[対応中]` /
+`[廃止]`) is supported by default and follows the same transitions.
+
+- **`[Watching]`** = fixed but resting. **Never auto-archived** (protected as the queue awaiting
+  regression confirmation).
+- Only **`[Done]` / `[Discarded]`** are archive targets. `[Discarded]` means quarantined into
+  `archive/`, not deleted (recoverable).
+- The label vocabulary, archivability, and auto-archive eligibility come from the `states:`
+  config — **the single source of truth** — from which detection, the Web display, and the
+  injection templates are all derived.
+
+## Configuration layers
+
+Precedence: **(1) CLI flags > (2) project `.docsweep.yaml` > (3) global `~/.docsweep/config.yaml`**.
+Write only the global config and it feels like a single layer; `.docsweep.yaml` applies partial
+overrides only where present.
+
+### Three common patterns (global `~/.docsweep/config.yaml`)
+
+Project boundaries are auto-detected from concrete markers like `.git` / `package.json` /
+`pyproject.toml`, so **projects can live at any depth under a root** (no hardcoded folder hierarchy).
+
+**A. Manage everything under one parent directory**
+
+```yaml
+roots:
+  - ~/dev
+```
+
+**B. Manage several scattered directories**
+
+```yaml
+roots:
+  - ~/dev/github/public
+  - ~/dev/works/clientA
+  - ~/dev/works/clientB
+  - /d/sandbox/experiments
+```
+
+**C. Switch by purpose (profiles)**
+
+```yaml
+roots:
+  - ~/dev/github/public        # Default scope (no arguments)
+profiles:
+  work:                         # python -m docsweep triage --profile work
+    - ~/dev/works/clientA
+    - ~/dev/works/clientB
+  all:                          # python -m docsweep triage --profile all
+    - ~/dev/github/public
+    - ~/dev/works
+```
+
+For a **one-off scan** you can also pass positional arguments without writing any config:
+
+```bash
+python -m docsweep triage ~/dev/foo ~/projects/bar
+```
+
+## AI agent integration
+
+> **The wings (v0.2 series) policy**: "works with every AI" comes first. Only the three
+> morning-entry tools where natural-language invocation adds the most value
+> (`brief` / `cross` / `capture_extract`+`capture_save`) are exposed via MCP; everything else
+> supports all AIs through **direct CLI calls**. Details and the natural-language mapping table:
+> [docs/ai-agent-integration.md](docs/ai-agent-integration.md).
+
+### Recommended setup: CLI only, no MCP registration
+
+Rather than registering the MCP server with each AI tool (Claude Code / Codex / Cursor …),
+the simplest setup is to **let the AI call the CLI directly** (`python -m docsweep ...`).
+
+- One install works from every AI tool (MCP registration is a separate file per AI tool)
+- The return values and triage contents are identical to MCP — the AI-facing experience barely differs
+- The only chore is **adding `python -m docsweep` to the AI's allowlist**
+
+For Claude Code, add one line to `permissions.allow` in `~/.claude/settings.json`:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(python -m docsweep:*)"
+    ]
+  }
+}
+```
+
+> docsweep **never rewrites this JSON automatically** (it would be a permission-boundary
+> operation). We deliberately leave it as something the user pastes in intentionally. To use MCP
+> instead, use the "MCP registration example" above (also never auto-registered).
+
+### What triage returns
+
+`python -m docsweep triage` (or the MCP `triage` tool) returns the **remaining work, filtered to
+needs-decision + pending items in oldest-first order**, as `counts` + `items[]` + `needs_fix[]`.
+Each item carries `rel` (relative path), `title` (H1), `state` (label), `type`, `age_days`,
+`summary`, and `actions` (a closed set of `discard`/`keep`/`resume`/`relabel`/`promote`). The
+agent decides "which file to continue and how", then executes mechanically with
+`python -m docsweep apply`. For a bird's-eye view of the whole cross-project INDEX, use
+`python -m docsweep summary`. docsweep itself never calls any AI API (vendor-neutral).
+
+To hand this remaining work to the AI automatically at session start, run
+`python -m docsweep inject --global` (a one-time injection into your personal global config of a
+"read triage before working" entry point — via `@import` for Claude, inline for Codex).
+
+### Scoping to a single project (`--project`)
+
+When you manage multiple roots, natural-language queries from an AI tend to be about
+"just `<this repo>`" rather than "everything". `sweep` / `promote` / `triage` / `scan` /
+`summary` all accept a common `--project <name>` flag to narrow down by project name
+(the boundary folder name).
+
+```bash
+# "How many archive candidates does many-ai-cli have?"
+python -m docsweep sweep --dry-run --project many-ai-cli
+
+# "Any watching items ready for promotion in the docsweep project?"
+python -m docsweep promote --dry-run --project docsweep
+
+# "Any remaining work in many-ai-cli?"
+python -m docsweep triage --project many-ai-cli
+
+# "Dump everything in the docsweep project as JSON"
+python -m docsweep scan --all --project docsweep --json
+
+# "Compressed JSON overview of the docsweep project"
+python -m docsweep summary --project docsweep
+```
+
+> The narrowing **keeps the scan roots fixed and filters afterwards**. Even if a project's
+> `.gitignore` excludes `docs/local/`, the files are still covered as long as they are visible
+> from the global config's `roots:` (this design avoids the trap where a one-off scan of the
+> project via the positional argument `.` returns 0 items because of `.gitignore` exclusion).
+>
+> The `counts` from `triage` / `summary` are also aligned to the per-project scope (they match
+> the filtered `items` count, so humans and AIs see consistent numbers).
+
+The same narrowing works over MCP via arguments, e.g. `triage(project="many-ai-cli")` /
+`summary(project="docsweep")` / `sweep(project="many-ai-cli", dry_run=True)`. Argument names
+and behavior are kept fully identical between CLI and MCP.
+
+See [docs/conventions.md](docs/conventions.md) and
+[templates/AGENT_GUIDE.md](templates/AGENT_GUIDE.md) for details.
+
+## License
+
+MIT

{docsweep-0.1.0 → docsweep-0.2.0}/README.md

@@ -1,5 +1,7 @@
 # docsweep
 
+> English version: [README.en.md](README.en.md)
+
 AI コーディングツール（Claude Code / Codex 等）が生成する `plan_*.md` / `bugfix_*.md` /
 `pending_*.md` の **蓄積・陳腐化問題を解決する** クロスプラットフォーム CLI + Web UI ツール。
 
@@ -274,9 +276,10 @@ python -m docsweep inject --project ./foo --preset claude-jp
 python -m docsweep inject --project ./foo --no-guidance   # 導線を省きラベル節だけ（導線をグローバルに寄せる場合）
 python -m docsweep eject  --project ./foo                  # 管理ブロックだけ剥がす（手書きは温存。--purge で .docsweep.yaml も）
 
-# 個人グローバルへ「セッション開始時に triage を読む」導線を一度だけ注入（全プロジェクトで有効）
+# 個人グローバルへ「セッション開始時に triage を読む」導線＋due ルールを一度だけ注入（全プロジェクトで有効）
 python -m docsweep inject --global                         # 既定 agent=claude（~/.claude/CLAUDE.md に @import 1 行）
 python -m docsweep inject --global --agent codex           # ~/.codex/AGENTS.md にインライン（CODEX_HOME 尊重）
+python -m docsweep inject --global --lang en               # 注入文言を英語で生成（プロジェクト注入でも --lang 可）
 python -m docsweep eject  --global
 
 python -m docsweep list                                    # 注入済み（プロジェクト＋グローバル）一覧

{docsweep-0.1.0 → docsweep-0.2.0}/docsweep/__init__.py

@@ -1,3 +1,3 @@
 """docsweep — AI 作業ドキュメント（plan/bugfix/pending）の横断スキャン・判定・archive 移送ツール。"""
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

{docsweep-0.1.0 → docsweep-0.2.0}/docsweep/cli.py

@@ -275,9 +275,10 @@ def build_parser() -> argparse.ArgumentParser:
     p_inject.add_argument("--project", default=".", help="注入先プロジェクト（既定 .）")
     p_inject.add_argument("--preset", help="プリセット名（claude-jp / frontmatter）")
     p_inject.add_argument("--no-yaml", action="store_true", help=".docsweep.yaml を書かない")
-    p_inject.add_argument("--no-guidance", action="store_true", help="導線を省きラベル節だけ注入（導線をグローバルに寄せる場合）")
-    p_inject.add_argument("--global", dest="is_global", action="store_true", help="個人グローバル設定へ導線だけ注入（全プロジェクトで効く）")
+    p_inject.add_argument("--no-guidance", action="store_true", help="導線と due ルールを省きラベル節だけ注入（グローバルに寄せる場合）")
+    p_inject.add_argument("--global", dest="is_global", action="store_true", help="個人グローバル設定へ導線＋due ルールを注入（全プロジェクトで効く）")
     p_inject.add_argument("--agent", choices=("claude", "codex"), default="claude", help="グローバル注入先の AI ツール（--global 時）")
+    p_inject.add_argument("--lang", choices=("ja", "en"), help="注入文言の言語（プロジェクト注入は preset の言語を上書き / --global の既定は ja）")
     p_inject.add_argument("--global-target", dest="global_target", help="グローバル注入先を明示パスで上書き")
     p_inject.add_argument("--dry-run", action="store_true")
 
@@ -1317,7 +1318,9 @@ def cmd_inject(args: argparse.Namespace) -> int:
 
     tag = "（dry-run）" if args.dry_run else ""
     if getattr(args, "is_global", False):
-        r = inject_global(agent=args.agent, target=args.global_target, dry_run=args.dry_run)
+        r = inject_global(
+            agent=args.agent, target=args.global_target, lang=args.lang or "ja", dry_run=args.dry_run,
+        )
         print(f"inject {r.project}{tag}: 書込={r.written or '-'} 温存/不変={r.skipped or '-'}")
         for w in r.warnings:
             print(f"  ⚠ {w}")
@@ -1325,7 +1328,7 @@ def cmd_inject(args: argparse.Namespace) -> int:
 
     r = inject(
         Path(args.project), preset=args.preset, write_yaml=not args.no_yaml,
-        include_guidance=not args.no_guidance, dry_run=args.dry_run,
+        include_guidance=not args.no_guidance, lang=args.lang, dry_run=args.dry_run,
     )
     print(f"inject {r.project}{tag}: 書込={r.written or '-'} 温存/不変={r.skipped or '-'}")
     if r.yaml_path: