codex-flow 2.1.13__py3-none-any.whl

codex_flow/__init__.py

@@ -0,0 +1,28 @@
+"""Intelligent, Efficient, Adaptive Multi-Agent Strategy Orchestration for Codex."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+__author__ = "Parsifal <zmw@izmw.me>"
+
+try:
+    if sys.version_info >= (3, 8):
+        from importlib.metadata import PackageNotFoundError, version
+    else:
+        from importlib_metadata import PackageNotFoundError, version  # type: ignore
+
+    __version__ = version("codex-flow")
+except Exception:
+    # Fallback to local VERSION file if present
+    _pkg_dir = Path(__file__).resolve().parent
+    _candidates = [
+        _pkg_dir / "data" / "VERSION",
+        _pkg_dir.parents[1] / "VERSION",
+    ]
+    __version__ = "unknown"
+    for _c in _candidates:
+        if _c.exists():
+            __version__ = _c.read_text(encoding="utf-8").strip().lstrip("v")
+            break

codex_flow/__main__.py

@@ -0,0 +1,9 @@
+"""Executable entry point for python -m codex_flow."""
+
+from __future__ import annotations
+
+import sys
+from codex_flow.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

codex_flow/cli.py

@@ -0,0 +1,242 @@
+"""Unified cross-platform CLI dispatcher for codex-flow."""
+
+from __future__ import annotations
+
+import os
+import platform
+import subprocess
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+CODEX_HOME = Path(os.environ.get("CODEX_HOME", Path.home() / ".codex"))
+STATE_DIR = CODEX_HOME / "codex-flow"
+SOURCE_FILE = STATE_DIR / "source"
+POLICY_FILE = CODEX_HOME / "codex-flow.toml"
+
+
+def get_resource_root() -> Path:
+    """Resolve the directory containing runtime scripts and assets."""
+    # 1. Check if bundled data directory inside the package exists
+    bundled = Path(__file__).resolve().parent / "data"
+    if (bundled / "VERSION").exists() and (bundled / "scripts").exists():
+        return bundled
+
+    # 2. Check if running from a git checkout / source tree
+    for parent in Path(__file__).resolve().parents:
+        if (parent / "VERSION").exists() and (parent / "scripts").exists():
+            return parent
+
+    # 3. Check installed state source file
+    if SOURCE_FILE.exists():
+        try:
+            target = Path(SOURCE_FILE.read_text(encoding="utf-8").strip())
+            if target.is_dir():
+                return target
+        except OSError:
+            pass
+
+    return bundled
+
+
+def find_script(name: str, root: Path) -> Optional[Path]:
+    """Find a script in resource root or state dir."""
+    candidates = [
+        root / "scripts" / name,
+        root / name,
+        STATE_DIR / name,
+    ]
+    for c in candidates:
+        try:
+            if c.is_file():
+                return c
+        except OSError:
+            continue
+    return None
+
+
+def run_python_script(script_path: Path, args: List[str], env: Optional[dict] = None) -> int:
+    """Run a python script using current interpreter and appropriate environment."""
+    run_env = os.environ.copy()
+    if env:
+        run_env.update(env)
+
+    # Ensure script's directory and its parent are in PYTHONPATH for internal imports
+    script_dir = str(script_path.parent)
+    parent_dir = str(script_path.parents[1]) if len(script_path.parents) > 1 else script_dir
+    existing_pp = run_env.get("PYTHONPATH", "")
+    new_pp = f"{script_dir}{os.pathsep}{parent_dir}"
+    run_env["PYTHONPATH"] = f"{new_pp}{os.pathsep}{existing_pp}" if existing_pp else new_pp
+
+    cmd = [sys.executable, str(script_path), *args]
+    try:
+        proc = subprocess.run(cmd, env=run_env)
+        return proc.returncode
+    except KeyboardInterrupt:
+        return 130
+
+
+def handle_install(root: Path, args: List[str]) -> int:
+    """Execute installation bootstrap."""
+    is_windows = platform.system() == "Windows"
+
+    # Prefer install-release scripts for full multi-platform + prebuilt FlowPilot support
+    if is_windows:
+        installer = root / "install-release.ps1"
+        if not installer.exists():
+            installer = root / "install.ps1"
+        if not installer.exists():
+            print("Error: install.ps1 not found in codex-flow package", file=sys.stderr)
+            return 1
+        cmd = ["powershell", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", str(installer), *args]
+    else:
+        installer = root / "install-release.sh"
+        if not installer.exists():
+            installer = root / "install.sh"
+        if not installer.exists():
+            print("Error: install.sh not found in codex-flow package", file=sys.stderr)
+            return 1
+        cmd = ["bash", str(installer), *args]
+
+    try:
+        proc = subprocess.run(cmd)
+        return proc.returncode
+    except KeyboardInterrupt:
+        return 130
+
+
+def handle_overlay(root: Path, args: List[str]) -> int:
+    """Execute native FlowPilot macOS overlay."""
+    if platform.system() != "Darwin":
+        print("FlowPilot native overlay widget is only available on macOS.", file=sys.stderr)
+        return 1
+
+    candidates = [
+        STATE_DIR / "bin" / "FlowPilot",
+        STATE_DIR / "bin" / "codex-flow-overlay",
+        root / "apps" / "macos-overlay" / "bin" / "FlowPilot",
+        root / "apps" / "macos-overlay" / "bin" / "codex-flow-overlay",
+    ]
+    overlay_bin = None
+    for c in candidates:
+        if c.is_file() and os.access(c, os.X_OK):
+            overlay_bin = c
+            break
+
+    if not overlay_bin:
+        print(
+            "FlowPilot native overlay is not built or installed yet. Run: codex-flow install",
+            file=sys.stderr,
+        )
+        return 1
+
+    sub = args[0] if args else "toggle"
+    if sub in ("start", "restart"):
+        logs_dir = STATE_DIR / "logs"
+        logs_dir.mkdir(parents=True, exist_ok=True)
+        start_log = logs_dir / "flowpilot-start.log"
+        with open(start_log, "a", encoding="utf-8") as lf:
+            proc = subprocess.Popen([str(overlay_bin), "start"], stdout=lf, stderr=lf)
+        print("🚀 Launched FlowPilot in background.")
+        return 0
+    else:
+        proc = subprocess.run([str(overlay_bin), *args])
+        return proc.returncode
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    """Main CLI entry point."""
+    if argv is None:
+        argv = sys.argv[1:]
+
+    root = get_resource_root()
+
+    if not argv:
+        if sys.stdin.isatty() and sys.stdout.isatty() and os.environ.get("TERM") != "dumb":
+            menu = find_script("menu.py", root)
+            if menu:
+                return run_python_script(menu, [])
+        argv = ["help"]
+
+    cmd = argv[0]
+    rest = argv[1:]
+
+    if cmd in ("install", "init"):
+        return handle_install(root, rest)
+
+    if cmd in ("status", "help", "-h", "--help"):
+        ui = find_script("ui.py", root)
+        if not ui:
+            print("Error: ui.py helper not found; reinstall codex-flow", file=sys.stderr)
+            return 1
+        sub = "status" if cmd == "status" else "help"
+        return run_python_script(ui, [sub, *rest])
+
+    if cmd == "language":
+        ui = find_script("ui.py", root)
+        if not ui:
+            print("Error: ui.py helper not found; reinstall codex-flow", file=sys.stderr)
+            return 1
+        return run_python_script(ui, ["language", *rest])
+
+    if cmd == "strategy":
+        strat = find_script("strategy_runtime.py", root)
+        if not strat:
+            print("Error: strategy_runtime.py not found; reinstall codex-flow", file=sys.stderr)
+            return 1
+        return run_python_script(strat, ["--policy", str(POLICY_FILE), *rest])
+
+    if cmd in ("usage", "telemetry"):
+        tel = find_script("telemetry.py", root)
+        if not tel:
+            print("Error: telemetry.py not found; reinstall codex-flow", file=sys.stderr)
+            return 1
+        sub_args = rest if rest else ["last"]
+        return run_python_script(tel, sub_args)
+
+    if cmd == "doctor":
+        doc = find_script("doctor.py", root)
+        if not doc:
+            print("Error: doctor.py not found; reinstall codex-flow", file=sys.stderr)
+            return 1
+        return run_python_script(doc, rest)
+
+    if cmd == "update":
+        upd = find_script("updater.py", root)
+        if not upd:
+            print("Error: updater.py not found; reinstall codex-flow", file=sys.stderr)
+            return 1
+        return run_python_script(upd, rest)
+
+    if cmd == "rollback":
+        upd = find_script("updater.py", root)
+        if not upd:
+            print("Error: updater.py not found; reinstall codex-flow", file=sys.stderr)
+            return 1
+        return run_python_script(upd, ["rollback", *rest])
+
+    if cmd == "overlay":
+        return handle_overlay(root, rest)
+
+    if cmd == "benchmark":
+        bench = find_script("run-benchmark.py", root)
+        if bench:
+            return run_python_script(bench, rest)
+
+    if cmd == "benchmark-local":
+        bench = find_script("benchmark-local.py", root)
+        if bench:
+            return run_python_script(bench, rest)
+
+    if cmd == "benchmark-analyze":
+        bench = find_script("analyze-benchmark.py", root)
+        if bench:
+            return run_python_script(bench, rest)
+
+    print(f"codex-flow: unknown command: {cmd}", file=sys.stderr)
+    print("Run 'codex-flow help' for available commands.", file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

codex_flow/data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 codex-flow 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.

codex_flow/data/README.en.md

@@ -0,0 +1,303 @@
+<div align="center">
+
+<a href="https://github.com/ParsifalC/codex-flow">
+  <img src="docs/assets/logo.png" alt="FlowPilot Logo" width="130" height="130" />
+</a>
+
+# FlowPilot · codex-flow
+
+**Intelligent, Efficient, Adaptive Multi-Agent Strategy Orchestration for Codex**
+
+[![Version](https://img.shields.io/badge/version-2.1.13-blue.svg?style=flat-square)](VERSION)
+[![Homebrew](https://img.shields.io/badge/Homebrew-ParsifalC%2Ftap-orange.svg?style=flat-square&logo=homebrew)](https://github.com/ParsifalC/homebrew-tap)
+[![PyPI](https://img.shields.io/pypi/v/codex-flow.svg?style=flat-square&logo=pypi)](https://pypi.org/project/codex-flow/)
+[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-brightgreen.svg?style=flat-square)](#-quick-start)
+[![SwiftUI](https://img.shields.io/badge/UI-SwiftUI%20%2B%20AppKit-orange.svg?style=flat-square)](docs/overlay.en.md)
+[![Telemetry](https://img.shields.io/badge/telemetry-deterministic%200--cost-purple.svg?style=flat-square)](docs/telemetry.en.md)
+[![Smithery](https://img.shields.io/badge/Smithery-FlowPilot-black.svg?style=flat-square)](https://smithery.ai)
+[![Glama](https://img.shields.io/badge/Glama-MCP-5046e6.svg?style=flat-square)](https://glama.ai/mcp/servers)
+[![LinuxDo](https://img.shields.io/badge/LinuxDo-Public%20Beta-5046e6.svg?style=flat-square)](https://linux.do)
+[![License](https://img.shields.io/badge/license-MIT-green.svg?style=flat-square)](LICENSE)
+
+<br />
+
+<img src="docs/assets/promo/flowpilot_promo_banner.png" alt="codex-flow Banner" width="100%" style="border-radius: 12px; box-shadow: 0 8px 24px rgba(0,0,0,0.15);" />
+
+<br /><br />
+
+[**简体中文**](README.md) · [**Strategy Runtime**](docs/strategy-runtime.md) · [**Configuration**](docs/configuration.en.md) · [**Telemetry**](docs/telemetry.en.md) · [**Native Overlay**](docs/overlay.en.md) · [**Benchmarks**](docs/benchmark.en.md)
+
+<br />
+
+> 📢 **Community Beta**: `codex-flow` is currently in public beta on [**LINUX DO**](https://linux.do). Feedback, suggestions, and discussions are welcome!
+
+<br />
+
+> **“ Spend expensive Parent capability on high-value decisions; let efficient Workers reason deeper through execution, and concentrate premium capability on critical Implementer / Reviewer roles instead of upgrading every Worker indiscriminately. ”**
+
+</div>
+
+---
+
+## ✨ Key Highlights
+
+<table>
+  <tr>
+    <td width="50%" valign="top">
+      <h3>🧠 Multi-Strategy Runtime</h3>
+      <p>Built-in <code>efficient</code>, <code>balanced</code>, <code>quality</code>, and <code>speed</code> strategies compile TaskProfile → WorkerBudget → ExecutionPlan v7 through one deterministic runtime.</p>
+    </td>
+    <td width="50%" valign="top">
+      <h3>⚙️ Dynamic Worker Budgeting</h3>
+      <p>Fan-out is no longer fixed at one or two Workers. Runtime derives Explorer / Implementer / Reviewer counts from uncertainty, proven workstream isolation, quota, strategy budget, and hard thread ceilings.</p>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <h3>🧠 Worker-First Reasoning</h3>
+      <p>Fresh installs keep Parent mostly at <code>high</code> while Worker roles start at <code>xhigh</code>. Delegated roles run at least one effort tier above Parent whenever the supported effort ladder permits it.</p>
+    </td>
+    <td width="50%" valign="top">
+      <h3>🏆 Quality Intent</h3>
+      <p><code>quality</code> supports per-task <code>normal / strong / absolute</code> intent. Ordinary Explorers remain <code>latest-efficient</code>; strong/absolute intent can promote high-value Implementer / Reviewer roles to <code>latest-capable</code>. Explorers move to Parent-class capability only when technical risk itself is critical.</p>
+    </td>
+  </tr>
+</table>
+
+---
+
+## 🧩 Built-In Strategies
+
+| Strategy | Optimization Goal | Demanding-task Worker tendency |
+| :--- | :--- | :--- |
+| **`efficient`** | Reduce expensive Parent use and wasted total work | Up to roughly 2 Explorers / 2 Implementers, low speculation, quota-aware collapse |
+| **`balanced`** | Balance quality, quota, and latency | Up to roughly 3 Explorers / 3 Implementers with moderate safe parallelism |
+| **`quality`** | Maximize correctness and verification confidence | Normal complex work prefers efficient Workers + `max` reasoning; `strong/absolute` promotes only key Implementer / Reviewer roles while Explorers remain efficient by default |
+| **`speed`** | Minimize wall-clock latency | Budget allows up to 8 Implementers; actual count follows proven writable workstreams and runtime ceiling |
+
+`quality_intent` is **per-task semantic intent**, not persistent policy and not an alias for `risk`; only the `quality` strategy consumes it:
+
+```text
+normal   → ordinary quality target; prefer latest-efficient Workers with deep reasoning
+strong   → explicit quality-over-cost preference; Parent-class Implementer / Reviewer capability is allowed
+absolute → explicit highest-quality preference; correctness > quota / latency inside hard safety ceilings while Explorers remain latest-efficient by default
+```
+
+The persistent default remains:
+
+```text
+strategy = efficient
+routing = adaptive
+```
+
+However, v1.7 fresh-install resource policy is intentionally more Worker-centric than the earlier architecture. Existing customized reasoning settings are preserved losslessly across update/reinstall.
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+> 💡 **Note**: The Codex CLI is **only required for initial installation checks and one-time hook authorization**. Once initial setup is complete, you can use the **Codex Desktop App exclusively** for daily workflows without ever touching the CLI.
+
+Ensure the Codex CLI is installed for initial bootstrap:
+```bash
+# via npm
+npm install -g @openai/codex
+
+# or via macOS Homebrew
+brew install codex
+```
+
+### Quick Installation
+
+#### Option 1: PyPI Installation (Recommended across Windows / macOS / Linux)
+
+```bash
+# Recommended using pipx (isolated environment)
+pipx install codex-flow
+
+# Or using standard pip
+pip install codex-flow
+
+# Initialize configuration and environment
+codex-flow install
+```
+
+#### Option 2: Homebrew (macOS & Linux)
+
+```bash
+brew install ParsifalC/tap/codex-flow
+codex-flow install
+```
+
+#### Option 3: Automated Bootstrap Script
+
+Fresh installs use the matching GitHub Release artifact directly; cloning the repository is not required.
+
+```bash
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/ParsifalC/codex-flow/main/install-release.sh | bash
+```
+
+```powershell
+# Windows PowerShell
+irm https://raw.githubusercontent.com/ParsifalC/codex-flow/main/install-release.ps1 | iex
+```
+
+The bootstrap detects OS/CPU, resolves the Latest Stable Release, downloads the matching artifact, verifies SHA-256, installs it under `~/.codex/codex-flow/versions/<version>`, and runs health checks. Windows automatically selects the x86_64 or ARM64 ZIP. macOS uses the prebuilt FlowPilot binary from the Release and starts the floating widget automatically without running `build.sh` locally.
+
+> ⚠️ **Final step**:
+> 1. **One-time authorization**: Launch `codex` in your terminal once, type `/hooks` in the conversation prompt, and approve FlowPilot telemetry (required only once for permanent trust).
+> 2. **Restart Codex Desktop**: Fully quit and relaunch your Codex Desktop App. FlowPilot is already running on macOS; you can now perform all daily tasks directly in the Codex Desktop App.
+
+The installer also adds a marked FlowPilot entry block to the effective global `AGENTS.md`. This tells the active agent to load the installed skill and record the strategy gate receipt before repository technical work, so you do not need to name the skill. Start a new task after installation or fully reload Codex so the updated instructions are available. A disabled global switch or a consumed one-shot bypass allows ordinary execution for that task. This prompt entry depends on the active host following its instructions; it is not a 100% enforcement boundary, and lifecycle hooks remain telemetry-only.
+
+---
+
+## 🎮 Basic Usage
+
+### 1. Inspect or change strategy
+
+```bash
+codex-flow strategy show
+codex-flow strategy profiles
+codex-flow strategy set quality
+codex-flow strategy set efficient
+codex-flow strategy routing adaptive
+```
+
+### 2. Per-task natural-language overrides
+
+```text
+👉 Strategy       : "quality first" / "minimize Plan quota" / "finish as fast as possible"
+👉 Strong quality : "quality first; use stronger models when useful" → quality_intent=strong
+👉 Max quality    : "cost is secondary; use the strongest models and independent verification" → quality_intent=absolute
+👉 Adaptive       : "follow default strategy" / "handle adaptively"
+👉 Delegate       : "use subagents" / "assign to workers"
+👉 Direct         : "do not use subagents" / "complete directly"
+```
+
+Strategy and routing are orthogonal. For example:
+
+```text
+quality + direct
+```
+
+uses quality-oriented capability/reasoning policy while keeping execution in Parent for that task.
+
+### 3. Compile a deterministic ExecutionPlan
+
+```bash
+codex-flow strategy plan \
+  --profile quality \
+  --quality-intent strong \
+  --complexity complex \
+  --uncertainty high \
+  --parallelism high
+```
+
+The Plan exposes `quality_intent`, the selected `worker_budget`, and separate role-scoped resources:
+
+```text
+explorer_capability_policy / explorer_model / explorer_reasoning
+implementer_capability_policy / implementer_model / implementer_reasoning
+reviewer_capability_policy / reviewer_model / reviewer_reasoning
+```
+
+It also includes concrete `exploration_workers`, `implementation_workers`, `reviewer_workers`, and `planned_worker_count`.
+
+### 4. Interactive console
+
+```bash
+codex-flow
+```
+
+The latest console also integrates Overlay build/start management, effective policy, Benchmark, and telemetry entry points:
+
+```text
+╭────────────────────────────────────────────────────────────────────╮
+│                  🚀 codex-flow Console (v2.1.13)                   │
+│   FlowPilot orchestration · deterministic telemetry · validation   │
+╰────────────────────────────────────────────────────────────────────╯
+  [1] 🪟 macOS native floating widget (overlay widget)
+  [2] 📊 Latest task card (usage last)
+  [3] 📜 Task history (usage list)
+  [4] 📈 Project aggregate statistics (usage stats)
+  [5] 🎯 Effective policy (status)
+  [6] 🩺 Diagnostics (doctor)
+  [7] ⚡ Local quick Benchmark (benchmark-local quick)
+  [8] 🔄 Check and pull updates (update)
+  [0] 🚪 Exit
+```
+
+The Overlay submenu can start the widget directly, build and start it, build only, or—when running—rebuild/restart, toggle expansion, and push the latest data. Users no longer need to run `build.sh` manually first.
+
+### 5. Essential commands
+
+```bash
+codex-flow usage last
+codex-flow usage list --today
+codex-flow usage stats -d 30
+codex-flow doctor
+codex-flow update
+```
+
+### 6. MCP Clients & Registry Integration (Claude Desktop / Cursor / Smithery / Glama)
+
+`codex-flow` bundles a standard Model Context Protocol (MCP) server for feeding deterministic FlowPilot telemetry into any MCP-compatible client:
+
+* **Claude Desktop / Cursor (`stdio` mode)**:
+  Add to your `claude_desktop_config.json` or Cursor MCP settings:
+  ```json
+  {
+    "mcpServers": {
+      "flowpilot": {
+        "command": "codex-flow-mcp",
+        "args": ["--stdio"]
+      }
+    }
+  }
+  ```
+* **Smithery.ai**: Configured via `smithery.yaml` in the repo root for one-click discovery and agent mounting.
+* **Glama**: Authenticated via `glama.json` in the repo root and indexed in the Glama MCP registry.
+
+---
+
+## 🪟 FlowPilot Native macOS Widget
+
+A **100% native SwiftUI + AppKit** frosted-glass dashboard for task lifecycle and quota observability.
+
+<div align="center">
+  <img src="docs/assets/promo/flowpilot_promo_poster.png" alt="FlowPilot Native Widget Showcase" width="100%" style="border-radius: 12px; margin: 16px 0;" />
+</div>
+
+- **🟢 Micro Capsule**: edge docking with task state and latest usage.
+- **⚡️ Live Inspector**: time, token, cost, quota, and Agent topology.
+- **📜 Task History**: cross-project timeline and drill-down.
+- **📊 Analytics**: 7d/30d cache efficiency, Worker offload, and model/project distribution.
+
+```bash
+codex-flow overlay start
+codex-flow overlay toggle
+```
+
+---
+
+## 📚 Deep-Dive Documentation
+
+| Module | Document | Description |
+| :--- | :--- | :--- |
+| **🧠 Strategy Runtime** | [docs/strategy-runtime.md](docs/strategy-runtime.md) | TaskProfile, Quality Intent, WorkerBudget, Strategy Registry, ExecutionPlan v7, role-scoped resources |
+| **⚙️ Configuration** | [docs/configuration.en.md](docs/configuration.en.md) | Policy schema v4, Worker-first reasoning, routing, runtime ceilings |
+| **📈 Telemetry & Quota** | [docs/telemetry.en.md](docs/telemetry.en.md) | Hook lifecycle, token attribution, quota sampling |
+| **🪟 Native Overlay** | [docs/overlay.en.md](docs/overlay.en.md) | Gestures, IPC, SwiftUI architecture |
+| **🧪 Local Benchmarks** | [docs/benchmark.en.md](docs/benchmark.en.md) | Keyless validation and multi-strategy comparisons |
+| **☁️ Actions CI** | [docs/benchmark-actions.en.md](docs/benchmark-actions.en.md) | GitHub Actions benchmark workflow |
+| **🌐 Localization** | [docs/localization.en.md](docs/localization.en.md) | English / Chinese localization coverage |
+
+---
+
+## 📄 License
+
+This project is licensed under the [MIT License](LICENSE).