@programinglive/dev-workflow-mcp-server 1.2.1 → 1.2.2

package/CHANGELOG.md

@@ -2,6 +2,89 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [1.2.6](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.2.1...v1.2.6) (2025-11-11)
+
+
+### 🧹 Chores
+
+* **release:** 1.2.2 🚀 ([64eb9de](https://github.com/programinglive/dev-workflow-mcp-server/commit/64eb9dea66625ce0b21b5006f455b0d452299997))
+* **release:** 1.2.3 🚀 ([cd113e9](https://github.com/programinglive/dev-workflow-mcp-server/commit/cd113e9a2ca7a8a374f2ec07aa4a25f1c0570051))
+* **release:** 1.2.4 🚀 ([7d39809](https://github.com/programinglive/dev-workflow-mcp-server/commit/7d398091359ee74c69f12e8fa77443615c32d51a))
+* **release:** 1.2.5 🚀 ([e893f26](https://github.com/programinglive/dev-workflow-mcp-server/commit/e893f26a173306f96a40f68bf2c71706cc5fdb77))
+
+
+### 📝 Documentation
+
+* clarify user ID management ([a76381c](https://github.com/programinglive/dev-workflow-mcp-server/commit/a76381c842c1dea5e98116667addc4cbd0d022ed))
+
+### [1.2.5](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.2.1...v1.2.5) (2025-11-11)
+
+
+### 🧹 Chores
+
+* **release:** 1.2.2 🚀 ([64eb9de](https://github.com/programinglive/dev-workflow-mcp-server/commit/64eb9dea66625ce0b21b5006f455b0d452299997))
+* **release:** 1.2.3 🚀 ([cd113e9](https://github.com/programinglive/dev-workflow-mcp-server/commit/cd113e9a2ca7a8a374f2ec07aa4a25f1c0570051))
+* **release:** 1.2.4 🚀 ([7d39809](https://github.com/programinglive/dev-workflow-mcp-server/commit/7d398091359ee74c69f12e8fa77443615c32d51a))
+* **release:** 1.2.5 🚀 ([e893f26](https://github.com/programinglive/dev-workflow-mcp-server/commit/e893f26a173306f96a40f68bf2c71706cc5fdb77))
+
+
+### 📝 Documentation
+
+* clarify user ID management ([a76381c](https://github.com/programinglive/dev-workflow-mcp-server/commit/a76381c842c1dea5e98116667addc4cbd0d022ed))
+
+### [1.2.4](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.2.1...v1.2.4) (2025-11-11)
+
+
+### 🧹 Chores
+
+* **release:** 1.2.2 🚀 ([64eb9de](https://github.com/programinglive/dev-workflow-mcp-server/commit/64eb9dea66625ce0b21b5006f455b0d452299997))
+* **release:** 1.2.3 🚀 ([cd113e9](https://github.com/programinglive/dev-workflow-mcp-server/commit/cd113e9a2ca7a8a374f2ec07aa4a25f1c0570051))
+* **release:** 1.2.4 🚀 ([7d39809](https://github.com/programinglive/dev-workflow-mcp-server/commit/7d398091359ee74c69f12e8fa77443615c32d51a))
+* **release:** 1.2.5 🚀 ([e893f26](https://github.com/programinglive/dev-workflow-mcp-server/commit/e893f26a173306f96a40f68bf2c71706cc5fdb77))
+
+
+### 📝 Documentation
+
+* clarify user ID management ([a76381c](https://github.com/programinglive/dev-workflow-mcp-server/commit/a76381c842c1dea5e98116667addc4cbd0d022ed))
+
+### [1.2.3](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.2.1...v1.2.3) (2025-11-11)
+
+
+### 🧹 Chores
+
+* **release:** 1.2.2 🚀 ([64eb9de](https://github.com/programinglive/dev-workflow-mcp-server/commit/64eb9dea66625ce0b21b5006f455b0d452299997))
+* **release:** 1.2.3 🚀 ([cd113e9](https://github.com/programinglive/dev-workflow-mcp-server/commit/cd113e9a2ca7a8a374f2ec07aa4a25f1c0570051))
+* **release:** 1.2.4 🚀 ([7d39809](https://github.com/programinglive/dev-workflow-mcp-server/commit/7d398091359ee74c69f12e8fa77443615c32d51a))
+* **release:** 1.2.5 🚀 ([e893f26](https://github.com/programinglive/dev-workflow-mcp-server/commit/e893f26a173306f96a40f68bf2c71706cc5fdb77))
+
+
+### 📝 Documentation
+
+* clarify user ID management ([a76381c](https://github.com/programinglive/dev-workflow-mcp-server/commit/a76381c842c1dea5e98116667addc4cbd0d022ed))
+
+### [1.2.2](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.2.1...v1.2.2) (2025-11-11)
+
+
+### 🧹 Chores
+
+* **release:** 1.2.2 🚀 ([64eb9de](https://github.com/programinglive/dev-workflow-mcp-server/commit/64eb9dea66625ce0b21b5006f455b0d452299997))
+* **release:** 1.2.3 🚀 ([cd113e9](https://github.com/programinglive/dev-workflow-mcp-server/commit/cd113e9a2ca7a8a374f2ec07aa4a25f1c0570051))
+* **release:** 1.2.4 🚀 ([7d39809](https://github.com/programinglive/dev-workflow-mcp-server/commit/7d398091359ee74c69f12e8fa77443615c32d51a))
+* **release:** 1.2.5 🚀 ([e893f26](https://github.com/programinglive/dev-workflow-mcp-server/commit/e893f26a173306f96a40f68bf2c71706cc5fdb77))
+
+
+### 📝 Documentation
+
+* clarify user ID management ([a76381c](https://github.com/programinglive/dev-workflow-mcp-server/commit/a76381c842c1dea5e98116667addc4cbd0d022ed))
+
+### [1.2.5](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.2.4...v1.2.5) (2025-11-03)
+
+### [1.2.4](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.2.3...v1.2.4) (2025-11-03)
+
+### [1.2.3](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.2.2...v1.2.3) (2025-11-03)
+
+### [1.2.2](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.2.1...v1.2.2) (2025-11-03)
+
 ### [1.2.1](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.2.0...v1.2.1) (2025-11-03)
 
 ## [1.2.0](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.1.18...v1.2.0) (2025-11-03)

package/README.md

@@ -54,6 +54,8 @@ Plesk supports Node.js applications through its Node.js extension. To deploy the
 
 > **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.
 
+> **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.
+
 #### Two Usage Modes
 
 - **Local (source)**: Point your MCP client to `index.js`. This runs directly from source and requires no build step. Recommended for MCP usage.
@@ -173,7 +175,8 @@ npm run web
 # 🌐 Dev Workflow Dashboard running at http://localhost:3111
 ```
 
-- **Default port:** 3111 (or the next free port if occupied). Override with `DEV_WORKFLOW_WEB_PORT`.
+- **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/summary?user=<id>` → overall stats for the user.
@@ -209,6 +212,28 @@ When you install this package in a project, a `.state/workflow-state.json` file
 
 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`:

package/docs/RELEASE-NOTES.md

@@ -0,0 +1,117 @@
+# Release Notes
+
+Authoritative history of user-visible changes for the Development Workflow MCP Server. Each entry highlights the improvements that shipped with the tagged version.
+
+> **Notice:** Versions 1.2.2 through 1.2.5 were published briefly for packaging experiments and have been withdrawn. The current latest version is **1.2.1**.
+
+## 1.2.1 — 2025-11-03
+- Packaging touch-up; functionality remains identical to 1.2.0.
+
+## 1.2.0 — 2025-11-03
+- Reload the workflow state from disk for every tool call, preventing stale data when multiple clients manipulate the same project.
+
+## 1.1.18 — 2025-11-03
+- `commit_and_push` now auto-detects the primary branch (preferring `main`, then `master`) when none is supplied.
+
+## 1.1.17 — 2025-10-31
+- Release bookkeeping only; no user-facing changes.
+
+## 1.1.16 — 2025-10-31
+- Added npm provenance metadata so published packages include supply-chain attestations.
+
+## 1.1.15 — 2025-10-31
+- Documented the automated npm publish workflow and ensured CI builds include provenance before publishing.
+
+## 1.1.14 — 2025-10-31
+- Improved project-root detection for workflow state, fixing issues when the server runs from nested directories.
+
+## 1.1.13 — 2025-10-30
+- Version bump to distribute refreshed dashboard assets; no new functionality beyond 1.1.12.
+
+## 1.1.12 — 2025-10-30
+- Added a `node index.js call <tool>` CLI helper to invoke MCP tools without a client integration.
+- Refreshed the web dashboard with a docs modal, dedicated docs API endpoints, and streamlined navigation.
+
+## 1.1.11 — 2025-10-30
+- Introduced per-user workflow state stored under `.state/users/<id>/` to avoid collisions on shared repos.
+- Added a SQLite-backed project knowledge summary and the dashboard that visualizes history and trends.
+- Hardened resumable workflows by re-checking persisted summaries between steps.
+
+## 1.1.10 — 2025-10-29
+- Shipped the initial project knowledge library with a persisted JSON summary for future database integrations.
+
+## 1.1.9 — 2025-10-29
+- Made `run_full_workflow` resume intelligently from the current phase.
+- Expanded automated tests around README/exec updates and other workflow paths.
+
+## 1.1.8 — 2025-10-27
+- Documented the `DEV_WORKFLOW_STATE_FILE` override for relocating workflow state outside the repository.
+
+## 1.1.7 — 2025-10-26
+- Added prompts guiding developers to document changes immediately after tests pass.
+
+## 1.1.6 — 2025-10-26
+- Prevented `.state` from being created at filesystem roots.
+- Enforced that commits must land before any release action can run.
+
+## 1.1.5 — 2025-10-25
+- Introduced the release guard, blocking `npm run release:*` until every prerequisite tool has run.
+- Standardized per-project workflow state creation during installs.
+
+## 1.1.4 — 2025-10-25
+- Ensured the install script always targets the project root when initializing `.state`.
+
+## 1.1.3 — 2025-10-25
+- Packaged the MCP server for project-level installs with per-project workflow state isolation.
+
+## 1.1.2 — 2025-10-25
+- Version alignment release with no additional changes versus 1.1.1.
+
+## 1.1.1 — 2025-10-25
+- Added `force_complete_task`, letting teams close tasks early with an audit trail.
+
+## 1.1.0 — 2025-10-25
+- Added smart staging checks before commit, and made `continue_workflow` auto-run the next action in the commit phase.
+- Enabled clean-tree commits to utilize `commit_and_push` and `perform_release` without manual staging.
+- Clarified documentation for the commit/push step.
+
+## 1.0.11 — 2025-10-25
+- Added contextual "continue workflow" guidance describing the next recommended tool.
+- Blocked releases until commits are safely pushed.
+
+## 1.0.10 — 2025-10-24
+- Modularized the workflow server internals for maintainability.
+- Expanded automated tests around the release push flow.
+
+## 1.0.9 — 2025-10-23
+- Documented how local workflow state is managed across projects.
+
+## 1.0.8 — 2025-10-21
+- Added explicit workflows for skipping tests with justification and dropping tasks mid-flight.
+
+## 1.0.7 — 2025-10-20
+- Version alignment update; no new functionality recorded.
+
+## 1.0.6 — 2025-10-20
+- Strengthened release tests to ensure prerequisites are met before tagging.
+
+## 1.0.5 — 2025-10-20
+- Updated tests around `workflowState` persistence and validation.
+
+## 1.0.4 — 2025-10-20
+- Added an enforced release step after the ready check to ensure workflow order.
+- Improved Windows compatibility by quoting commit messages safely.
+
+## 1.0.3 — 2025-10-20
+- Added a project `.gitignore` and clarified cross-platform installation steps.
+
+## 1.0.2 — 2025-10-19
+- Hardened `run_tests` argument validation and normalized tool call arguments.
+- Expanded documentation around tool payload requirements.
+
+## 1.0.1 — 2025-10-18
+- Configured release tooling to support semantic version tagging moving forward.
+
+## 1.0.0 — 2025-10-18
+- Initial public release with the full MCP workflow (start → fix → tests → docs → commit → release → complete).
+- Launched project governance, contribution guidelines, and tooling scaffolding.

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@programinglive/dev-workflow-mcp-server",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "MCP server to enforce development workflow discipline",
+  "homepage": "https://devworkflow.programinglive.com/",
   "type": "module",
   "main": "index.js",
   "bin": {

package/release-wrapper.js

@@ -8,6 +8,7 @@ const RELEASE_TYPES = new Set(['major', 'minor', 'patch']);
 
 async function main() {
   const releaseTypeArg = (process.argv[2] || '').toLowerCase();
+  const forceFlag = process.argv.includes('--force') || process.env.DEV_WORKFLOW_FORCE_RELEASE === '1';
 
   if (!RELEASE_TYPES.has(releaseTypeArg)) {
     console.error(
@@ -76,15 +77,24 @@ async function main() {
     errors.push('A release has already been recorded for this task.');
   }
 
-  if (errors.length) {
+  if (errors.length && !forceFlag) {
     console.error('❌ Release guard blocked the release:');
     for (const message of errors) {
       console.error(`  • ${message}`);
     }
     console.error("\nUse 'perform_release' through the dev-workflow MCP after completing the missing steps.");
+    console.error("Or use: npm run release:patch -- --force (to bypass guard)");
     process.exit(1);
   }
 
+  if (forceFlag && errors.length) {
+    console.warn('⚠️ --force flag detected. Bypassing workflow guard.');
+    console.warn('Errors that were skipped:');
+    for (const message of errors) {
+      console.warn(`  • ${message}`);
+    }
+  }
+
   const runRelease = async () => {
     if (process.env.DEV_WORKFLOW_SKIP_RELEASE === '1') {
       console.log('ℹ️ DEV_WORKFLOW_SKIP_RELEASE=1 detected. Skipping actual release command.');

package/tests/release-wrapper.test.js

@@ -23,6 +23,7 @@ async function runWrapper({ state, args = ["patch"], env = {} }) {
     ...process.env,
     INIT_CWD: dir,
     DEV_WORKFLOW_SKIP_RELEASE: "1",
+    DEV_WORKFLOW_FORCE_RELEASE: undefined,
     ...env,
   };
 

package/web/index.html

@@ -95,6 +95,14 @@
                 Overview
               </h2>
               <p class="mt-2 text-slate-600">Learn how the Dev Workflow dashboard surfaces workflow history and offers inline documentation for every MCP command.</p>
+              <div class="mt-4 bg-amber-50 border border-amber-200 text-amber-800 text-sm rounded-lg p-4 flex gap-3">
+                <i data-lucide="alert-circle" class="mt-1 shrink-0"></i>
+                <p>
+                  The dashboard is read-only. MCP clients (Windsurf, Claude Desktop, etc.) must launch the server via <code>node index.js</code>
+                  over stdio on the machine they control. Hosting this site publicly does <strong>not</strong> expose the MCP protocol; without SSH or another
+                  execution path to the server, remote users cannot connect their MCP agents.
+                </p>
+              </div>
             </div>
             <div class="hidden md:flex items-center gap-2 text-sm text-slate-500">
               <i data-lucide="info"></i>
@@ -278,16 +286,45 @@
 
             <details class="border border-slate-200 rounded-lg">
               <summary class="cursor-pointer select-none px-4 py-3 flex items-center justify-between font-medium">
-                <span><i data-lucide="beaker"></i> create_tests &amp; run_tests</span>
+                <span><i data-lucide="beaker"></i> create_tests</span>
+                <i data-lucide="chevron-down" class="ml-2"></i>
+              </summary>
+              <div class="px-5 pb-5 space-y-3 text-sm text-slate-600">
+                <p>Confirm that coverage exists for the work you just completed.</p>
+                <ul class="list-disc list-inside space-y-1">
+                  <li><strong>Parameters:</strong> None.</li>
+                  <li><strong>When to use:</strong> After <code>mark_bug_fixed</code> once tests are written.</li>
+                  <li><strong>Next step:</strong> Execute <code>run_tests</code> and record the results.</li>
+                </ul>
+              </div>
+            </details>
+
+            <details class="border border-slate-200 rounded-lg">
+              <summary class="cursor-pointer select-none px-4 py-3 flex items-center justify-between font-medium">
+                <span><i data-lucide="ban"></i> skip_tests</span>
                 <i data-lucide="chevron-down" class="ml-2"></i>
               </summary>
               <div class="px-5 pb-5 space-y-3 text-sm text-slate-600">
-                <p>Track your testing workflow from coverage to execution.</p>
+                <p>Document why automated tests are impossible for this task.</p>
                 <ul class="list-disc list-inside space-y-1">
-                  <li><strong>create_tests:</strong> No parameters — confirms tests exist.</li>
-                  <li><strong>run_tests:</strong> <code>passed</code> (boolean), <code>testCommand</code> (string), optional <code>details</code> (string)</li>
-                  <li><strong>Guidance:</strong> Tests must pass before documentation or commits.</li>
-                  <li><strong>Alternate:</strong> Use <code>skip_tests</code> with a detailed justification when automation is impossible.</li>
+                  <li><strong>Parameter:</strong> <code>reason</code> (string, required)</li>
+                  <li><strong>Effect:</strong> Flags the workflow for manual QA review.</li>
+                  <li><strong>Next step:</strong> Continue with <code>create_documentation</code>.</li>
+                </ul>
+              </div>
+            </details>
+
+            <details class="border border-slate-200 rounded-lg">
+              <summary class="cursor-pointer select-none px-4 py-3 flex items-center justify-between font-medium">
+                <span><i data-lucide="test-tube"></i> run_tests</span>
+                <i data-lucide="chevron-down" class="ml-2"></i>
+              </summary>
+              <div class="px-5 pb-5 space-y-3 text-sm text-slate-600">
+                <p>Capture the outcome of your automated test run.</p>
+                <ul class="list-disc list-inside space-y-1">
+                  <li><strong>Parameters:</strong> <code>passed</code> (boolean, required), <code>testCommand</code> (string, required), optional <code>details</code> (string)</li>
+                  <li><strong>Guidance:</strong> Never proceed if tests fail—return to coding and re-run.</li>
+                  <li><strong>Next step:</strong> Move to <code>create_documentation</code> when green.</li>
                 </ul>
               </div>
             </details>
@@ -351,16 +388,158 @@
 
             <details class="border border-slate-200 rounded-lg">
               <summary class="cursor-pointer select-none px-4 py-3 flex items-center justify-between font-medium">
-                <span><i data-lucide="check-square"></i> complete_task &amp; friends</span>
+                <span><i data-lucide="check-square"></i> complete_task</span>
+                <i data-lucide="chevron-down" class="ml-2"></i>
+              </summary>
+              <div class="px-5 pb-5 space-y-3 text-sm text-slate-600">
+                <p>Close the workflow after a successful push and release.</p>
+                <ul class="list-disc list-inside space-y-1">
+                  <li><strong>Parameter:</strong> <code>commitMessage</code> (string, required)</li>
+                  <li><strong>Effect:</strong> Archives the task in history and resets the state.</li>
+                  <li><strong>Next step:</strong> Celebrate or begin the next task with <code>start_task</code>.</li>
+                </ul>
+              </div>
+            </details>
+
+            <details class="border border-slate-200 rounded-lg">
+              <summary class="cursor-pointer select-none px-4 py-3 flex items-center justify-between font-medium">
+                <span><i data-lucide="alert-triangle"></i> force_complete_task</span>
+                <i data-lucide="chevron-down" class="ml-2"></i>
+              </summary>
+              <div class="px-5 pb-5 space-y-3 text-sm text-slate-600">
+                <p>Record an incomplete task as finished with a justification.</p>
+                <ul class="list-disc list-inside space-y-1">
+                  <li><strong>Parameters:</strong> optional <code>commitMessage</code>, optional <code>reason</code> (string)</li>
+                  <li><strong>Use sparingly:</strong> Ideal for emergencies where remaining steps cannot be done.</li>
+                  <li><strong>Next step:</strong> Follow up manually on outstanding work.</li>
+                </ul>
+              </div>
+            </details>
+
+            <details class="border border-slate-200 rounded-lg">
+              <summary class="cursor-pointer select-none px-4 py-3 flex items-center justify-between font-medium">
+                <span><i data-lucide="x-circle"></i> drop_task</span>
+                <i data-lucide="chevron-down" class="ml-2"></i>
+              </summary>
+              <div class="px-5 pb-5 space-y-3 text-sm text-slate-600">
+                <p>Abandon the current effort while keeping the history clean.</p>
+                <ul class="list-disc list-inside space-y-1">
+                  <li><strong>Parameter:</strong> optional <code>reason</code> (string)</li>
+                  <li><strong>When to use:</strong> Pivoting to a new approach or discarding exploratory work.</li>
+                  <li><strong>Next step:</strong> Start a fresh task once direction is clear.</li>
+                </ul>
+              </div>
+            </details>
+
+            <details class="border border-slate-200 rounded-lg">
+              <summary class="cursor-pointer select-none px-4 py-3 flex items-center justify-between font-medium">
+                <span><i data-lucide="info"></i> get_workflow_status</span>
+                <i data-lucide="chevron-down" class="ml-2"></i>
+              </summary>
+              <div class="px-5 pb-5 space-y-3 text-sm text-slate-600">
+                <p>Check the current phase, pending steps, and metadata.</p>
+                <ul class="list-disc list-inside space-y-1">
+                  <li><strong>Parameters:</strong> None.</li>
+                  <li><strong>Use when:</strong> You need a quick reminder of what remains.</li>
+                </ul>
+              </div>
+            </details>
+
+            <details class="border border-slate-200 rounded-lg">
+              <summary class="cursor-pointer select-none px-4 py-3 flex items-center justify-between font-medium">
+                <span><i data-lucide="history"></i> view_history</span>
+                <i data-lucide="chevron-down" class="ml-2"></i>
+              </summary>
+              <div class="px-5 pb-5 space-y-3 text-sm text-slate-600">
+                <p>List recently completed tasks and their outcomes.</p>
+                <ul class="list-disc list-inside space-y-1">
+                  <li><strong>Parameter:</strong> optional <code>limit</code> (number)</li>
+                  <li><strong>Great for:</strong> Standups, retrospectives, or auditing recent work.</li>
+                </ul>
+              </div>
+            </details>
+
+            <details class="border border-slate-200 rounded-lg">
+              <summary class="cursor-pointer select-none px-4 py-3 flex items-center justify-between font-medium">
+                <span><i data-lucide="compass"></i> continue_workflow</span>
+                <i data-lucide="chevron-down" class="ml-2"></i>
+              </summary>
+              <div class="px-5 pb-5 space-y-3 text-sm text-slate-600">
+                <p>Receive coaching on what to do next.</p>
+                <ul class="list-disc list-inside space-y-1">
+                  <li><strong>Parameters:</strong> None.</li>
+                  <li><strong>Behavior:</strong> Runs readiness checks automatically and surfaces blockers.</li>
+                </ul>
+              </div>
+            </details>
+
+            <details class="border border-slate-200 rounded-lg">
+              <summary class="cursor-pointer select-none px-4 py-3 flex items-center justify-between font-medium">
+                <span><i data-lucide="refresh-cw"></i> rerun_workflow</span>
+                <i data-lucide="chevron-down" class="ml-2"></i>
+              </summary>
+              <div class="px-5 pb-5 space-y-3 text-sm text-slate-600">
+                <p>Reset the active task back to the start.</p>
+                <ul class="list-disc list-inside space-y-1">
+                  <li><strong>Parameters:</strong> None.</li>
+                  <li><strong>Use when:</strong> You want to replay the entire process with fresh inputs.</li>
+                </ul>
+              </div>
+            </details>
+
+            <details class="border border-slate-200 rounded-lg">
+              <summary class="cursor-pointer select-none px-4 py-3 flex items-center justify-between font-medium">
+                <span><i data-lucide="workflow"></i> run_full_workflow</span>
+                <i data-lucide="chevron-down" class="ml-2"></i>
+              </summary>
+              <div class="px-5 pb-5 space-y-3 text-sm text-slate-600">
+                <p>Execute every command in sequence when you already know the answers.</p>
+                <ul class="list-disc list-inside space-y-1">
+                  <li><strong>Parameters (required):</strong> <code>summary</code>, <code>testCommand</code>, <code>documentationType</code>, <code>documentationSummary</code>, <code>commitMessage</code>, <code>releaseCommand</code></li>
+                  <li><strong>Optional:</strong> <code>testsPassed</code>, <code>testDetails</code>, <code>branch</code>, <code>releaseNotes</code>, <code>releaseType</code>, <code>preset</code></li>
+                  <li><strong>Ideal for:</strong> Scripted flows or demos where you want the guardrails without manual calls.</li>
+                </ul>
+              </div>
+            </details>
+
+            <details class="border border-slate-200 rounded-lg">
+              <summary class="cursor-pointer select-none px-4 py-3 flex items-center justify-between font-medium">
+                <span><i data-lucide="pie-chart"></i> project_summary</span>
+                <i data-lucide="chevron-down" class="ml-2"></i>
+              </summary>
+              <div class="px-5 pb-5 space-y-3 text-sm text-slate-600">
+                <p>Generate a high-level recap of the project’s workflow health.</p>
+                <ul class="list-disc list-inside space-y-1">
+                  <li><strong>Parameters:</strong> None.</li>
+                  <li><strong>Output:</strong> Aggregated stats compiled from workflow history.</li>
+                </ul>
+              </div>
+            </details>
+
+            <details class="border border-slate-200 rounded-lg">
+              <summary class="cursor-pointer select-none px-4 py-3 flex items-center justify-between font-medium">
+                <span><i data-lucide="database"></i> project_summary_data</span>
+                <i data-lucide="chevron-down" class="ml-2"></i>
+              </summary>
+              <div class="px-5 pb-5 space-y-3 text-sm text-slate-600">
+                <p>Read the persisted JSON knowledge base (project-summary.json).</p>
+                <ul class="list-disc list-inside space-y-1">
+                  <li><strong>Parameters:</strong> None.</li>
+                  <li><strong>Use when:</strong> You need the structured summary file for automation or reporting.</li>
+                </ul>
+              </div>
+            </details>
+
+            <details class="border border-slate-200 rounded-lg">
+              <summary class="cursor-pointer select-none px-4 py-3 flex items-center justify-between font-medium">
+                <span><i data-lucide="database-backup"></i> project_summary_db</span>
                 <i data-lucide="chevron-down" class="ml-2"></i>
               </summary>
               <div class="px-5 pb-5 space-y-3 text-sm text-slate-600">
-                <p>Finalize or reroute the workflow depending on outcomes.</p>
+                <p>Query the SQLite-backed knowledge base for the active user.</p>
                 <ul class="list-disc list-inside space-y-1">
-                  <li><strong>complete_task:</strong> Requires the final <code>commitMessage</code>.</li>
-                  <li><strong>force_complete_task:</strong> Close with justification, recording in history.</li>
-                  <li><strong>drop_task:</strong> Abandon work while capturing a reason.</li>
-                  <li><strong>view_history / continue_workflow:</strong> Read-only helpers for status.</li>
+                  <li><strong>Parameters:</strong> None.</li>
+                  <li><strong>Tip:</strong> Set <code>DEV_WORKFLOW_USER_ID</code> to target another user’s dataset.</li>
                 </ul>
               </div>
             </details>

package/web/server.js

@@ -14,8 +14,20 @@ const allowedDocs = {
   "web-dashboard.md": join(projectRoot, "docs", "web-dashboard.md"),
 };
 
+function getPreferredPort() {
+  const fromEnv = process.env.PORT || process.env.DEV_WORKFLOW_WEB_PORT;
+
+  if (!fromEnv) {
+    return null;
+  }
+
+  const parsed = Number(fromEnv);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+
 async function start() {
-  const PORT = process.env.DEV_WORKFLOW_WEB_PORT || await getPort({ port: 3111 });
+  const preferred = getPreferredPort();
+  const PORT = preferred ?? await getPort({ port: 3111 });
 
   const server = createServer(async (req, res) => {
     try {