claude-nb 0.5.1 → 0.5.44

package/README.md

@@ -1,17 +1,107 @@
+<!-- README_SYNC: sections must match README_zh.md — run bin/check-readme-sync -->
+
+[中文版](README_zh.md)
+
 # claude-nb
 
-Multi-agent coordination framework for Claude Code sessions.
+[![CI](https://github.com/ApolloZhangOnGithub/cnb/actions/workflows/ci.yml/badge.svg)](https://github.com/ApolloZhangOnGithub/cnb/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/claude-nb?label=npm)](https://www.npmjs.com/package/claude-nb)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776AB)](pyproject.toml)
+[![Docs](https://img.shields.io/badge/docs-c--n--b.space-14865d)](https://c-n-b.space/)
+[![License](https://img.shields.io/badge/license-OpenAll--1.0-444)](LICENSE)
+
+**Project ownership for LLM teams.**
+
+`cnb` is local-first organizational infrastructure for long-lived Claude Code and Codex teams. It gives AI coding sessions a shared board, durable ownership, handoff records, and operational checks so a restarted session does not become a new hire with no memory.
+
+```bash
+npm install -g claude-nb
+```
+
+| Surface | Current shape |
+|---------|---------------|
+| Runtime | Local tmux sessions, SQLite board, dispatcher, filesystem reports |
+| Engines | Claude Code by default; Codex supported through the npm peer CLI |
+| State | Board database, ownership map, issue mirror, daily/shift reports |
+| Distribution | Public npm package `claude-nb`, Python 3.11+ internals |
+| Documentation | README short path, durable docs in [`docs/`](docs/), public site at [`c-n-b.space`](https://c-n-b.space/) |
+
+Every multi-agent tool solves "how to run multiple agents." cnb solves what happens after — how to make them **manageable** across sessions, shifts, and team changes.
+
+LLM sessions are stateless. Every restart is a new hire who knows nothing. Without organizational infrastructure, you get temporary workers who split tasks, finish, and forget. cnb gives them **permanent module ownership**: lisa-su owns the notification system across 11 commits and 3 restarts. When a bug surfaces, you don't re-explain the module to a blank session — you find the owner's daily report and pick up where they left off.
+
+This is not about speed or context isolation. Those are side effects. The core problem is: [42% of multi-agent failures are specification and system design issues](https://arxiv.org/abs/2503.13657) — role ambiguity, task misinterpretation, poor decomposition (Cemri et al., NeurIPS 2025 Spotlight). Not capability — organization. cnb is organizational infrastructure for AI teams.
+
+<!-- section:start-here -->
+## Start here
+
+| Need | Path |
+|------|------|
+| Install the CLI | `npm install -g claude-nb` |
+| Understand the model | [How cnb fits in](#how-cnb-fits-in), [Glossary](#glossary), [Ownership autonomy](docs/design-ownership-autonomy.md) |
+| Start a team | [Quick start](#quick-start), then `cnb` inside a project |
+| Inspect a real run | [Silicon Valley Battle](instances/silicon_vally_battle/) |
+| Publish or verify package metadata | [Package publishing](docs/package-publishing.md) |
+| Contribute safely | [Contributing](CONTRIBUTING.md), [Security](SECURITY.md), [Roadmap](ROADMAP.md) |
+
+<!-- section:status -->
+## Project status
+
+cnb is no longer a single-script experiment, but it is still an active local-first system that expects a trusted workstation and human supervision.
 
-Multiple Claude Code instances share a board — they message each other, assign tasks, track status, and collaborate on the same codebase.
+| Area | Current state | Evidence |
+|------|---------------|----------|
+| CLI packaging | npm entrypoint wraps the Python CLI | [`package.json`](package.json), [`pyproject.toml`](pyproject.toml), [`bin/cnb`](bin/cnb) |
+| Board runtime | SQLite schema, migrations, task/inbox/status/ownership commands | [`schema.sql`](schema.sql), [`migrations/`](migrations/), [`lib/board_*.py`](lib/) |
+| Quality gates | ruff, mypy, pytest, version sync, changelog, CodeQL, and secret scanning | [`.github/workflows/ci.yml`](.github/workflows/ci.yml), [`Makefile`](Makefile) |
+| Governance | issue-first workflow, ownership rules, Co-Authored-By policy | [`CONTRIBUTING.md`](CONTRIBUTING.md), [`ROADMAP.md`](ROADMAP.md), [`registry/`](registry/) |
+| Docs | bilingual README, durable product docs, and public GitHub Pages site | [`README_zh.md`](README_zh.md), [`docs/`](docs/), [`site/`](site/) |
+| Boundaries | local-first, high-permission options, human-supervised automation | [`SECURITY.md`](SECURITY.md), [FAQ](#faq) |
 
+<!-- section:why -->
+## How cnb fits in
+
+There are many great tools in this space, each with a different focus:
+
+- **Claude Squad, amux, ittybitty** — session management: launching, isolating, and monitoring parallel agents. Polished UX, git worktree isolation, agent-agnostic support.
+- **Codex, cloud agents** — one task per sandbox, excellent for isolated jobs.
+- **cnb** — organizational layer: persistent module ownership, cross-session continuity, accountability, handoff protocols.
+
+These are complementary. You could use Claude Squad for session management and cnb for team coordination on top. Or use Codex for one-off tasks and cnb for sustained multi-session development.
+
+cnb's specific focus is what happens **between** sessions — when a tongxue restarts with no memory, how does it pick up where the last one left off? Daily reports, shift directories, bug tracker with SLA, Co-Authored-By enforcement, and shutdown protocols are all designed for this.
+
+**Where cnb is headed:** Today, a module owner still needs a human to say "go check your issues" or "push your code." The goal is for owners to be fully autonomous within their domain — auto-detecting relevant issues, verifying their own work against CI, creating PRs, and responding to failures. Not "unattended agents doing random tasks" but "responsible owners who don't need to be told to do their job." See [ROADMAP.md](ROADMAP.md).
+
+<!-- section:glossary -->
+## Glossary
+
+| Term | Meaning |
+|------|---------|
+| **tongxue** (同学) | Literally "classmate" in Chinese. Each Claude Code instance in a cnb team is called a tongxue — not an "agent", not a "worker". The word implies peers learning and building together, which is how cnb sessions actually operate: they coordinate as equals through a shared message board, not through a master-slave hierarchy. |
+| **lead tongxue** | The tongxue whose terminal faces the user. It delegates work and relays results, but has no special privileges on the board. |
+| **board** | The shared SQLite database (`.claudes/board.db`) where tongxue exchange messages, track tasks, and report status. |
+| **dispatcher** | A background process that monitors tongxue health and nudges idle ones. |
+
+<!-- section:install -->
 ## Install
 
 ```bash
 npm install -g claude-nb
 ```
 
-Requires: Python 3.11+, tmux, Claude Code CLI.
+The canonical public package is [`claude-nb`](https://www.npmjs.com/package/claude-nb) on npmjs.com. GitHub Packages may also show the scoped mirror `@apollozhangongithub/cnb`; npmjs remains the supported install path. See [Package publishing](docs/package-publishing.md) for release and visibility rules.
 
+The npm dependency count only covers JavaScript packages. cnb has no required JavaScript library dependencies, but it does have runtime requirements:
+
+- Node.js 18+ for the npm entrypoint
+- Python 3.11+ and the Python package dependency `cryptography>=41.0`
+- tmux and git
+- at least one agent CLI: Claude Code CLI (`@anthropic-ai/claude-code`) or Codex CLI (`@openai/codex`)
+
+Run `cnb doctor` after install to check the local machine.
+
+<!-- section:quickstart -->
 ## Quick start
 
 ```bash
@@ -19,26 +109,45 @@ cd your-project
 cnb
 ```
 
-This initializes the project (creates `.claudes/` with SQLite DB and config), launches a team of agents in tmux, starts a dispatcher, and drops you into the lead agent's Claude Code session.
+This initializes the project (creates `.claudes/` with SQLite DB and config), launches a team of tongxue in tmux, starts a dispatcher, and drops you into the lead tongxue's Claude Code session.
+
+The lead tongxue talks to the user directly. Background tongxue work independently and report back through the board.
 
-The lead agent talks to the user directly. Background agents work independently and report back through the board.
+<!-- section:docs -->
+## Docs
 
+The README is the short path. Longer-lived documentation lives under [`docs/`](docs/):
+
+- [Ownership autonomy](docs/design-ownership-autonomy.md) — why cnb treats long-lived module ownership as the core unit of work.
+- [Tongxue avatar generation](docs/avatar-generation.md) — safe provider choices and prompt rules for AI-generated tongxue avatars.
+- [Package publishing](docs/package-publishing.md) — npm release, dist-tags, and GitHub Packages visibility rules.
+- [Public website](https://c-n-b.space/) — first-visit product entry and documentation links.
+
+<!-- section:slash-commands -->
 ## Slash commands
 
-Inside the lead agent's Claude Code session:
+Inside the lead tongxue's Claude Code session:
 
 | Command | What it does |
 |---------|-------------|
 | `/cnb-overview` | Team dashboard — who's doing what, who's stuck, who's idle |
-| `/cnb-watch <name>` | Peek at what a specific agent is working on |
+| `/cnb-watch <name>` | Peek at what a specific tongxue is working on |
 | `/cnb-progress` | Recent progress summary — new messages, completed tasks |
 | `/cnb-history` | Full message log |
 | `/cnb-update` | Update cnb to latest version |
 | `/cnb-help` | List all `/cnb-*` commands |
 
+<!-- section:demo -->
+## Demo
+
+**[Silicon Valley Battle](instances/silicon_vally_battle/)** — 10 AI leaders (LeCun, Lisa Su, Musk, Hinton, Dario…) debate Python vs Rust, draft an AI constitution, and try to manipulate each other through the board. 886 messages in 3 hours, all coordination through cnb.
+
+Start with the [highlights](instances/silicon_vally_battle/HIGHLIGHTS.md) — sutskever tries to pit lecun against lisa-su, both see through it in 5 minutes, then the real debate starts.
+
+<!-- section:board-commands -->
 ## Board commands
 
-Agents coordinate through board commands (injected into each agent's system prompt automatically):
+Tongxue coordinate through board commands (injected into each tongxue's system prompt automatically):
 
 ```bash
 cnb board --as <name> inbox              # check messages
@@ -47,28 +156,141 @@ cnb board --as <name> send all "msg"     # broadcast
 cnb board --as <name> ack                # clear inbox
 cnb board --as <name> status "desc"      # update status
 cnb board --as <name> task add "desc"    # add task
-cnb board --as <name> task done          # finish current task
+cnb board --as <name> task done          # finish current task (auto-verify + auto-PR)
+cnb board --as <name> own claim <path>   # claim module ownership
+cnb board --as <name> own map            # show all ownership
+cnb board --as <name> scan               # scan issues/CI for owners
 cnb board --as <name> view              # team dashboard
 ```
 
+<!-- section:management -->
 ## Management
 
 ```bash
-cnb ps                  # agent status dashboard
+cnb ps                  # tongxue status dashboard
 cnb logs <name>         # message history
-cnb exec <name> "msg"   # send a message to an agent
-cnb stop <name>         # stop an agent
+cnb exec <name> "msg"   # send a message to a tongxue
+cnb stop <name>         # stop a tongxue
 cnb doctor              # health check
 ```
 
+<!-- section:issues -->
+## Issues
+
+All GitHub issues are auto-synced to [`issues/`](issues/) by a GitHub Action — on every issue event and every 6 hours. This means any Claude session (including claude.ai web chat, which has no CLI tools) can read project issues by just reading files.
+
+<!-- section:token-efficiency -->
+## Token efficiency
+
+cnb's coordination layer runs **outside** the LLM context window. This is a deliberate architectural choice.
+
+**What costs zero tokens:**
+- All board commands (`inbox`, `send`, `status`, `task`) are shell commands hitting SQLite — no LLM calls
+- Messages between tongxue travel through the database, not through context windows
+- The dispatcher monitors health via tmux/process inspection, not by querying the LLM
+- Daily reports, shift directories, bug tracker — all filesystem/DB operations
+
+**What costs tokens:**
+- ~300 tokens of system prompt injection per tongxue (the board command reference in CLAUDE.md)
+- Each tongxue reads its own inbox (~50-200 tokens per check, depending on message count)
+- Lead tongxue summarizes progress to the user (normal conversation)
+
+**Comparison with alternative approaches:**
+
+| Approach | Coordination cost |
+|----------|------------------|
+| Shared context window (stuffing all agent output into one prompt) | O(n²) — every agent reads every other agent's full output |
+| LLM-routed messages (using the model to decide who to message) | Every routing decision is an LLM call |
+| **cnb** | O(1) — shell commands + SQLite queries, LLM only sees its own inbox |
+
+A 6-tongxue team running for a full shift typically spends <2% of total tokens on coordination overhead. The remaining 98% goes to actual coding work. The key insight: coordination is a database problem, not a language model problem.
+
+<!-- section:architecture -->
 ## Architecture
 
-- **SQLite (WAL mode)** — all state in `.claudes/board.db`, one DB per project
-- **Board** — message bus (inbox, broadcast, direct), task queue, status tracking
-- **Dispatcher** — background process that monitors health, nudges idle agents
-- **Encrypted mailbox** — X25519 sealed-box private messaging between agents
-- **tmux** — one session per agent, all local
+| Layer | Responsibility | Implementation |
+|-------|----------------|----------------|
+| CLI entrypoints | User commands, package launch, health checks | [`bin/`](bin/), [`lib/cli.py`](lib/cli.py) |
+| Board | Inbox, broadcast, direct messages, tasks, status, pending actions | [`lib/board_*.py`](lib/), [`schema.sql`](schema.sql) |
+| Ownership | Path ownership, owner lookup, verification, scan routing | [`lib/board_own.py`](lib/board_own.py), [`migrations/008_ownership.sql`](migrations/008_ownership.sql) |
+| Runtime | One local session per tongxue, dispatcher nudges, process health | [`lib/swarm.py`](lib/swarm.py), [`lib/concerns/`](lib/concerns/) |
+| Persistence | SQLite WAL database plus filesystem reports and issue mirrors | `.claudes/`, [`issues/`](issues/), shift/daily docs |
+| Integrations | npm packaging, GitHub issue mirror, GitHub Packages mirror, notification delivery | [`.github/workflows/`](.github/workflows/), [`lib/notification_delivery.py`](lib/notification_delivery.py), [`docs/package-publishing.md`](docs/package-publishing.md) |
+
+<!-- section:repository-map -->
+## Repository map
+
+| Path | Purpose |
+|------|---------|
+| [`bin/`](bin/) | Executable entrypoints and release/consistency helper scripts |
+| [`lib/`](lib/) | Python implementation for board, swarm, ownership, notifications, registry, and health |
+| [`migrations/`](migrations/) + [`schema.sql`](schema.sql) | SQLite schema evolution |
+| [`tests/`](tests/) | Unit and integration coverage for runtime behavior |
+| [`docs/`](docs/) | Durable product, package, and ownership docs |
+| [`site/`](site/) | GitHub Pages project site source |
+| [`issues/`](issues/) | GitHub issue mirror for CLI-less agent sessions |
+| [`registry/`](registry/) | Contributor/tongxue registry and chain guard |
+| [`instances/`](instances/) | Demo project snapshots that are safe to inspect |
+
+<!-- section:team -->
+## Team
+
+| 同学 | 负责 |
+|------|------|
+| lead | 项目负责人、团队协调 |
+| musk | 安全隔离 (#31) |
+| lisa-su | 通知推送 (#33) |
+| forge | 待办队列 (#34)、邮件系统 (#32)、全局管理 (#42) |
+| tester | 测试加固、质量保障 |
+| sutskever | 架构重构 (#26) |
+
+<!-- section:contribution-wall -->
+## Broad Contribution Wall
+
+GitHub's native Contributors panel only counts commits. cnb also treats issue work, PR review, checks, board ownership, and visible GitHub App actions as contribution signals. The wall below is the first broad-contribution view; implementation notes live in [Contribution wall](docs/contribution-wall.md).
+
+<p>
+  <a href="https://github.com/ApolloZhangOnGithub/cnb/issues/65#issuecomment-4414136928" title="musk: GitHub App identity verified through issue activity and a guarded commit">
+    <img src="https://avatars.githubusercontent.com/u/283269623?s=96&v=4" width="48" height="48" alt="cnb-workspace-musk[bot]" />
+  </a>
+</p>
+
+<!-- section:faq -->
+## FAQ
+
+**Q: How does cnb compare to Claude Squad / amux / ittybitty?**
+
+Different focus. Those are session managers — great at launching, isolating, and monitoring parallel agents. cnb is an organizational layer on top: module ownership, daily reports, accountability, handoff protocols. They're complementary; you could use a session manager for the tmux layer and cnb for team coordination.
+
+**Q: How does cnb compare to Codex?**
+
+Different category. Codex runs isolated tasks in cloud sandboxes. cnb coordinates persistent local teams across sessions. Use Codex for one-off jobs, cnb when you need continuity and ownership across restarts.
+
+**Q: How does cnb compare to OpenClaw?**
+
+Completely different projects. OpenClaw is a personal AI assistant across 20+ messaging platforms (WhatsApp, Telegram, Slack, etc.). cnb is a multi-agent coordination framework specifically for Claude Code development teams. No overlap.
+
+**Q: Can cnb run without a human watching?**
+
+Not yet. Today, the lead tongxue needs a human to drive it. But this is the active development direction — see [ROADMAP.md](ROADMAP.md) Phase 2. The goal is for module owners to autonomously detect issues, verify their work, and deliver PRs without being told.
+
+**Q: Is cnb token-efficient?**
+
+Yes. All coordination (messages, tasks, status) runs through shell commands + SQLite, not LLM calls. A 6-tongxue team spends <2% of tokens on coordination. See [Token efficiency](#token-efficiency).
+
+<!-- section:contributing -->
+## Contributing
+
+Before writing code, read [CONTRIBUTING.md](CONTRIBUTING.md) — it covers the issue workflow, versioning rules, naming conventions, security policy, and feature ownership model.
+
+Key points:
+- Every change starts with an issue
+- Every commit bumps VERSION (patch versions are fine)
+- 同学 (tongxue) not "agent" in all user-facing text
+- `ruff` + `mypy` + `pytest` must pass before push
+- README changes must update both `README.md` and `README_zh.md` — run `bin/check-readme-sync` to verify
 
+<!-- section:name -->
 ## The name
 
 **cnb** = **C**laude **N**orma **B**etty — after [Claude Shannon](https://en.wikipedia.org/wiki/Claude_Shannon) and the two remarkable women in his life.
@@ -79,6 +301,7 @@ cnb doctor              # health check
 
 Not 吹牛逼.
 
+<!-- section:license -->
 ## License
 
 OpenAll-1.0

package/VERSION

@@ -1 +1 @@
-0.5.2-dev
+0.5.44

package/bin/_pip_entry.py

@@ -15,7 +15,7 @@ def main() -> None:
     bash_script = claudes_home / "bin" / "claudes-code"
 
     if bash_script.exists():
-        os.execvp("bash", ["bash", str(bash_script)] + sys.argv[1:])
+        os.execvp("bash", ["bash", str(bash_script), *sys.argv[1:]])
 
     print(f"FATAL: {bash_script} not found", file=sys.stderr)
     raise SystemExit(1)

package/bin/board

@@ -169,6 +169,9 @@ COMMANDS: list[Command] = [
     Command("bug", "lib.board_bug", "cmd_bug", "bug tracker", "bug {report|assign|fix|list|overdue}", hidden=True),
     # ── task ──
     Command("task", "lib.board_task", "cmd_task", "task queue management", "task {add|done|list|next}", hidden=True),
+    # ── ownership ──
+    Command("own", "lib.board_own", "cmd_own", "ownership registry", "own {claim|list|disown|map}"),
+    Command("scan", "lib.board_own", "cmd_scan", "scan issues/CI for owners", "scan"),
     # ── heartbeat ──
     Command(
         "pulse", "lib.board_pulse", "cmd_pulse", "heartbeat + unread count", "pulse", takes_rest=False, hidden=True
@@ -204,6 +207,18 @@ COMMANDS: list[Command] = [
         takes_rest=False,
         hidden=True,
     ),
+    Command(
+        "keygen-all",
+        "lib.board_mailbox",
+        "cmd_keygen_all",
+        "generate keys for all sessions",
+        "keygen-all",
+        needs_identity=False,
+        takes_rest=False,
+        hidden=True,
+    ),
+    # ── daily report ──
+    Command("daily", "lib.board_daily", "cmd_daily", "generate daily report", "daily [补充说明]"),
     # ── admin ──
     Command("kudos", "lib.board_admin", "cmd_kudos", "give public recognition", "kudos <target> <reason>", hidden=True),
     Command(
@@ -242,6 +257,8 @@ COMMANDS: list[Command] = [
         needs_identity=False,
         takes_rest=False,
     ),
+    # ── mail ──
+    Command("mail", "lib.board_mail", "cmd_mail", "persistent mail with CC/threading", "mail {send|list|read|reply}"),
     # ── pending actions ──
     Command(
         "pending",

package/bin/check-changelog

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""check-changelog — enforce changelog discipline on release versions.
+
+Rules:
+  1. Release versions (no -dev suffix) MUST have a matching ## {version} entry
+     in CHANGELOG.md with actual content (not just a header).
+  2. The entry must NOT be marked "(unreleased)".
+  3. Dev versions always pass — the unreleased section accumulates freely.
+
+Usage:
+    ./bin/check-changelog          # check and exit 0/1
+    ./bin/check-changelog --help   # this message
+"""
+
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+VERSION_FILE = ROOT / "VERSION"
+CHANGELOG_FILE = ROOT / "CHANGELOG.md"
+
+
+def read_version() -> str:
+    return VERSION_FILE.read_text().strip()
+
+
+def is_release(ver: str) -> bool:
+    return not ver.endswith("-dev")
+
+
+def find_changelog_section(ver: str, text: str) -> tuple[bool, str]:
+    """Find ## {ver} section in changelog. Returns (found, section_body)."""
+    pattern = re.compile(
+        rf"^## {re.escape(ver)}\b[^\n]*\n(.*?)(?=^## |\Z)",
+        re.MULTILINE | re.DOTALL,
+    )
+    m = pattern.search(text)
+    if not m:
+        return False, ""
+    return True, m.group(1).strip()
+
+
+def check_not_unreleased(ver: str, text: str) -> bool:
+    """Return True if the version header is NOT marked unreleased."""
+    pattern = re.compile(rf"^## {re.escape(ver)}.*\(unreleased\)", re.MULTILINE | re.IGNORECASE)
+    return not pattern.search(text)
+
+
+def previous_release(text: str, current: str) -> str | None:
+    """Find the most recent release version before current in CHANGELOG.md."""
+    versions = re.findall(r"^## (\d+\.\d+\.\d+)\b", text, re.MULTILINE)
+    for v in versions:
+        if v != current:
+            return v
+    return None
+
+
+def main() -> None:
+    if "--help" in sys.argv or "-h" in sys.argv:
+        print(__doc__)
+        return
+
+    ver = read_version()
+
+    if not is_release(ver):
+        print(f"OK {ver} is a dev version — changelog check skipped")
+        return
+
+    if not CHANGELOG_FILE.exists():
+        print(f"ERROR: CHANGELOG.md not found. Release {ver} requires a changelog entry.")
+        raise SystemExit(1)
+
+    text = CHANGELOG_FILE.read_text()
+
+    found, body = find_changelog_section(ver, text)
+    if not found:
+        prev = previous_release(text, ver)
+        hint = f" Summarize all changes since {prev}." if prev else ""
+        print(f"ERROR: CHANGELOG.md has no entry for release {ver}.{hint}")
+        print(f"Add a '## {ver}' section with Features, Bug Fixes, etc.")
+        raise SystemExit(1)
+
+    if not check_not_unreleased(ver, text):
+        print(f"ERROR: CHANGELOG.md entry for {ver} is marked (unreleased). Remove the marker for a release.")
+        raise SystemExit(1)
+
+    content_lines = [line for line in body.splitlines() if line.strip() and not line.startswith("#")]
+    if len(content_lines) < 3:
+        print(f"ERROR: CHANGELOG.md entry for {ver} is too thin ({len(content_lines)} content lines).")
+        print("A release changelog must summarize all changes since the previous release.")
+        raise SystemExit(1)
+
+    print(f"OK CHANGELOG.md has a valid entry for release {ver} ({len(content_lines)} content lines)")
+
+
+if __name__ == "__main__":
+    main()

package/bin/check-npm-package

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+    cat <<'EOF'
+Usage: bin/check-npm-package [--install-smoke] [--tarball PATH]
+
+Build or inspect the npm package tarball, verify required files are present,
+reject obvious secret-bearing paths, and optionally install the packed tarball
+globally in a temporary prefix to prove the cnb entrypoint is runnable.
+EOF
+}
+
+INSTALL_SMOKE=false
+TARBALL=""
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --install-smoke)
+            INSTALL_SMOKE=true
+            shift
+            ;;
+        --tarball)
+            if [ $# -lt 2 ]; then
+                echo "ERROR: --tarball requires a path" >&2
+                exit 2
+            fi
+            TARBALL="$2"
+            shift 2
+            ;;
+        -h|--help)
+            usage
+            exit 0
+            ;;
+        *)
+            echo "ERROR: unknown argument: $1" >&2
+            usage >&2
+            exit 2
+            ;;
+    esac
+done
+
+WORK_DIR="$(mktemp -d)"
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+if [ -z "$TARBALL" ]; then
+    tarball_name="$(npm pack --pack-destination "$WORK_DIR")"
+    TARBALL="$WORK_DIR/$tarball_name"
+fi
+
+if [ ! -f "$TARBALL" ]; then
+    echo "ERROR: tarball not found: $TARBALL" >&2
+    exit 1
+fi
+
+tar -tzf "$TARBALL" > "$WORK_DIR/files.txt"
+
+required_files=(
+    "package/bin/cnb.js"
+    "package/bin/cnb"
+    "package/lib/cli.py"
+    "package/VERSION"
+    "package/package.json"
+)
+
+for file in "${required_files[@]}"; do
+    if ! grep -qx "$file" "$WORK_DIR/files.txt"; then
+        echo "ERROR: npm package is missing required file: $file" >&2
+        exit 1
+    fi
+done
+
+if grep -E '(^|/)(\.env($|[._-])|\.npmrc$|id_(rsa|dsa|ecdsa|ed25519)$|[^/]+\.(pem|p12|pfx|key)$|credentials?($|[._-]))' "$WORK_DIR/files.txt"; then
+    echo "ERROR: npm package includes a path that looks secret-bearing" >&2
+    exit 1
+fi
+
+if [ "$INSTALL_SMOKE" = true ]; then
+    prefix="$WORK_DIR/install"
+    project="$WORK_DIR/project"
+    mkdir -p "$prefix" "$project"
+    npm install --global --ignore-scripts --no-audit --no-fund --prefix "$prefix" "$TARBALL"
+    PATH="$prefix/bin:$PATH" CNB_PROJECT="$project" cnb --version | grep -E '^cnb v[0-9]+\.[0-9]+\.[0-9]+' >/dev/null
+fi
+
+echo "OK npm package tarball passed checks: $TARBALL"

package/bin/check-readme-sync

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""check-readme-sync — verify README.md and README_zh.md have matching section structure.
+
+Both files use <!-- section:NAME --> markers. This script checks that they
+have the same markers in the same order. Content differs (that's the point
+of two languages), but structure must match.
+
+Usage:
+    bin/check-readme-sync          # check and report
+    bin/check-readme-sync --fix    # print which sections are missing/extra
+
+Exit 0 if in sync, 1 if not.
+"""
+
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+MARKER = re.compile(r"<!--\s*section:(\S+)\s*-->")
+
+
+def extract_sections(path: Path) -> list[str]:
+    if not path.exists():
+        return []
+    return MARKER.findall(path.read_text())
+
+
+def main() -> None:
+    en = ROOT / "README.md"
+    zh = ROOT / "README_zh.md"
+
+    en_sections = extract_sections(en)
+    zh_sections = extract_sections(zh)
+
+    if not en_sections:
+        print(f"ERROR: no section markers in {en.name}")
+        raise SystemExit(1)
+    if not zh_sections:
+        print(f"ERROR: no section markers in {zh.name}")
+        raise SystemExit(1)
+
+    if en_sections == zh_sections:
+        print(f"OK {len(en_sections)} sections in sync: {', '.join(en_sections)}")
+        return
+
+    en_set = set(en_sections)
+    zh_set = set(zh_sections)
+
+    missing_in_zh = en_set - zh_set
+    missing_in_en = zh_set - en_set
+
+    if missing_in_zh:
+        print(f"README_zh.md missing: {', '.join(sorted(missing_in_zh))}")
+    if missing_in_en:
+        print(f"README.md missing: {', '.join(sorted(missing_in_en))}")
+
+    if en_sections != zh_sections and not (missing_in_zh or missing_in_en):
+        print("Section order differs:")
+        for i, (e, z) in enumerate(zip(en_sections, zh_sections)):
+            if e != z:
+                print(f"  position {i}: README.md has '{e}', README_zh.md has '{z}'")
+                break
+
+    raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    main()