优先级锻造

Install dependencies

npm install

Prerequisites (one-time, Windows side)

1. Install WSL2 + Ubuntu: in PowerShell as Administrator —

   wsl --install -d Ubuntu
   

   sudo tee -a /etc/wsl.conf >/dev/null <<'EOF'
   [boot]
   systemd=true
   EOF
   

   wsl --shutdown
   

   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
   exec bash
   nvm install 20
   

One-Command Setup (Recommended)

```bash

Run the setup script - handles everything!

bash setup.sh ```

The setup script will: 1. Check for and install prerequisites (Node.js via Homebrew or nvm) 2. Install npm dependencies 3. Initialize your task database 4. Interactively configure your AI tool (Cursor, Droid, Claude Code, or Codex) 5. Verify everything works

Manual Setup

If you prefer manual control:

```bash

Quick Install

```bash

Install and start all services

./setup.sh install-launchd ```

This will: - Copy launch agent files to ~/Library/LaunchAgents/ - Update paths to match your installation - Load and start all three services (backend, frontend, watchdog) - Verify they're running correctly

Uninstall launch agents

./setup.sh uninstall-launchd ```

Switched Node.js installations?

The deployed plists contain the absolute path to the node and npm binaries that were on PATH when the installer ran. If you migrate between Homebrew / the official .pkg installer / nvm / Volta / fnm / asdf, re-run ./setup.sh install-launchd so the plists are regenerated with the new binary paths.

Manual Installation

If you prefer manual control, see detailed instructions in launchd/README.md.

Note: Launch agents only work on macOS. For Linux, see below. For Windows, see Windows Support.

---

Quick Install

./setup.sh install-systemd

This copies unit files to ~/.config/systemd/user/, enables linger so services start at boot (not just at login), and starts all three services immediately.

Setup & Configuration

bash setup.sh # Full setup (prerequisites, deps, MCP config) npm run setup:mcp # Configure MCP for your AI tool (interactive) npm run seed # Initialize/reset database npm run verify # Verify setup is working

Install priority-forge

Critical: clone into your WSL home, NOT /mnt/c/....

cd ~
git clone https://github.com/Unobtainiumrock/priority-forge.git
cd priority-forge
./setup.sh install

Why not /mnt/c/? WSL's /mnt/<drive>/ mounts use DrvFs, which is roughly 100x slower than ext4 for SQLite writes and is unreliable for the chokidar file-watcher used by Vite and tsx watch. The stack will appear to install, then silently miss reloads and corrupt data on concurrent writes. setup.sh and npm run setup:mcp will refuse to run from /mnt/<drive>/ paths; override with PRIORITY_FORGE_ALLOW_CROSS_MOUNT=1 only for read-only smoke tests.

Team Deployment

For team use with shared tasks, deploy to a shared server:

{
  "mcpServers": {
    "priority-forge": {
      "type": "http",
      "url": "https://your-server.example.com/mcp"
    }
  }
}

For individual use, each team member runs their own local instance with their own tasks.

Quick Start

Initialize your database (creates example project/task)

npm run seed

Configure MCP for your AI tool (interactive)

npm run setup:mcp

Verify everything works (optional)

npm run verify ```

Server runs at http://localhost:3456

Note: The data/progress.json file is gitignored - each user maintains their own task database. Run the seed script to create your initial database.

---

Configuration Summary

Here's a quick reference for all configuration file locations:

Claude Code note: Claude Code reads CLAUDE.md, not AGENTS.md. Project-scoped .mcp.json servers prompt once for approval on first use; local-scoped servers added with claude mcp add --scope local are the personal no-prompt option.

<details> <summary>Manual Agent Rules Configuration (click to expand)</summary>

Copy the contents of AGENT_RULES.md to the appropriate agent rules location above.

</details>

Environment Variables

MCP Configuration Differences by Tool

Droid and Claude Code require the explicit "type": "http" field because they support multiple transport types (HTTP, stdio, etc.). Cursor infers HTTP from the URL.

REST API Endpoints

Core Endpoints

V2 Priority Endpoints

REST Endpoints

Export training data via API

curl http://localhost:3456/ml/export

MCP Prompts (Workflow Templates)

MCP Integration

If you used ./setup.sh or npm run setup:mcp, MCP is already configured! Otherwise, configure manually:

<details> <summary>Manual MCP Configuration (click to expand)</summary>

Prompts (V2.1 - Workflow Templates)

What's Per-Workspace vs Global

Backend dies when I close VS Code / my terminal

If you started the backend with npm run dev inside an editor's integrated terminal (VS Code, Cursor, etc.), the node process becomes a child of the editor's shell. When the editor closes or crashes, it sends SIGHUP to its process tree and the backend dies with it. The frontend may appear to survive if it was started a different way (e.g. via ./setup.sh start, which uses nohup to detach).

Fix — pick one:

• Persistent services (recommended): ./setup.sh install-systemd on Linux, or re-run ./setup.sh install on macOS and accept the launchd prompt. Services run independently of any shell and auto-start on boot.
• Detached dev mode: ./setup.sh start — uses nohup so processes survive the terminal closing. Won't survive a reboot.

Avoid: npm run dev in a VS Code/Cursor integrated terminal for anything other than a quick one-off test.

Troubleshooting