@programinglive/dev-workflow-mcp-server 1.8.1 → 1.10.0

package/README.md

@@ -1,842 +1,565 @@
-# Development Workflow MCP Server
+# Dev Workflow MCP Server
+
+An MCP server that enforces development workflow discipline: **tests → documentation → commit → release**, with no way to skip a step.
+
+```mermaid
+graph LR
+    A[start_task] --> B[Implement]
+    B --> C[mark_bug_fixed]
+    C --> D[create_tests]
+    D --> E[run_tests]
+    E -- FAIL --> B
+    E -- PASS --> F[create_documentation]
+    F --> G[check_ready_to_commit]
+    G --> H[commit_and_push]
+    H --> I[perform_release / skip_release]
+    I --> J[complete_task]
+```
 
-<p align="left">
-  <a href="https://www.npmjs.com/package/@programinglive/dev-workflow-mcp-server"><img src="https://img.shields.io/npm/v/@programinglive/dev-workflow-mcp-server.svg" alt="npm version"></a>
-  <a href="https://www.npmjs.com/package/@programinglive/dev-workflow-mcp-server"><img src="https://img.shields.io/npm/dm/@programinglive/dev-workflow-mcp-server.svg" alt="npm downloads"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="license: MIT"></a>
-</p>
+---
 
-An MCP (Model Context Protocol) server that helps enforce development discipline and workflow best practices. This server acts as your coding conscience, reminding you to follow proper development workflows.
+## Quick Start
 
-### 🛡️ Resilience Features
-- **Startup Resilience**: 5-second connection timeouts for external databases.
-- **Background Loading**: Non-critical assets (compatibility mirrors) initialize in the background to ensure sub-second startup.
-- **Diagnostic Mode**: Automatic startup timing logs displayed in stderr.
+### 1. Clone and install
 
-## 🎯 Purpose
+```bash
+git clone https://github.com/programinglive/dev-workflow-mcp-server.git
+cd dev-workflow-mcp-server
+npm install
+```
 
-This MCP server guides you through a disciplined development workflow:
+`better-sqlite3` ships prebuilt binaries for Node 22 and newer (ABI 127, 137,
+141, 147). On Node 20 there is no prebuild for the current version, so npm falls
+back to `node-gyp` and you need [Python 3](https://python.org) and
+[Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
+on Windows. See [Troubleshooting](#troubleshooting).
 
-1. **Start Conscious** - Be clear about what you're coding
-2. **Fix/Implement** - Write your code
-3. **Create Tests** - Always test your changes
-4. **Run Tests** - Tests must pass (GREEN)
-5. **Document** - Update documentation
-6. **Commit & Push** - Let the server stage, commit, **and push** your changes once verification passes (if you make new edits afterward, the workflow moves back to this step automatically)
-7. **Release** - After the push succeeds, record the release details before closing out the task
+### 2. Verify the server runs
 
-## 🆕 What's New in v1.8.0
+```bash
+node index.js call get_workflow_status
+```
 
-- **Modular Handler Architecture** – `tools/handlers.js` now re-exports focused handler modules, improving maintainability and bundler behavior.
-- **Organized Test Suite** – The 1k-line `tests/handlers.test.js` has been split into `handlers-*.test.js` files with shared helpers, reducing duplication and clarifying intent.
-- **Shared Test Utilities** – New `tests/test-helpers.js` centralizes workflow state setup, request builders, and git mocks.
-- **Documentation Refresh** – PRD moved to `docs/PRD.md` root, status bumped to v1.8.0, and release notes updated to reflect the current workflow.
-- **Release Hygiene** – Recommended flow now includes `npm run release:<type>` followed by `git push --follow-tags origin main` to keep stages clean.
+Expected output:
 
-## 🚀 Installation
+```
+📊 Current Workflow Status:
 
-### Option 1: Install as Dependency in Your Project (Recommended)
+Phase: idle
+Task: (none)
+Feature flow: ❌
+...
+```
 
-Each project gets its own isolated workflow state file.
+### 3. Connect an MCP client
+
+See [MCP client configuration](#mcp-client-configuration).
+
+---
+
+## Available Tools
+
+22 tools.
+
+| Tool | Purpose |
+|---|---|
+| `start_task` | Begin a task (always the first step) |
+| `create_feature_flow` | Record the feature flow as Mermaid |
+| `mark_bug_fixed` | Mark the implementation done |
+| `create_tests` | Mark tests as written |
+| `skip_tests` | Skip tests with a justification |
+| `run_tests` | Record test results (blocks commit when failing) |
+| `create_documentation` | Mark docs as written |
+| `check_ready_to_commit` | Verify every required step is complete |
+| `commit_and_push` | `git add` → `commit` → `push` |
+| `perform_release` | Record a release |
+| `skip_release` | Skip the release step with a justification |
+| `complete_task` | Finish and reset the workflow |
+| `get_workflow_status` | Show the current phase |
+| `continue_workflow` | Get guidance on the next step |
+| `view_history` | List completed tasks |
+| `run_full_workflow` | Run every step in one call |
+| `rerun_workflow` | Restart the current task from the beginning |
+| `drop_task` | Abandon the task without completing it |
+| `force_complete_task` | Complete despite missing steps, with a reason |
+| `project_summary` | Aggregate activity for the project |
+| `project_summary_data` | Read the persisted `project-summary.json` |
+| `project_summary_db` | Read the per-user summary from SQLite |
+| `list_factory_tasks` | List your Factory task queue (requires config) |
+| `claim_factory_task` | Claim a Factory task and start a local workflow |
+| `sync_task_status` | Report a status change back to Factory |
+
+### Factory task integration
+
+Three tools connect this server to the **Factory** board at
+`factory.programinglive.com`. They read and write the real task table
+(`factory_tasks`), not the retired PocketBase `activity_tasks` collection
+(which still exists but holds 0 records and never reached the board).
+
+They stay **inert** until configured. With no configuration the server behaves
+exactly as before, and the tools reply with setup instructions.
 
 ```bash
-npm install @programinglive/dev-workflow-mcp-server
+FACTORY_URL=https://factory.programinglive.com
+FACTORY_EMAIL=<activity_users email>
+FACTORY_PASSWORD=<password>
 ```
 
-This will automatically create a `.state/workflow-state.json` file in the **project where you ran `npm install`** (using npm's `INIT_CWD`), keeping workflow history separate per project. If you're installing the package itself (inside `node_modules`), the script skips creation so it never pollutes the shared package directory.
-
-### Option 2: Install from Source
+Or supply a ready token instead of a password:
 
 ```bash
-git clone https://github.com/programinglive/dev-workflow-mcp-server.git
-cd dev-workflow-mcp-server
-npm install
+FACTORY_TOKEN=<PocketBase activity_users token>
 ```
 
-> **Windows prerequisites:** Installing dependencies from source compiles native modules such as `better-sqlite3`. Make sure Python 3 (added to PATH) and the Visual Studio Build Tools “Desktop development with C++” workload are installed before running `npm install`. Without them, npm will fail with a “need python” or build error.
-
-### Option 3: Install on Plesk Hosting
+Optional:
 
-Plesk supports Node.js applications through its Node.js extension. To deploy the MCP server on a Plesk subscription:
-
-1. **Enable Node.js support** – Ensure the Plesk administrator has installed the Node.js extension and enabled SSH access for your subscription.
-2. **Upload the project** – Either clone the repository or upload an archive into the directory you will run it from (e.g., `httpdocs/dev-workflow-mcp-server`). From SSH you can run:
-   ```bash
-   cd httpdocs
-   git clone https://github.com/programinglive/dev-workflow-mcp-server.git
-   cd dev-workflow-mcp-server
-   ```
-3. **Install dependencies** – In Plesk’s **Node.js** panel use “NPM install” (or run `npm install --production` over SSH). Linux hosts already ship the Python/build toolchain required for `better-sqlite3`; if your plan uses a Windows host, install Python 3 and the Visual Studio Build Tools beforehand or ask your provider to enable them.
-4. **Define environment variables** – In the Node.js panel add any environment variables you need (for example `DEV_WORKFLOW_USER_ID` or `DEV_WORKFLOW_STATE_FILE`). This keeps state files outside the web root if desired.
-5. **Configure the application** – Set **Application startup file** to `index.js` and **Application mode** to `production`. Plesk will run the server with `node index.js`.
-6. **Start/Restart the app** – Click “Restart App” so Plesk launches the MCP server with the new configuration. When you update the code, rerun “NPM install” and restart.
-
-> **Tip:** The MCP server communicates over stdio. If you only need it as a CLI tool, you can also run `npx @programinglive/dev-workflow-mcp-server` directly in an SSH session without keeping it running under the Node.js panel.
+```bash
+FACTORY_PB_URL=https://pocketbase.programinglive.com   # where the login happens
+FACTORY_MACHINE_ID=<name shown on the device row>       # defaults to the hostname
+FACTORY_DEVICE_ID=<fixed device UUID>                   # else derived from the name
+FACTORY_AGENT=dev-workflow-mcp                          # max 40 chars
+```
 
-> **Important:** MCP clients (Windsurf, Claude Desktop, etc.) must launch the server process locally via stdio. Hosting the dashboard on a public domain does **not** expose the MCP interface. Without SSH or another way to execute `node index.js` on the server, users cannot connect their MCP clients to the hosted instance.
+Use an **`activity_users` account, not a PocketBase superuser**. Factory accepts
+that token as `Authorization: Bearer <token>` for non-browser clients, and the
+account only sees its own tasks.
 
-### Option 4: Deploy with Docker on Google Cloud
+| Tool | Writes? | What it does |
+|---|---|---|
+| `list_factory_tasks` | no | Reads `GET /api/factory`, maps tasks plus their latest work session, and orders them status → priority. Defaults to `running, queued, backlog, review, blocked` |
+| `claim_factory_task` | yes | Opens a work session (`POST /api/work {action:start}`), which is what turns the task `running` on the board, then starts a local workflow |
+| `sync_task_status` | yes | Uses the only endpoint that can produce the status; see the table below |
 
-Deploy the MCP server to Google Cloud Compute Engine using Docker and PostgreSQL for a production-ready, cloud-hosted setup.
+#### Status mapping is not free-form
 
-**Quick Start:**
-1. SSH into your GCP instance
-2. Run the setup script: `bash scripts/setup-gcp-instance.sh`
-3. Clone the repository and configure `.env`
-4. Start containers: `docker-compose up -d`
-5. Update your local MCP client config to connect via SSH
+Factory has no generic "set status" endpoint, so the tool routes each status to
+the endpoint that actually supports it:
 
-**Benefits:**
-- ✅ PostgreSQL database for robust data persistence
-- ✅ Containerized deployment for consistency
-- ✅ Remote access via SSH tunneling
-- ✅ Easy updates and rollbacks
+| Requested status | Endpoint used | Result |
+|---|---|---|
+| `review`, `blocked`, `paused` | `POST /api/work {action:finish}` | Session closes, task changes accordingly |
+| `backlog`, `queued`, `cancelled` | `POST /api/factory {action:move_task}` | Board column changes |
+| `running` | — rejected | Point the caller at `claim_factory_task` |
+| `done` | — rejected | A human approves the work in Factory |
 
-See the [GCP Deployment Guide](./docs/GCP_DEPLOYMENT.md) for complete step-by-step instructions.
+`review` requires an active work session. Asking for it without one fails with
+"no active work session" instead of silently doing nothing — the task must be
+claimed first. Full behaviour, limits (summary 2000 chars, step 240 chars) and
+troubleshooting live in [docs/factory-integration.md](docs/factory-integration.md).
 
 
-#### Two Usage Modes
+### Example session
 
-- **Local (source)**: Point your MCP client to `index.js`. This runs directly from source and requires no build step. Recommended for MCP usage.
-- **Production (built)**: Run `npm run build` once to generate `dist/`. This creates an optimized bundle but isn’t needed for MCP usage.
+```
+"Start a new task: add user authentication, type: feature"
+→ start_task, phase moves to coding
 
-### 3. Configure in Windsurf/Claude Desktop
+[you write code]
 
-Point your MCP client to the server entry point. Replace `<PROJECT_ROOT>` with the absolute path to this repository on your machine.
+"Mark as fixed: login with JWT token"
+→ mark_bug_fixed, phase moves to testing
 
-#### macOS
+[you write tests]
 
-- **Windsurf** (`~/Library/Application Support/Windsurf/config.json`):
+"Create tests done"
+→ create_tests
 
-```json
-{
-  "mcpServers": {
-    "dev-workflow": {
-      "command": "node",
-      "cwd": "<PROJECT_ROOT>",
-      "args": ["index.js"],
-      "env": {
-        "DEV_WORKFLOW_DB_TYPE": "postgres",
-        "DEV_WORKFLOW_DB_URL": "postgres://USER:PASS@HOST:5432/devworkflow"
-      }
-    }
-  }
-}
-```
+"Run tests: passed=true, command='npm test', details='12 tests passed'"
+→ run_tests, phase moves to documentation
 
-- **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+"Create docs: type=README, summary='Added auth section'"
+→ create_documentation, phase moves to ready_to_commit
 
-```json
-{
-  "mcpServers": {
-    "dev-workflow": {
-      "command": "node",
-      "args": ["<PROJECT_ROOT>/index.js"]
-    }
-  }
-}
-```
+"Check if ready to commit"
+→ check_ready_to_commit → READY
 
-#### Windows
+"Commit and push: message='feat(auth): add JWT authentication'"
+→ commit_and_push, phase moves to release
 
-- **Windsurf** (`%APPDATA%\Windsurf\config.json`):
+"Perform release: command='npm run release:minor'"
+→ perform_release, phase moves to ready_to_complete
 
-```json
-{
-  "mcpServers": {
-    "dev-workflow": {
-      "command": "node",
-      "args": ["<PROJECT_ROOT>\\index.js"]
-    }
-  }
-}
+"Complete task: commitMessage='feat(auth): add JWT authentication'"
+→ complete_task, workflow reset to idle
 ```
 
-- **Claude Desktop** (`%APPDATA%\Claude\claude_desktop_config.json`):
+---
 
-```json
-{
-  "mcpServers": {
-    "dev-workflow": {
-      "command": "node",
-      "args": ["<PROJECT_ROOT>\\index.js"]
-    }
-  }
-}
-```
+## MCP client configuration
 
-#### Linux
+### OpenCode
 
-- **Windsurf** (`~/.config/windsurf/config.json`):
+OpenCode V2 nests servers under `mcp.servers` and does **not** accept an
+`enabled` key there. Config path is reported by `opencode debug paths`
+(`~/.config/opencode` on every platform, including Windows).
 
 ```json
 {
-  "mcpServers": {
-    "dev-workflow": {
-      "command": "node",
-      "args": ["<PROJECT_ROOT>/index.js"]
+  "mcp": {
+    "servers": {
+      "dev-workflow": {
+        "type": "local",
+        "command": ["node", "C:\\path\\to\\dev-workflow-mcp-server\\index.js"]
+      }
     }
   }
 }
 ```
 
-- **Claude Desktop** (`~/.config/claude/claude_desktop_config.json`):
+The simplest way to write this correctly is to let OpenCode do it:
 
-```json
-{
-  "mcpServers": {
-    "dev-workflow": {
-      "command": "node",
-      "args": ["<PROJECT_ROOT>/index.js"]
-    }
-  }
-}
+```bash
+opencode mcp add dev-workflow --global -- node "C:\path\to\dev-workflow-mcp-server\index.js"
 ```
 
-> **Note:** On Windows paths in JSON require escaped backslashes (e.g., `"C:\\path\\to\\project"`).
+### Claude Desktop
 
-#### Full Windsurf MCP Config Example (macOS)
-
-If you keep this repository checked out at `/Users/alex/code/dev-workflow-mcp-server` and want to point Windsurf at a hosted PostgreSQL instance, drop the following into `~/Library/Application Support/Windsurf/mcp_config.json`:
+`%APPDATA%\Claude\claude_desktop_config.json` (Windows) or
+`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
 
 ```json
 {
   "mcpServers": {
     "dev-workflow": {
       "command": "node",
-      "cwd": "/Users/alex/code/dev-workflow-mcp-server",
-      "args": ["index.js"],
-      "env": {
-        "DEV_WORKFLOW_DB_TYPE": "postgres",
-        "DEV_WORKFLOW_DB_URL": "postgres://devworkflow:devworkflow_secure_password@34.50.121.142:5432/devworkflow"
-      }
+      "args": ["C:\\path\\to\\dev-workflow-mcp-server\\index.js"]
     }
   }
 }
 ```
 
-This mirrors the Windows configuration shared in previous releases, but avoids `npx` lookup issues on macOS by launching the local `index.js` directly.
-
-### 4. Restart Windsurf/Claude Desktop
-
-After adding the configuration, restart the application to load the MCP server.
-
-
-### 5. Configure in Antigravity
+### Windsurf
 
-Antigravity users should configure the MCP server in their `mcp_config.json`.
-
-**Windows:** `%APPDATA%\Antigravity\mcp_config.json` or `C:\Users\<USERNAME>\.gemini\antigravity\mcp_config.json`
+`%APPDATA%\Windsurf\config.json` (Windows) or
+`~/Library/Application Support/Windsurf/config.json` (macOS):
 
 ```json
 {
   "mcpServers": {
     "dev-workflow": {
       "command": "node",
-      "args": ["<PROJECT_ROOT>\\index.js"]
+      "cwd": "C:\\path\\to\\dev-workflow-mcp-server",
+      "args": ["index.js"]
     }
   }
 }
 ```
 
-See [Antigravity Getting Started](./docs/antigravity/GETTING-STARTED.md) for detailed instructions and troubleshooting.
-
-### ⚡ Performance Optimization (Recommended)
-
-To ensure the fastest possible startup (critical for IDE-integrated clients like Claude Desktop), we recommend pointing directly to `index.js` using `node` rather than `npx`. This avoids the overhead of checking for package updates.
+### Antigravity
 
-**Optimized Configuration:**
+`%APPDATA%\Antigravity\mcp_config.json`:
 
 ```json
 {
   "mcpServers": {
     "dev-workflow": {
       "command": "node",
-      "args": ["<PROJECT_ROOT>\\index.js"],
-      "env": {
-        "DEV_WORKFLOW_USER_ID": "your_user_id"
-      }
+      "args": ["C:\\path\\to\\dev-workflow-mcp-server\\index.js"]
     }
   }
 }
 ```
 
-The server automatically times its own startup and logs it to stderr:
-`Dev Workflow MCP Server running on stdio (startup took 15ms)`
-
-## ⚙️ Configuration
-
-### Database Setup
+> **Performance:** run `node index.js` directly rather than through `npx`.
+> Startup is noticeably faster.
 
-The server supports **SQLite** (default), **MySQL**, and **PostgreSQL**.
+---
 
-#### Configuration via `.env`
-1. Copy `.env.example` to `.env`:
-   ```bash
-   cp .env.example .env
-   ```
-2. Edit `.env` with your settings:
-   ```ini
-   DEV_WORKFLOW_DB_TYPE=mysql
-   DEV_WORKFLOW_DB_URL=mysql://user:pass@localhost:3306/db
-   ```
+## Configuration
 
-#### Configuration via Environment Variables
-Alternatively, export variables directly:.
+### Database
 
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `DEV_WORKFLOW_DB_TYPE` | Database driver (`sqlite`, `mysql`, `postgres`) | `sqlite` |
-| `DEV_WORKFLOW_DB_URL` | Connection string for MySQL/Postgres | `null` |
-| `DEV_WORKFLOW_DB_PATH` | Override path for the SQLite database file | `<project>/.state/dev-workflow.db` |
+Defaults to **SQLite** (file-based, zero config). PostgreSQL and MySQL are also
+supported:
 
-#### Examples
-
-**MySQL:**
-```bash
-export DEV_WORKFLOW_DB_TYPE=mysql
-export DEV_WORKFLOW_DB_URL="mysql://user:password@localhost:3306/dev_workflow"
-```
-
-**PostgreSQL:**
 ```bash
-export DEV_WORKFLOW_DB_TYPE=postgres
-export DEV_WORKFLOW_DB_URL="postgresql://user:password@localhost:5432/dev_workflow"
+# .env or environment variable
+DEV_WORKFLOW_DB_TYPE=postgres
+DEV_WORKFLOW_DB_URL=postgresql://user:pass@localhost:5432/devworkflow
 ```
 
-#### 🛠️ Database Schema Normalization (Postgres/MySQL)
-To ensure compatibility with existing reporting dashboards, the `PostgresAdapter` and `MysqlAdapter` automatically normalize column names:
-- `task_description` → DB column: `description`
-- `timestamp` → DB column: `completed_at`
-
-The adapters use aliases in queries so the MCP tools still receive the expected `task_description` and `timestamp` fields.
-
-#### 👤 User ID Handling (Postgres/MySQL)
-These databases use an `INTEGER` column for `user_id`.
-- **Numeric strings** (e.g., `"1"`) are parsed directly into integers.
-- **Non-numeric strings** (e.g., `"programinglive"`) are automatically hashed into a consistent, positive integer to ensure compatibility with the schema while maintaining unique user isolation.
-
-
-### User & State Management
-
-| Variable | Description |
-|----------|-------------|
-| `DEV_WORKFLOW_USER_ID` | Override the auto-generated user ID (e.g., set to your name/email) |
-| `DEV_WORKFLOW_STATE_FILE` | Override the location of the `workflow-state.json` file |
-
-### Using Multiple Clients (Antigravity & Windsurf)
-
-If you use multiple AI coding tools simultaneously (e.g., Antigravity and Windsurf) on the same project, they will share the same workflow state by default.
+| Variable | Default | Description |
+|---|---|---|
+| `DEV_WORKFLOW_DB_TYPE` | `sqlite` | `sqlite`, `mysql`, or `postgres` |
+| `DEV_WORKFLOW_DB_URL` | — | Connection string (MySQL/Postgres) |
+| `DEV_WORKFLOW_DB_PATH` | `.state/dev-workflow.db` | SQLite path (optional) |
+| `DEV_WORKFLOW_USER_ID` | auto-generated | User ID for multi-user isolation |
+| `DEV_WORKFLOW_STATE_FILE` | auto-resolved | Override for `workflow-state.json` |
+| `FACTORY_URL` | - | Factory base URL, e.g. `https://factory.programinglive.com` |
+| `FACTORY_TOKEN` | - | PocketBase `activity_users` token sent as a Bearer header |
+| `FACTORY_EMAIL` | - | `activity_users` email, exchanged for a token on demand |
+| `FACTORY_PASSWORD` | - | Password for that account |
+| `FACTORY_PB_URL` | `https://pocketbase.programinglive.com` | Where the token is obtained |
+| `FACTORY_MACHINE_ID` | hostname | Device name shown on the Factory board |
+| `FACTORY_DEVICE_ID` | derived from the name | Stable device UUID |
+
+### Project-specific state
+
+Each project keeps its own state in `.state/users/<user-id>/workflow-state.json`.
+The `.state/` directory is gitignored.
+
+For multi-client isolation (for example separate state for Windsurf and
+Antigravity), set a different user ID per client:
 
-To maintain **separate, distinct sessions** for each tool, configure a unique `DEV_WORKFLOW_USER_ID` for each.
-
-**Antigravity Config (`mcp_config.json`):**
 ```json
 {
   "mcpServers": {
     "dev-workflow": {
       "command": "node",
-      "args": ["path/to/server/index.js"],
-      "env": {
-        "DEV_WORKFLOW_USER_ID": "antigravity_user"
-      }
+      "args": ["path/to/index.js"],
+      "env": { "DEV_WORKFLOW_USER_ID": "windsurf" }
     }
   }
 }
 ```
 
-**Windsurf Config:**
-Add the environment variable in your Windsurf MCP settings:
-```json
-{
-  "mcpServers": {
-    "dev-workflow": {
-      "command": "node",
-      "args": ["path/to/server/index.js"],
-      "env": {
-        "DEV_WORKFLOW_USER_ID": "windsurf_user"
-      }
-    }
-  }
-}
-```
+---
 
+## One-command stack setup (OpenCode V2)
 
-
-### ✅ Testing
-
-The project uses Node.js native test runner (`node --test`).
+`scripts/setup-stack.js` installs the whole agent stack: this MCP server,
+[obra/superpowers](https://github.com/obra/superpowers) skills, and
+[RTK](https://github.com/rtk-ai/rtk) token compression.
 
 ```bash
-npm test
+node scripts/setup-stack.js      # any platform
 ```
 
-This runs:
-- Unit tests for workflow logic
-- Integration tests for `.env` configuration
-- DB Adapter tests (SQLite always; MySQL/Postgres if configured)
+Platform wrappers install RTK, run `npm install`, then delegate to the same
+script:
 
-#### Testing Database Adapters
-To verify MySQL or PostgreSQL adapters, run tests with the environment variable set:
+```powershell
+pwsh scripts/bootstrap-windows.ps1
+```
 
 ```bash
-# Test MySQL
-export DEV_WORKFLOW_DB_URL="mysql://root:pass@localhost:3306/test_db"
-node --test tests/db-adapters.test.js
-
-# Test PostgreSQL
-export DEV_WORKFLOW_DB_URL="postgres://postgres:pass@localhost:5432/test_db"
-node --test tests/db-adapters.test.js
+bash scripts/bootstrap-unix.sh
 ```
 
-### Scripts
+### What it does
 
-- `npm run build` - Bundle the source into `dist/index.mjs` for distribution
-- `npm run dev` - Run in development mode with file watching
-- `npm run local` - Alias for running from source (same as `npm start`)
-- `npm run web` - Launch the lightweight workflow dashboard for browsing task history (see [Web Dashboard docs](./docs/web-dashboard.md))
+1. **Finds the real config directory.** Runs `opencode debug paths` and uses the
+   reported `config` path, falling back to `~/.config/opencode`. OpenCode V2
+   uses that path on Windows too — `%APPDATA%\opencode` is not read.
+2. **Backs up `opencode.json`** to `secrets/opencode-backup-<timestamp>.json`
+   before touching it.
+3. **Registers Superpowers** under the V2 `plugins` key. The V1 `plugin` key is
+   deprecated and ignored by V2.
+4. **Registers the MCP server** via `opencode mcp add`, which writes a
+   schema-valid `mcp.servers` entry.
+5. **Installs dependencies.** Without `npm install` the server dies at startup
+   with `ERR_MODULE_NOT_FOUND: Cannot find package 'dotenv'`.
+6. **Smoke tests the server**, then verifies with `opencode mcp list` and
+   `opencode plugin list`. Exits non-zero when a check fails.
+7. **Creates `AGENTS.md`** in the current project if missing.
 
-#### `npm run web`
+---
 
-This command starts the dashboard defined in `web/server.js`, giving you a quick view of workflow history and summary statistics.
+## Tests
 
 ```bash
-npm run web
-# 🌐 Dev Workflow Dashboard running at http://localhost:3111
+npm test                            # full suite
+node --test tests/setup-stack.test.js
 ```
 
-- **Default port:** 3111 (or the next free port if occupied).
-- **Environment overrides:** Honors `PORT` (common on hosts like Plesk/Render) or `DEV_WORKFLOW_WEB_PORT` before falling back to auto-selection.
-- **Query parameter:** `?user=<id>` lets you inspect another user’s history (defaults to `default`).
-- **API endpoints:**
-  - `GET /api/version` → current package version from `package.json` (used by dashboard to display version dynamically).
-  - `GET /api/summary?user=<id>` → overall stats for the user.
-  - `GET /api/history?user=<id>&page=1&pageSize=20&startDate=YYYY-MM-DD&endDate=YYYY-MM-DD` → paginated task history.
-  - `GET /api/history-summary?user=<id>&frequency=daily|monthly|yearly` → aggregated counts over time.
-
-Open `http://localhost:3111` in a browser to view the dashboard UI (`web/index.html`).
-
-### Build Output
-
-Running `npm run build` generates:
-- `dist/index.mjs` - Optimized ES module bundle
-- Source maps and other build artifacts
-- `dist/docs/` - Pre-rendered HTML documentation generated from Markdown via `scripts/build-docs.js`
-
-The build bundles all source files while externalizing Node.js built-in modules and dependencies, resulting in a single file distribution.
-
-### Usage
-
-For MCP server usage, point your client at `index.js` (source) to avoid stdio transport compatibility issues. The built `dist/index.mjs` is primarily for:
-- npm package distribution
-- Performance optimization
-- Embedding in other projects
-
-### MCP Tools Registry (Publishing)
-
-This package is configured for the official MCP Tools Registry using **npm package deployment**:
-
-- `package.json` declares `mcpName: "io.github.programinglive/dev-workflow-mcp-server"`.
-- `server.json` describes the server and links it to the npm package `@programinglive/dev-workflow-mcp-server`.
-
-To publish a new server version to the registry:
-
-1. Release a new npm version (for example):
-   - `npm test`
-   - `npm run release:patch` (runs your existing release pipeline and publishes to npm)
-2. Verify the new version exists on npm:
-   - `npm view @programinglive/dev-workflow-mcp-server version`
-3. Install the MCP publisher CLI (once per machine):
-   - `brew install mcp-publisher` (or follow the docs at https://modelcontextprotocol.info/tools/registry/publishing/)
-4. From this repo root, authenticate and publish:
-   - `mcp-publisher login github`
-   - `mcp-publisher publish`
-5. Optionally verify in the registry:
-   - `curl "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.programinglive/dev-workflow-mcp-server"`
-
-#### PowerShell CLI tip
-
-When invoking the lightweight CLI from PowerShell, use `--%` to prevent PowerShell from rewriting JSON arguments, for example:
-
-```powershell
-node --% index.js call start_task --args "{\"description\":\"Convert docs to HTML during build\",\"type\":\"feature\"}"
 ```
-
-The `--%` prefix and escaped double quotes ensure the JSON reaches the MCP server unchanged.
-
-## 📁 Project-Specific Workflow State
-
-When you install this package in a project, a `.state/workflow-state.json` file is automatically created in your project root. This file:
-
-- **Stores workflow history** specific to that project
-- **Tracks task progress** independently per project
-- **Should be gitignored** (already in `.gitignore` by default)
-- **Persists across sessions** so your workflow state is preserved
-- **Stays centralized** even if you run the server from nested build outputs like `dist/`. The MCP server walks back to the project root (looking for `.git` or `package.json`) before reading or writing workflow state, so you never need duplicate copies under build directories.
-
-Each project maintains its own isolated workflow history, so you can work on multiple projects without mixing their histories. Within that `.state` directory, the MCP server automatically creates a unique per-user subdirectory (e.g., `.state/users/user-abc123/`). The generated identifier persists locally so multiple developers sharing the same repository never clobber each other’s workflow files. If you prefer a specific name, set `DEV_WORKFLOW_USER_ID` before launching the server and that value will be used instead of the auto-generated ID.
-
-#### Choosing a User ID
-
-Use cases:
-
-1. **Let the server choose** – Do nothing and the first time you run any MCP tool the server creates `.state/users/<random-id>/`. The dashboard `User ID` filter accepts that value (visible in the folder name or in workflow responses).
-2. **Set an explicit ID** – Before starting the server, export `DEV_WORKFLOW_USER_ID`:
-
-   ```bash
-   # macOS/Linux
-   export DEV_WORKFLOW_USER_ID=alice
-   node index.js
-
-   # Windows PowerShell
-   $env:DEV_WORKFLOW_USER_ID = "alice"
-   node index.js
-   ```
-
-   Now all history for that session lands in `.state/users/alice/` and the dashboard can be filtered with `alice`.
-3. **Multiple users on one host** – Run separate processes (or MCP clients) with different `DEV_WORKFLOW_USER_ID` values. Each user’s workflow state remains isolated.
-
-> **Tip:** The web dashboard simply reads existing records. Typing a new value into the `User ID` filter will only return results after a workflow session has written history into `.state/users/<that-id>/`.
-
-### Adding to .gitignore
-
-If you're using this package, add this to your project's `.gitignore`:
-
-```
-.state/
+ℹ tests 112
+ℹ pass 110
+ℹ fail 0
+ℹ skipped 2
 ```
 
-This keeps workflow state local to each developer's machine.
-
-> **Need to override the location?** Set `DEV_WORKFLOW_STATE_FILE=/absolute/path/to/your/project/.state/workflow-state.json` before launching the server (or inside your MCP client config). The server will honor that path, letting you keep the package installed centrally while maintaining per-project workflow history.
+The two skipped tests are the MySQL and PostgreSQL adapters. They run only when a
+database is reachable:
 
-## 🛠️ Available Tools
-
-- `start_task` - Begin a new coding task
-- `mark_bug_fixed` - Mark the feature/bug as fixed (requires tests next)
-- `create_tests` - Mark that tests have been created
-- `skip_tests` - Skip tests with justification
-- `run_tests` - Record test results (must pass to proceed)
-- `create_documentation` - Mark documentation as created
-- `check_ready_to_commit` - Verify all steps are complete
-- `commit_and_push` - Commit and push changes
-- `perform_release` - Record release details (or use `skip_release` when the project has no release automation)
-- `complete_task` - Mark task as complete and reset
-- `force_complete_task` - Force completion with reason
-- `drop_task` - Abandon current task
-- `get_workflow_status` - Show current status
-- `view_history` - View completed tasks
-- `continue_workflow` - Get next-step guidance
-- `rerun_workflow` - Reset and restart the current task from the beginning
-- `run_full_workflow` - Execute every workflow step in sequence with a single command (requires supplying the details for each phase)
+```bash
+TEST_MYSQL_URL=mysql://user:pass@localhost:3306/db npm test
+TEST_POSTGRES_URL=postgres://user:pass@localhost:5432/db npm test
+```
 
-### `run_full_workflow`
+To exercise them against real servers without exposing them publicly:
 
-Use this when you already have all the information needed for each workflow phase and want to execute them in one go.
+```bash
+# on the database host, once: creates isolated devworkflow_test databases
+./scripts/setup-test-dbs.sh
 
-```json
-{
-  "summary": "Add payment webhooks",
-  "testCommand": "npm test",
-  "documentationType": "README",
-  "documentationSummary": "Document webhook configuration",
-  "commitMessage": "feat: add payment webhooks",
-  "releaseCommand": "npm run release:minor",
-  "releaseNotes": "Release webhook support",
-  "branch": "feature/payments",
-  "testsPassed": true,
-  "testDetails": "node --test; 42 tests",
-  "releaseType": "minor",
-  "preset": "minor"
-}
+# locally: opens an SSH tunnel, runs only the adapter tests, closes the tunnel
+TEST_POSTGRES_URL=... TEST_MYSQL_URL=... ./scripts/test-db-adapters.sh
 ```
 
-The tool will:
+Both adapters pass against live MySQL and PostgreSQL this way (19/19 tests, none
+skipped). The tests **write real rows**, so `setup-test-dbs.sh` creates separate
+`devworkflow_test` databases and grants the test role access only to those. Never
+point these variables at a production database.
 
-1. `mark_bug_fixed` using `summary`
-2. `create_tests`
-3. `run_tests` with `testsPassed`, `testCommand`, and optional `testDetails`
-4. `create_documentation` with `documentationType` and `documentationSummary`
-   - **Requires**: `docs/product/PRD.md` must exist before documentation can be marked complete
-5. `check_ready_to_commit`
-6. `commit_and_push` with `commitMessage` and optional `branch`
-7. `perform_release` with `releaseCommand`, plus optional `releaseNotes`, `releaseType`, and `preset`
-   - Alternatively call `skip_release` with a justification when the repository has no Node-based release step (e.g., Python-only or docs-only tasks)
-8. `complete_task` reusing `commitMessage`
+Everything else, including the SQLite adapter, always runs.
 
-All arguments except the optional flags are required and must be non-empty strings.
+`tests/test-helpers.js` exports `stripNpmNotices()`, which removes npm's own
+`npm warn`/`npm notice` output and Rollup's third-party annotation warnings from
+captured stderr before the build test asserts on it.
 
-### Documentation Requirements
+---
 
-The `create_documentation` step enforces that a PRD (Product Requirements Document) exists at `docs/product/PRD.md` before documentation can be marked as complete. This ensures all projects maintain a current PRD that describes the product's goals, features, and requirements.
+## CI
 
-## 🚫 Releasing Without the Workflow Steps
+`.github/workflows/ci.yml` runs on the **self-hosted runner on MMCH**, not on
+GitHub-hosted minutes:
 
-The package ships with a release guard (`release-wrapper.js`) that backs the `npm run release:*` scripts. The guard refuses to run unless:
+```yaml
+runs-on: [self-hosted, windows, mmch]
+```
 
-- The current workflow phase is **release**
-- `check_ready_to_commit` and `commit_and_push` have been completed
-- A release has not already been recorded for the active task
+| Job | Steps |
+|---|---|
+| `test` | `npm ci` → `npm test` → `build:server` → **verify the bundle starts** → `npm audit --omit=dev --audit-level=high` → setup-stack suite |
+| `web` | `npm ci` in `web/` → static export build → verify `out/index.html` and CSS size → `npm audit --audit-level=high` |
 
-If any requirements are missing, the guard exits with guidance to return to the MCP tools. This prevents accidentally bumping versions or tagging releases outside the managed workflow. To release correctly:
+The bundle verification step exists because a successful build does not mean
+the artefact runs. `dist/index.mjs` is the published package entry, and a
+bundler upgrade once produced a green build whose output crashed on startup.
+`scripts/verify-bundle.mjs` starts the bundle and requires the stdio startup
+banner, so that class of failure fails the pull request instead of the release.
 
-1. Use `perform_release {"command":"patch"}` (or `minor`/`major`) via the MCP client, or `skip_release {"reason":"<explanation>"}` if no release applies.
-2. The guard runs automatically, verifies the workflow state, and records the release before letting you finish with `complete_task`.
+The `web` job exists because the dashboard is deployed to Netlify from `web/`.
+The CSS size check catches a Tailwind regression that a green build would
+otherwise hide.
 
-### Automated npm Publishing
+### Tailwind stays on v3
 
-This repository ships with `.github/workflows/npm-publish.yml`, which publishes the package to npm whenever a git tag matching `v*` is pushed (for example, `v1.1.14`). To enable the workflow:
+`web/` uses Tailwind 3.4 and is **not** being migrated to v4. Tailwind 4 is a
+rewrite of the CSS pipeline: the `@tailwind` directives become
+`@import "tailwindcss"`, the config moves into CSS, and the PostCSS plugin is
+replaced by `@tailwindcss/postcss`. The dashboard is finished and stable, so
+rewriting its styling pipeline risks the entire visual design for no functional
+gain.
 
-1. Create an npm automation token with publish rights (`npm token create --read-only false`).
-2. In the repository settings, add a secret named **`NPM_TOKEN`** containing that token.
-3. Ensure your release process pushes tags after running `npm run release:<type>` so the workflow triggers.
-4. Confirm `npm run build` succeeds locally; the workflow runs the build before publishing so broken bundles block the release.
-5. GitHub provenance is enabled via `npm publish --provenance`. Leave GitHub Actions' default OIDC permissions enabled so the job can request an ID token.
-6. Keep the `repository.url` field in `package.json` pointing at this GitHub repo. Provenance validation fails if it does not match the repository that built the package.
+`dependabot.yml` ignores `tailwindcss`, `@tailwindcss/postcss` and
+`@tailwindcss/cli` entirely — not just majors — so no v4 pull request
+reappears.
 
-The workflow verifies that the tag version matches `package.json` before publishing and fails fast if they diverge.
+Runner provisioning and troubleshooting: [docs/homelab/ci-runner.md](./docs/homelab/ci-runner.md).
 
-## 🛠️ Available Tools
+---
 
-### Tool Argument Requirements
+## Release workflow
 
-All tool invocations validate their `arguments` payload before running:
-- Strings are parsed as JSON and must resolve to an object (key/value pairs).
-- Passing non-object data (numbers, arrays, plain text) triggers a guidance error.
-- Missing or malformed arguments safely default to empty input so the tool can respond with actionable reminders.
+`.github/workflows/github-release.yml` runs on a `v*` tag, split in two:
 
-Example (stringified JSON object):
-```
-{
-  "name": "start_task",
-  "arguments": "{\"description\":\"Add reporting endpoint\",\"type\":\"feature\"}"
-}
-```
+| Job | Runner | Work |
+|---|---|---|
+| `build` | self-hosted MMCH | `npm ci` → `npm test` → `build:server` → verify the bundle starts → `npm pack` → upload tarball |
+| `publish` | `ubuntu-latest` | download tarball → `npm publish` → create/update the GitHub release |
 
-### `start_task`
-Start a new coding task. This is your first step - be conscious about what you're coding.
+Publishing uses **Trusted Publishing (OIDC)**: no long-lived npm token is stored
+anywhere, and `id-token: write` plus `registry-url` on `setup-node` is the whole
+configuration. The trusted publisher is registered with `npm trust`:
 
-**Parameters:**
-- `description` (string, required): Clear description of what you're going to code
-- `type` (enum, required): Type of task - "feature", "bugfix", "refactor", or "other"
-
-**Example:**
-```
-Use the start_task tool with:
-- description: "Add user authentication to the login page"
-- type: "feature"
+```bash
+npm trust github @programinglive/dev-workflow-mcp-server \
+  --file .github/workflows/github-release.yml \
+  --repo programinglive/dev-workflow-mcp-server \
+  --allow-publish -y
 ```
 
-### `mark_bug_fixed`
-Mark that the bug/feature is fixed. **Reminder: Now you MUST create tests!**
-
-**Parameters:**
-- `summary` (string, required): Brief summary of what was fixed/implemented
-
-### `create_tests`
-Confirm that you've created the necessary tests covering your change. Required before recording test results.
-
-**Parameters:** _none_
-
-### `skip_tests`
-Record an explicit justification when automated tests aren't feasible. Marks testing as satisfied so you can proceed with documentation and verification, while flagging the task for manual QA.
-
-**Parameters:**
-- `reason` (string, required): Why automated tests were skipped
+The `file` must match the workflow filename exactly, or OIDC is rejected.
 
-### `run_tests`
-Record test results. **NEVER commit if tests fail!** Only proceed if all tests are green.
+### No provenance
 
-**Parameters:**
-- `passed` (boolean, required): Did all tests pass?
-- `testCommand` (string, required): The test command that was run
-- `details` (string, optional): Test results details
+`--provenance` is intentionally **not** used. npm rejects provenance bundles
+whose source repository is private:
 
-**Example:**
 ```
-Use run_tests with:
-- passed: true
-- testCommand: "npm test"
-- details: "All 15 tests passed"
+422 Unprocessable Entity - Unsupported GitHub Actions source repository
+visibility: "private". Only public source repositories are supported when
+publishing with provenance.
 ```
 
-### `create_documentation`
-Mark that documentation has been created/updated. This is required before committing.
+This repository is private by policy, so provenance is unavailable. Consumers
+cannot cryptographically verify which commit produced a published tarball.
 
-**Parameters:**
-- `documentationType` (enum, required): "PRD", "README", "RELEASE_NOTES", "inline-comments", "API-docs", "changelog", or "other"
-- `summary` (string, required): What was documented
+### What ships in the package
 
-### `check_ready_to_commit`
-Check if all workflow steps are completed and you're ready to commit & push.
+`.npmignore` limits the tarball to the runtime server: about 60 files and 66 kB.
+It excludes `.env*` (only `.env.example` ships), `.state/`, tests, CI config,
+`web/`, and docs.
 
-### `commit_and_push`
-Automatically run `git add`, `git commit`, and `git push` after the ready check passes.
+`scripts/install-husky.js` runs from `prepare`. It installs git hooks only when a
+`.git` directory is present, so installing the package as a dependency does not
+fail on husky.
 
-**Auto-detection of primary branch:** If no `branch` is specified, the tool automatically detects your project's primary branch by checking for `origin/main` first, then falling back to `origin/master`. This eliminates the need to specify the branch parameter for most projects.
+---
 
-**Parameters:**
-- `commitMessage` (string, required): Conventional commit message to use
-- `branch` (string, optional): Target branch to push. If omitted, auto-detects primary branch (main or master)
+## What this server prevents
 
-### `perform_release`
-Record the release after you've committed and pushed. Required before you can complete the task.
+- Committing without tests
+- Committing with failing tests
+- Committing without documentation
+- Forgetting a workflow step
+- Releasing without committing and pushing
 
-**Parameters:**
-- `command` (string, required): Release command that was executed (e.g., `npm run release`)
-- `notes` (string, optional): Additional release notes
+---
 
-### `complete_task`
-Mark the task as complete after successful commit & push. Resets workflow for next task.
+## Tips
 
-**Parameters:**
-- `commitMessage` (string, required): The commit message used
+1. Always start with `start_task` — it sets the intent for the session
+2. Do not skip tests unless it is genuinely impossible — use `skip_tests` with a clear reason
+3. Call `get_workflow_status` whenever you lose track of the phase
+4. `run_full_workflow` is a shortcut for simple tasks where all the data is already known
+5. For docs-only work, use `skip_release` rather than forcing a release
 
-### `drop_task`
-Abandon the current task without completing the workflow. Preserves an audit entry with context, then resets the state so you can start fresh.
+---
 
-**Parameters:**
-- `reason` (string, optional): Additional detail about why the task was dropped
+## Troubleshooting
 
-### `get_workflow_status`
-Get current workflow status and what needs to be done next.
+**`ERR_MODULE_NOT_FOUND: Cannot find package 'dotenv'`** — dependencies are not
+installed. Run `npm install` in the repo.
 
-### `view_history`
-View workflow history of completed tasks.
+**`gyp ERR! find VS` on Windows** — the native module is compiling from source
+because there is no prebuild for your Node ABI. Either switch to a Node version
+that has one, or install Visual Studio Build Tools.
 
-**Parameters:**
-- `limit` (number, optional): Number of recent tasks to show (default: 10)
+**`EPERM ... better_sqlite3.node`** — a running process holds the file. Stop it,
+then reinstall.
 
-## 📋 Available Prompts
+**OpenCode does not load the server** — check the config shape. V2 requires
+`mcp.servers` and rejects `enabled`:
 
-### `workflow_reminder`
-Get a complete reminder of the development workflow discipline.
-
-### `pre_commit_checklist`
-Get a pre-commit checklist to ensure nothing is missed before committing.
-
-## 🔄 Typical Workflow
-
-Here's how you'd use this MCP server in a typical coding session:
-
-1. **Start your task:**
-   ```
-   Ask Cascade to use start_task:
-   "Start a new task: implementing user profile page, type: feature"
-   ```
-
-2. **Code your feature/fix**
-   - Write your code as usual
-
-3. **Mark as fixed:**
-   ```
-   "Mark the feature as fixed: User profile page with avatar and bio completed"
-   ```
-
-4. **Create tests:**
-   - Write your tests
-   - The server will remind you this is mandatory!
-
-5. **Run tests:**
-   ```
-   "Record test results: passed=true, command='npm test'"
-   ```
-   - If tests fail, the server will **block** you from proceeding!
-
-7. **Document:**
-   ```
-   "Create documentation: type=README, summary='Added user profile section to docs'"
-   ```
-
-8. **Check readiness:**
-   ```
-   "Check if I'm ready to commit"
-   ```
-
-9. **Commit & Push:**
-   ```
-   "Commit and push: commitMessage='feat: add user profile page with tests and docs'"
-   ```
-
-10. **Record release:**
-   ```
-   "Record release: command='npm run release', notes='v1.2.3'"
-   ```
-
-11. **Complete:**
-   ```
-   "Complete the task with commit message: 'feat: add user profile page'"
-   ```
-
-12. **Drop task (optional):**
-   ```
-   "Drop task: reason='Switching to a different feature'"
-   ```
+```bash
+opencode mcp list          # should show: dev-workflow  connected
+```
 
-## 🎯 Key Features
+---
 
-- **Enforces discipline**: Won't let you skip steps
-- **Test-driven**: Blocks commits if tests fail
-- **Documentation reminder**: Ensures you document your work
-- **State tracking**: Remembers where you are in the workflow
-- **History**: Keeps track of completed tasks
-- **Prompts**: Quick reminders of best practices
+## Build
 
-## 🚫 What This Server Prevents
+```bash
+npm run build    # → dist/index.mjs (optimized bundle, used for npm distribution)
+npm run web      # → dashboard on http://localhost:3000
+```
 
-- ❌ Committing without tests
-- ❌ Committing with failing tests
-- ❌ Committing without documentation
-- ❌ Losing track of what you're working on
-- ❌ Skipping important workflow steps
+For MCP use, point the client at `index.js` directly — startup is faster than the
+bundled `dist/index.mjs`.
 
-## 💡 Tips
+---
 
-1. **Always start with `start_task`** - This sets your intention
-2. **Never skip tests without justification** - Use `skip_tests` only when absolutely necessary and document the reason for manual QA
-3. **Use `get_workflow_status`** - Check where you are anytime
-4. **Review history** - Learn from your past tasks
-5. **Follow the prompts** - They contain best practices
+## Homelab Development Guide
 
-## 🔧 Customization
+This repository also documents the internal **programinglive** homelab: Tailscale
+plus SSH across three machines (MMCH, HELLOWORLD, Mac).
 
-You can modify the workflow in `index.js`:
-- Add more workflow phases
-- Customize reminders
-- Add integration with your test runner
-- Add custom validation rules
+| Document | Contents |
+|---|---|
+| [docs/homelab/README.md](./docs/homelab/README.md) | Overview and quick reference |
+| [docs/homelab/infra-tailnet-ssh.md](./docs/homelab/infra-tailnet-ssh.md) | Tailnet and SSH setup |
+| [docs/homelab/cli-tools.md](./docs/homelab/cli-tools.md) | CLI tools per machine |
+| [docs/homelab/ci-runner.md](./docs/homelab/ci-runner.md) | Self-hosted CI runner on MMCH |
+| [docs/homelab/security-rules.md](./docs/homelab/security-rules.md) | Security rules |
+| [.agent/workflows/homelab-setup.md](./.agent/workflows/homelab-setup.md) | MCP workflow for onboarding a new machine |
 
-## 📝 State Management
+> ⚠️ This repository is **private**. Do not share it publicly.
 
-The server maintains state in `.state/workflow-state.json`:
-- Current phase
-- Task description
-- Completion status of each step
-- History of completed tasks
+---
 
-This file is automatically created and managed by the server.
-It contains local, machine-specific progress and is ignored by git so each environment can manage its own workflow history without cross-contamination.
-
-## 🤝 Integration with Your Rules
-
-This MCP server aligns with your existing development rules:
-- ✅ Enforces test-first discipline
-- ✅ Prevents commits with failing tests
-- ✅ Reminds about documentation
-- ✅ Tracks workflow state
-- ✅ Maintains history
-
-## 📄 License
+## License
 
 MIT
-
-## 🙏 Contributing
-
-Feel free to customize this server to match your specific workflow needs!
-
-## 📜 Project Governance
-
-- [Code of Conduct](./CODE_OF_CONDUCT.md)
-- [Contributing Guide](./CONTRIBUTING.md)
-- [Security Policy](./SECURITY.md)
-- [License](./LICENSE)