@odarino/backlog.md 1.54.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,433 @@
+<p align="center">
+  <img src="./.github/backlog-logo.png" alt="Backlog.md logo" width="120">
+</p>
+
+<h1 align="center">Backlog.md</h1>
+<p align="center"><strong>Markdown‑native Task Manager &amp; Kanban visualizer for any Git repository</strong></p>
+<p align="center">AI agents write the code. You review the tasks: before, during, and after.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@odarino/backlog.md"><img src="https://img.shields.io/npm/v/@odarino/backlog.md?color=brightgreen" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@odarino/backlog.md"><img src="https://img.shields.io/npm/dm/@odarino/backlog.md" alt="npm downloads"></a>
+  <a href="https://github.com/odarino/Backlog.md/blob/main/LICENSE"><img src="https://img.shields.io/github/license/odarino/Backlog.md" alt="MIT license"></a>
+  <a href="https://github.com/odarino/Backlog.md"><img src="https://img.shields.io/github/stars/odarino/Backlog.md?style=social" alt="GitHub stars"></a>
+</p>
+
+<p align="center">
+<code>npm i -g @odarino/backlog.md</code>
+</p>
+
+## About this fork
+
+This is a fork of [MrLesk/Backlog.md](https://github.com/MrLesk/Backlog.md) with extra web UI features. The command is still `backlog`.
+
+> **Note:** Do not install this package and the original `backlog.md` globally at the same time. Both provide the `backlog` command. Uninstall one first: `npm uninstall -g backlog.md`.
+
+Homebrew and Nix install the upstream package, which does not have the fork features.
+
+### Fork features
+
+- **Image zoom.** Click an image in a task, a document, or a decision to open it full screen. Zoom with the mouse wheel, a double-click, or a pinch. Drag to pan. Use the arrow keys to move between all images of the task.
+- **Image upload, paste, and drag-drop.** Paste a screenshot or drop image files into any task editor. The server compresses each image to WebP and saves it under `backlog/assets/images/<task-id>/`. Images that you add before a task has an ID go to `_unsorted/`, and they move to the task folder when you create the task. An image that another task also links is copied, not moved.
+- **Image picker.** The image button in the editor toolbar opens a picker. Search, select, and insert existing images, or upload new ones.
+- **Workflow editor.** In Settings, add, rename, reorder, color, and delete statuses. A rename or delete rewrites the affected tasks in `tasks/`, `completed/`, and `archive/tasks/`. Status colors show on the board columns and in the task list.
+- **Clone task.** Copy a task into a new one from the task view (**Clone**), the CLI (`backlog task clone <id> [--title <title>]`), or MCP (`task_clone`). The copy keeps the content, labels, links, and checklists (unchecked), and resets the status (drafts stay drafts), due date, notes, summary, and comments.
+- **Safer local server.** The web server rejects requests from other websites and DNS rebinding.
+
+### Configuration
+
+| Key | Default | Range | Purpose |
+|-----|---------|-------|---------|
+| `image_max_dimension` | `1920` | 256–8192 | The longest side of a compressed image, in pixels |
+| `image_quality` | `0.8` | 0.1–1.0 | WebP quality |
+| `status_colors` | none | `#rrggbb` per status | Status colors, for example `{"Done":"#10b981"}` |
+
+### Limits
+
+- Images over 50 megapixels are rejected. Shrink them first.
+- GIF, SVG, and AVIF images are saved unchanged.
+- With `auto_commit` on, a rename or delete of a status makes one commit for the task files and `config.yml`. A Settings save also commits `config.yml`.
+- A running MCP server keeps the old status names until it restarts.
+- Tasks that exist only on other git branches are not rewritten when you rename or delete a status.
+- Two processes that change the workflow at the same moment can still conflict. Reload and try again.
+- The web UI accepts only `http://127.0.0.1:<port>` and `http://localhost:<port>`. Access through a tunnel or a proxy is blocked.
+
+![Backlog demo GIF using: backlog board](./.github/backlog-v1.40.gif)
+
+
+---
+
+> **Backlog.md** turns any folder into a **self‑contained project board**
+> powered by plain Markdown files and a zero‑config CLI.
+
+## Why Backlog.md in the AI era
+
+AI agents can now produce more plausible code in an hour than you can carefully read in a day.
+The bottleneck is no longer writing code. It's your attention. You can't meaningfully review
+15,000 generated lines in one sitting, but you can read a screenful of task specs with acceptance
+criteria before any code exists, and push back while a misunderstanding is still one sentence,
+not a rebuilt feature.
+
+Backlog.md structures agent work around **three review checkpoints**:
+
+1. **Review the spec:** the agent decomposes your idea into tasks with descriptions, acceptance
+   criteria, and milestones before implementation starts.
+2. **Review the plan:** the agent researches your codebase and writes its implementation plan
+   into the task. Approve it or steer before any code is written.
+3. **Review the code:** one task = one context window = one PR. Diffs stay a size a human can
+   actually read.
+
+Afterwards, the completed tasks remain in Git as a permanent record of what was attempted and why,
+legible to you, your team, and the next agent.
+
+**Dogfooded:** nearly all of Backlog.md's own code is written by AI agents working through
+Backlog.md itself. The full task ledger lives in this repo's [backlog folder](backlog/tasks).
+
+📺 **See it in action:** [Devoxx Belgium 2025](https://www.youtube.com/watch?v=LSoDQU_9MMA) · [AI Engineer Code Summit 2025](https://www.youtube.com/watch?v=zMXKhhwiCIc)
+
+## Features
+
+* 🤖 **AI-ready** -- works with Claude Code, Gemini CLI, Codex, Kiro & any other MCP or CLI compatible AI assistant
+
+* 📝 **Markdown-native tasks** -- every task is a plain `.md` file in your repo
+
+* ✅ **Acceptance criteria & Definition of Done** -- verifiable scope per task, plus a reusable DoD checklist for every new task
+
+* 🎯 **Milestones & dependencies** -- structure bigger efforts and make execution order reviewable, with task detail showing what a task waits on and what waits on it
+
+* 📊 **Terminal Kanban** -- `backlog board` paints a live board in your shell; `backlog board export` creates shareable markdown reports
+
+* 🌐 **Web UI** -- `backlog browser` serves a local Kanban board with drag-and-drop and task editing forms
+
+* 🔍 **Search** -- fuzzy search across tasks, docs & decisions with `backlog search`
+
+* 🔒 **Local-first** -- no server, no account, no telemetry; tasks are plain files in your repo, and remote Git operations are optional
+
+* 💻 Cross-platform (macOS, Linux, Windows) · 🆓 MIT-licensed & open-source
+
+
+---
+
+## <img src="./.github/5-minute-tour-256.png" alt="Getting started" width="28" height="28" align="center"> Getting started
+
+```bash
+# Install
+npm i -g @odarino/backlog.md
+# or: bun add -g @odarino/backlog.md
+
+# Initialize in any Git repo
+backlog init "My Awesome Project"
+
+# Or initialize without Git for local/non-code projects
+backlog init "Personal Planning" --no-git
+```
+
+> [!TIP]
+> **Running one-off with `npx`?** This tool's npm package is named `@odarino/backlog.md`, so use the full name: `npx @odarino/backlog.md init "My Project"`, `npx @odarino/backlog.md board`.
+> Without an install, `npx backlog` resolves to an unrelated third-party npm package — not this tool.
+> (With `@odarino/backlog.md` installed as a project dependency, `npx backlog` runs the local binary as usual.)
+
+### Run with Nix
+
+> **Note:** This installs the upstream package, without the fork features.
+
+Run Backlog.md directly from the repository flake:
+
+```bash
+nix run github:MrLesk/Backlog.md -- --version
+```
+
+Or install the named package into your Nix profile:
+
+```bash
+nix profile install github:MrLesk/Backlog.md#backlog-md
+```
+
+The Nix flake supports `x86_64-linux`, `aarch64-linux`, and
+`aarch64-darwin`. The x86_64 Linux package uses Bun's baseline runtime so it
+also works on pre-AVX2 processors with AVX support. Intel macOS users can use
+the npm, Bun, or Homebrew installation instead.
+
+The init wizard will ask how you want to connect AI tools:
+- **CLI instructions** (recommended): creates a short instruction file that tells agents to run `backlog instructions overview`.
+- **MCP connector**: optionally auto-configures Claude Code, Codex, Gemini CLI, Kiro or Cursor for teams that prefer MCP.
+- **Skip**: no AI setup; use Backlog.md purely as a task manager.
+
+For Cursor with CLI instructions, select AGENTS.md or pass `--agent-instructions cursor`; both use the same AGENTS.md target. Backlog.md preserves existing AGENTS.md content and does not migrate or remove unrelated user-managed `.cursor/rules` files.
+
+Everything is stored as human-readable Markdown in a project-local backlog folder such as `backlog/`, `.backlog/`, or a custom project-relative path configured through `backlog.config.yml` (e.g. `backlog_directory: my-backlog`). Task IDs use a configurable prefix (`backlog init --task-prefix`): the default produces `TASK-1`-style IDs, while this repository uses `back`, so examples below show `BACK-1`-style IDs. Git is optional: `backlog init --no-git` creates a filesystem-only project.
+
+---
+
+## Working with AI agents
+
+This is the recommended flow for Claude Code, Codex, Gemini CLI, Kiro and similar tools, following the **spec‑driven AI development** approach.
+After running `backlog init`, agents should start by running `backlog instructions overview`. Work in this loop:
+
+**Step 1: Describe your idea.** Tell the agent what you want to build and ask it to split the work into small tasks with clear descriptions and acceptance criteria.
+
+**🤖 Ask your AI Agent:**
+> I want to add a search feature to the web view that searches tasks, docs, and decisions. Please decompose this into small Backlog.md tasks.
+
+> [!NOTE]
+> **Review checkpoint #1:** read the task descriptions and acceptance criteria.
+
+**Step 2: One task at a time.** Work on a single task per agent session, one PR per task. Good task splitting means each session can work independently without conflicts. Make sure each task is small enough to complete in a single conversation. You want to avoid running out of context window.
+
+**Step 3: Plan before coding.** Ask the agent to research and write an implementation plan in the task. Do this right before implementation so the plan reflects the current state of the codebase.
+
+**🤖 Ask your AI Agent:**
+> Work on BACK-10 only. Research the codebase and write an implementation plan in the task. Wait for my approval before coding.
+
+> [!NOTE]
+> **Review checkpoint #2:** read the plan. Does the approach make sense? Approve it or ask the agent to revise.
+
+**Step 4: Implement and verify.** Let the agent implement the task.
+
+> [!NOTE]
+> **Review checkpoint #3:** review the code, run tests, check linting, and verify the results match your expectations.
+
+Mark verified work Done (or the configured final status). During periodic cleanup, use `backlog task complete` to move it off the board while preserving its record and dependency links. Use `backlog task archive` for canceled, duplicate, or invalid work; it removes incoming dependencies and task references.
+
+If the output is not good enough: clear the plan/notes/final summary, refine the task description and acceptance criteria, and run the task again in a fresh session.
+
+---
+
+## Working without AI agents
+
+Use Backlog.md as a standalone task manager from the terminal or browser.
+
+```bash
+# Create and refine tasks
+backlog task create "Render markdown as kanban"
+backlog task edit BACK-1 -d "Detailed context" --ac "Clear acceptance criteria"
+
+# Track work
+backlog task list -s "To Do"
+backlog task list --json | jq '.tasks[] | .id'
+backlog task edit BACK-1 --comment "Can we split the UI work into a separate PR?" --comment-author @sara
+backlog search "kanban"
+backlog board
+
+# Work visually in the browser
+backlog browser
+```
+
+You can switch between AI-assisted and manual workflows at any time; both operate on the same Markdown task files. Just prefer Backlog.md commands (CLI/MCP/Web) over hand-editing task files, so field types and metadata stay consistent.
+
+Read commands support stable, versioned JSON for scripts and integrations. Use `--json` with `task list`, `task view`, the `task <id>` shorthand, and `search`. JSON mode is noninteractive and keeps successful stdout machine-readable. Add `--watch` to `task list --json` for an initial full list followed by changed full replacements, using the exact same JSON format. Read successive complete JSON values; each response replaces the previous list.
+
+**Learn more:** [CLI reference](CLI-INSTRUCTIONS.md) | [Advanced configuration](ADVANCED-CONFIG.md)
+
+---
+
+## <img src="./.github/web-interface-256.png" alt="Web Interface" width="28" height="28" align="center"> Web Interface
+
+Launch a web interface for visual task management on the local machine. The server listens on `127.0.0.1` and is not
+reachable from other devices on the LAN or VPN:
+
+```bash
+# Start the web server (opens browser automatically)
+backlog browser
+
+# Custom port
+backlog browser --port 8080
+
+# Don't open browser automatically
+backlog browser --no-open
+```
+
+**Features:**
+- Interactive Kanban board with drag-and-drop
+- Multi-select cards to move several tasks to one column
+- Task creation and editing with forms
+- Interactive acceptance criteria editor with checklists
+- Real-time updates across all views
+- Responsive design for desktop and mobile
+- Task archiving with confirmation dialogs
+- Seamless CLI integration - all changes sync with markdown files
+
+![Web Interface Screenshot](./.github/web.jpeg)
+
+To keep the Web UI running as an auto-starting local service, see [Running Backlog.md as a Service](backlog/docs/doc-003%20-%20Running-Backlog-Browser-as-a-Service.md).
+
+---
+
+## 🔧 MCP Integration (Model Context Protocol)
+
+CLI instructions are the default AI setup. MCP remains supported for AI coding assistants like Claude Code, Codex, Gemini CLI and Kiro when you explicitly prefer an MCP connector.
+You can run `backlog init` (even if you already initialized Backlog.md) and choose MCP integration, or follow the manual steps below.
+
+### Client guides
+
+<details>
+  <summary><strong>Claude Code</strong></summary>
+
+  ```bash
+  claude mcp add backlog --scope user -- backlog mcp start
+  ```
+
+</details>
+
+<details>
+  <summary><strong>Codex</strong></summary>
+
+  ```bash
+  codex mcp add backlog -- backlog mcp start
+  ```
+
+</details>
+
+<details>
+  <summary><strong>Gemini CLI</strong></summary>
+
+  ```bash
+  gemini mcp add backlog -s user backlog mcp start
+  ```
+
+</details>
+
+<details>
+  <summary><strong>Kiro</strong></summary>
+
+  ```bash
+  kiro-cli mcp add --scope global --name backlog --command backlog --args mcp,start
+  ```
+
+</details>
+
+<details>
+  <summary><strong>Cursor / other MCP clients</strong></summary>
+
+  Use the manual JSON config below in your client's MCP settings.
+
+</details>
+
+Use the shared `backlog` server name everywhere. The server finds the active project from your client's MCP roots, and re-resolves when you switch workspace or worktree. A single user-scope server covers every repo.
+
+<details>
+  <summary><strong>Manual config</strong></summary>
+
+```json
+{
+  "mcpServers": {
+    "backlog": {
+      "command": "backlog",
+      "args": ["mcp", "start"],
+      "env": {
+        "BACKLOG_CWD": "/absolute/path/to/your/project"
+      }
+    }
+  }
+}
+```
+
+Set `BACKLOG_CWD` to pin the server to one project and stop workspace following. Use it to always target the same backlog, or when your client can't report MCP roots.
+If your IDE supports custom args but not env vars, you can also use `["mcp", "start", "--cwd", "/absolute/path/to/your/project"]`.
+Until the server finds an initialized project, it serves `backlog://init-required`.
+
+</details>
+
+> [!IMPORTANT]
+> When adding the MCP server manually, add a short instruction to your CLAUDE.md/AGENTS.md files telling agents to read `backlog://workflow/overview`.
+> This step is not required when using `backlog init` as it adds these instructions automatically.
+> For CLI-based setups, use `backlog instructions overview` to fetch the current workflow guidance.
+
+
+Once connected, agents can read the Backlog.md workflow instructions via `backlog://workflow/overview`, with detailed guides at `backlog://workflow/task-creation`, `backlog://workflow/task-execution`, and `backlog://workflow/task-finalization`.
+Use `/mcp` command in your AI tool (Claude Code, Codex, Kiro) to verify if the connection is working.
+
+---
+
+## <img src="./.github/cli-reference-256.png" alt="CLI Reference" width="28" height="28" align="center"> CLI reference
+
+Full command reference covering task management, search, board, docs, decisions, and more: **[CLI-INSTRUCTIONS.md](CLI-INSTRUCTIONS.md)**
+
+Quick examples: `backlog`, `backlog instructions`, `backlog task create`, `backlog task list`, `backlog task edit`, `backlog milestone add`, `backlog milestone rename`, `backlog milestone remove`, `backlog search`, `backlog board`, `backlog browser`.
+
+Full help: `backlog --help`
+
+---
+
+## <img src="./.github/configuration-256.png" alt="Configuration" width="28" height="28" align="center"> Configuration
+
+Backlog.md works with zero configuration. Settings merge from CLI flags, then the project config file (`backlog.config.yml` when present, otherwise `backlog/config.yml` or `.backlog/config.yml`), then built‑in defaults.
+
+Run `backlog config` with no arguments to launch the interactive wizard (the same experience triggered from `backlog init` advanced setup). It walks through cross-branch accuracy (`checkActiveBranches`, `remoteOperations`, `activeBranchDays`), Git workflow (`autoCommit`, `bypassGitHooks`), ID formatting (`zeroPaddedIds`), editor integration (`defaultEditor`), Definition of Done defaults, and Web UI defaults (`defaultPort`, `autoOpenBrowser`). Skipping the wizard applies the safe built-in defaults, and rerunning `backlog init` or `backlog config` pre-populates prompts with your current values.
+
+For filesystem-only projects (`backlog init --no-git`), the saved config forces `checkActiveBranches=false`, `remoteOperations=false`, and `autoCommit=false` so CLI, Web, and MCP local-file workflows do not depend on a Git repository.
+
+### Definition of Done defaults
+
+Set project-wide DoD items with `backlog config` (or during `backlog init` advanced setup), in the Web UI (Settings → Definition of Done Defaults), or by editing the project config file directly:
+
+```yaml
+definition_of_done:
+  - Tests pass
+  - Documentation updated
+  - No regressions introduced
+```
+
+When a project uses root config discovery, edit `backlog.config.yml` instead of `backlog/config.yml`.
+
+These items are added to every new task by default. You can add more on create with `--dod`, or disable defaults per task with `--no-dod-defaults`.
+
+For the full configuration reference (all options, default values, commands, and detailed notes), see **[ADVANCED-CONFIG.md](ADVANCED-CONFIG.md)**.
+
+---
+
+## Troubleshooting
+
+### Apple Silicon (macOS)
+
+On M-series Macs, `backlog` can fail with `illegal hardware instruction` or `Binary package not installed for darwin-...` when Node, Bun, or Homebrew run under Rosetta (x64 emulation) and install the Intel binary instead of the arm64 one — or the other way around. The launcher runs whichever darwin variant (arm64 or x64) is actually installed, but a clean native-arch install is the reliable fix.
+
+Check what your tools report:
+
+```bash
+uname -m                            # arm64 = Apple Silicon hardware; x86_64 = Intel or a Rosetta shell
+node -p process.arch                # architecture of your Node/Bun runtime
+sysctl -in sysctl.proc_translated   # 1 = current shell runs under Rosetta
+which brew                          # /opt/homebrew = arm64 brew, /usr/local = Intel brew
+```
+
+If the architectures disagree, reinstall with the native one:
+
+> **Note:** The Homebrew formula installs the upstream package, without the fork features.
+
+```bash
+# Homebrew: make sure `which brew` prints /opt/homebrew, then
+brew reinstall backlog-md
+```
+
+To keep the fork features, use npm or Bun:
+
+```bash
+# npm
+arch -arm64 npm i -g @odarino/backlog.md
+
+# Bun
+arch -arm64 bun add -g @odarino/backlog.md
+```
+
+Running an x64 Node under Rosetta on purpose also works: `backlog` falls back to whichever `@odarino/backlog.md-darwin-*` package is present.
+
+---
+
+## 📺 Talks & Community
+
+Watch Backlog.md in action:
+
+- **Devoxx Belgium 2025**: [the spec-driven agent workflow behind Backlog.md, live on stage](https://www.youtube.com/watch?v=LSoDQU_9MMA)
+- **AI Engineer Code Summit 2025**: [Backlog.md: task management for AI agents](https://www.youtube.com/watch?v=zMXKhhwiCIc)
+- Slides from these and more talks: [mrlesk.com/talks](https://mrlesk.com/talks)
+
+### Community tools
+
+- **[vscode-backlog-md](https://marketplace.visualstudio.com/items?itemName=ysamlan.vscode-backlog-md)** - VS Code extension with issues panel, kanban view, and editing. ([ysamlan/vscode-backlog-md](https://github.com/ysamlan/vscode-backlog-md))
+
+---
+
+## License
+
+Backlog.md is released under the **MIT License**: do anything, just give credit. See [LICENSE](LICENSE).

package/cli.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+
+const { spawn } = require("node:child_process");
+const { constants: osConstants } = require("node:os");
+const { getCandidatePackageNames, isRosettaTranslated, resolveBinaryPath } = require("./resolveBinary.cjs");
+
+// Matches a deep path to a platform package binary that some global shims pass as an argument.
+const PLATFORM_BINARY_PATH =
+	/node_modules[/\\]@odarino[/\\]backlog\.md-(darwin|linux|windows)-[^/\\]+[/\\]backlog(\.exe)?$/i;
+
+function printInstallHelp() {
+	console.error(`Detected: ${process.platform}-${process.arch} (Node ${process.version})`);
+	if (process.platform === "darwin") {
+		const rosetta = isRosettaTranslated();
+		console.error(`Rosetta translation: ${rosetta ? "yes" : "no"}`);
+		if (rosetta) {
+			console.error(
+				"Your Node/Bun runs as x64 under Rosetta on an Apple Silicon Mac, so the wrong CPU variant may have been installed.",
+			);
+		}
+		console.error("To fix on macOS:");
+		console.error("  - Compare architectures: `node -p process.arch` vs `uname -m` (arm64 = Apple Silicon hardware).");
+		console.error("  - npm on Apple Silicon: `arch -arm64 npm i -g @odarino/backlog.md`");
+		console.error("  - Bun on Apple Silicon: `arch -arm64 bun add -g @odarino/backlog.md`");
+		console.error("More details: https://github.com/odarino/Backlog.md#apple-silicon-macos");
+	} else {
+		console.error("Reinstall @odarino/backlog.md so the platform package matching this architecture gets installed.");
+	}
+}
+
+/**
+ * Spawn/exec failures that indicate a missing or wrong-architecture binary.
+ * macOS reports a wrong-arch Mach-O as EBADARCH (errno 86), which libuv has no
+ * name for, so it surfaces as errno -86 ("Unknown system error -86").
+ */
+function isBinaryInstallError(error) {
+	return error?.errno === -86 || error?.code === "EBADARCH" || error?.code === "ENOEXEC" || error?.code === "ENOENT";
+}
+
+function isArchitectureSignal(signal) {
+	return signal === "SIGILL" || signal === "SIGTRAP";
+}
+
+function getSignalExitCode(signal) {
+	const signalNumber = osConstants.signals[signal];
+	return signalNumber ? 128 + signalNumber : 1;
+}
+
+function handleSpawnError(binaryPath, error) {
+	if (isBinaryInstallError(error)) {
+		console.error(`Cannot execute ${binaryPath} (${error.code ?? error.errno}).`);
+		console.error("The binary is missing or was built for a different CPU architecture.");
+		printInstallHelp();
+	} else {
+		console.error("Failed to start backlog:", error);
+	}
+	process.exit(1);
+}
+
+function main() {
+	let binaryPath;
+	try {
+		binaryPath = resolveBinaryPath();
+	} catch {
+		console.error(`Binary package not installed for ${process.platform}-${process.arch}.`);
+		console.error(`Tried packages: ${getCandidatePackageNames().join(", ")}`);
+		printInstallHelp();
+		process.exit(1);
+	}
+
+	// Clean up unexpected args some global shims pass (e.g. bun) like the binary path itself
+	const rawArgs = process.argv.slice(2);
+	const cleanedArgs = rawArgs.filter((arg) => {
+		if (arg === binaryPath) return false;
+		// Filter any accidental deep path to our platform package binary
+		try {
+			return !PLATFORM_BINARY_PATH.test(arg);
+		} catch {
+			return true;
+		}
+	});
+
+	// Spawn failures can surface as a synchronous throw (e.g. ENOEXEC) or as an 'error' event
+	let child;
+	try {
+		child = spawn(binaryPath, cleanedArgs, {
+			stdio: "inherit",
+			windowsHide: true,
+			// Internal: lets a watch end when the process that started this launcher ends.
+			env: { ...process.env, BACKLOG_LAUNCHER: `${process.pid}:${process.ppid}` },
+		});
+	} catch (error) {
+		handleSpawnError(binaryPath, error);
+		return;
+	}
+
+	child.on("exit", (code, signal) => {
+		if (isArchitectureSignal(signal)) {
+			// Typical symptom of running a binary built for the other CPU architecture
+			console.error(`\nbacklog crashed with ${signal} (illegal instruction): ${binaryPath}`);
+			console.error("The installed binary was likely built for a different CPU architecture.");
+			printInstallHelp();
+			process.exit(1);
+		}
+		if (signal) {
+			process.exit(getSignalExitCode(signal));
+		}
+		process.exit(code ?? 1);
+	});
+
+	child.on("error", (error) => handleSpawnError(binaryPath, error));
+}
+
+if (require.main === module) main();
+
+module.exports = { PLATFORM_BINARY_PATH, getSignalExitCode, isArchitectureSignal, isBinaryInstallError };

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@odarino/backlog.md",
+  "version": "1.54.0",
+  "module": "src/cli.ts",
+  "files": [
+    "cli.js",
+    "resolveBinary.cjs",
+    "postuninstall.cjs",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "backlog": "cli.js"
+  },
+  "optionalDependencies": {
+    "@odarino/backlog.md-darwin-arm64": "1.54.0",
+    "@odarino/backlog.md-darwin-x64": "1.54.0",
+    "@odarino/backlog.md-linux-arm64": "1.54.0",
+    "@odarino/backlog.md-linux-x64": "1.54.0",
+    "@odarino/backlog.md-windows-arm64": "1.54.0",
+    "@odarino/backlog.md-windows-x64": "1.54.0"
+  },
+  "scripts": {
+    "postuninstall": "node postuninstall.cjs"
+  },
+  "lint-staged": {
+    "package.json": [
+      "biome check --write --files-ignore-unknown=true"
+    ],
+    "*.json": [
+      "biome check --write --files-ignore-unknown=true"
+    ],
+    "src/**/*.{ts,js}": [
+      "biome check --write --files-ignore-unknown=true"
+    ]
+  },
+  "author": "Alex Gavrilescu (https://github.com/MrLesk)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/odarino/Backlog.md"
+  },
+  "bugs": {
+    "url": "https://github.com/odarino/Backlog.md/issues"
+  },
+  "homepage": "https://github.com/odarino/Backlog.md#readme",
+  "keywords": [
+    "cli",
+    "markdown",
+    "kanban",
+    "task",
+    "project-management",
+    "backlog",
+    "agents"
+  ],
+  "license": "MIT",
+  "trustedDependencies": [
+    "@biomejs/biome",
+    "bun",
+    "node-pty"
+  ]
+}

package/postuninstall.cjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+const { spawn } = require("node:child_process");
+
+// Platform-specific packages to uninstall
+const platformPackages = [
+	"@odarino/backlog.md-linux-x64",
+	"@odarino/backlog.md-linux-arm64",
+	"@odarino/backlog.md-darwin-x64",
+	"@odarino/backlog.md-darwin-arm64",
+	"@odarino/backlog.md-windows-arm64",
+	"@odarino/backlog.md-windows-x64",
+];
+
+// Detect package manager
+const packageManager = process.env.npm_config_user_agent?.split("/")[0] || "npm";
+
+console.log("Cleaning up platform-specific packages...");
+
+// Try to uninstall all platform packages
+for (const pkg of platformPackages) {
+	const args = packageManager === "bun" ? ["remove", "-g", pkg] : ["uninstall", "-g", pkg];
+
+	const child = spawn(packageManager, args, {
+		stdio: "pipe", // Don't show output to avoid spam
+		windowsHide: true,
+	});
+
+	child.on("exit", (code) => {
+		if (code === 0) {
+			console.log(`✓ Cleaned up ${pkg}`);
+		}
+		// Silently ignore failures - package might not be installed
+	});
+}
+
+console.log("Platform package cleanup completed.");

package/resolveBinary.cjs

@@ -0,0 +1,57 @@
+const { execFileSync } = require("node:child_process");
+
+function getPackageName(platform = process.platform, arch = process.arch) {
+	return `@odarino/backlog.md-${platform === "win32" ? "windows" : platform}-${arch}`;
+}
+
+/**
+ * Package names to try, in order. On macOS both darwin variants are candidates
+ * because the OS can run whichever one is actually installed (natively or via
+ * Rosetta 2). A Rosetta-translated process reports x64 while the hardware is
+ * arm64, so under Rosetta the arm64 (hardware) package comes first.
+ */
+function getCandidatePackageNames(
+	platform = process.platform,
+	arch = process.arch,
+	rosetta = isRosettaTranslated(platform),
+) {
+	if (platform !== "darwin" || (arch !== "arm64" && arch !== "x64")) {
+		return [getPackageName(platform, arch)];
+	}
+	const primary = rosetta ? "arm64" : arch;
+	return [getPackageName(platform, primary), getPackageName(platform, primary === "arm64" ? "x64" : "arm64")];
+}
+
+/**
+ * True when the current process runs under Rosetta 2 translation on macOS.
+ * stdio ignores the child's stdin and stderr so restricted shells, where sysctl
+ * is not permitted, cannot leak "Operation not permitted" into our own stderr.
+ */
+function isRosettaTranslated(platform = process.platform, exec = execFileSync) {
+	if (platform !== "darwin") return false;
+	try {
+		return (
+			exec("/usr/sbin/sysctl", ["-in", "sysctl.proc_translated"], {
+				encoding: "utf8",
+				stdio: ["ignore", "pipe", "ignore"],
+			}).trim() === "1"
+		);
+	} catch {
+		return false;
+	}
+}
+
+function resolveBinaryPath(platform = process.platform, arch = process.arch, resolver = require.resolve) {
+	const binary = `backlog${platform === "win32" ? ".exe" : ""}`;
+	let firstError;
+	for (const packageName of getCandidatePackageNames(platform, arch)) {
+		try {
+			return resolver(`${packageName}/${binary}`);
+		} catch (error) {
+			firstError ??= error;
+		}
+	}
+	throw firstError;
+}
+
+module.exports = { getPackageName, getCandidatePackageNames, isRosettaTranslated, resolveBinaryPath };