pmpt-cli 1.14.21 → 1.17.0

package/README.md

@@ -10,6 +10,8 @@
 
 Plan with 5 questions. Build with AI. Save every version. Share and reproduce.
 
+Every session, every decision, every constraint — accumulated in one file your AI can always read.
+
 [Quick Start](#quick-start) · [Commands](#commands) · [MCP Server](#mcp-server) · [Explore Projects](#explore-projects)
 
 </div>
@@ -65,6 +67,7 @@ pmpt explore
 | | Without pmpt | With pmpt |
 |---|---|---|
 | **Planning** | Stare at blank screen, write vague prompts | Answer 5 guided questions, get structured AI prompt |
+| **Context** | Re-explain the same decisions every AI session | AI reads pmpt.md and knows why things are the way they are |
 | **Tracking** | Lose track of what you built and how | Every version auto-saved with full history |
 | **Sharing** | Share finished code only | Share the entire journey — others can reproduce it |
 
@@ -92,8 +95,13 @@ The generated prompt is **automatically copied to your clipboard**. Just paste i
 
 | Command | Description |
 |---------|-------------|
-| `pmpt init` | Initialize project and start tracking |
+| `pmpt init` | Initialize project — sets up `.pmpt/`, selects AI tool, creates entry points |
 | `pmpt plan` | 5 questions → AI prompt (auto-copied to clipboard) |
+| `pmpt plan --template` | Generate a fillable `answers.json` (Windows/PowerShell friendly) |
+| `pmpt plan --answers-file <f>` | Run plan non-interactively from a JSON file |
+| `pmpt constraint add "<rule>"` | Add an architecture rule to pmpt.md |
+| `pmpt constraint list` | List all constraints |
+| `pmpt constraint remove <n>` | Remove a constraint by index |
 | `pmpt save` | Save current state as a snapshot |
 | `pmpt watch` | Auto-detect file changes and save versions |
 | `pmpt status` | Check project status, tracked files, and quality score |
@@ -213,18 +221,37 @@ All tools accept an optional `projectPath` parameter (defaults to cwd).
 
 ```
 your-project/
+├── CLAUDE.md              # Claude Code entry point → points to .pmpt/index.md
+├── .cursorrules           # Cursor entry point      → points to .pmpt/index.md
+├── AGENTS.md              # Codex entry point       → points to .pmpt/index.md
 └── .pmpt/
+    ├── index.md           # AI context map (entry point for all tools)
     ├── config.json        # Project configuration
-    ├── docs/              # Generated documents
+    ├── docs/
+    │   ├── pmpt.md        # Single source of truth — architecture, constraints,
+    │   │                  #   decisions, lessons, progress, snapshot log
     │   ├── plan.md        # Product plan (features checklist)
-    │   ├── pmpt.md        # Progress tracking & decisions
-    │   └── pmpt.ai.md     # AI-ready prompt (project context & instructions)
+    │   └── pmpt.ai.md     # AI-ready prompt (paste into your AI tool)
     └── .history/          # Auto-saved version history
         ├── v1-2024-02-20/
         ├── v2-2024-02-21/
         └── ...
 ```
 
+### pmpt.md — Single Source of Truth
+
+`pmpt.md` is the living document that your AI reads at the start of every session. It accumulates everything the AI needs to understand your project:
+
+| Section | What to record |
+|---------|---------------|
+| `## Architecture` | High-level structure — update as it evolves |
+| `## Active Work` | What's currently being built (clear when done) |
+| `## Decisions` | WHY, not just WHAT — include what led to each decision |
+| `## Constraints` | Platform/library limitations and workarounds |
+| `## Lessons` | Anti-patterns: what failed → root cause → fix applied |
+
+The more you fill this in, the less you re-explain to AI every session.
+
 ---
 
 ## .pmpt File Format

package/dist/commands/constraint.js

@@ -0,0 +1,92 @@
+import * as p from '@clack/prompts';
+import { resolve } from 'path';
+import { isInitialized } from '../lib/config.js';
+import { readConstraints, addConstraint, removeConstraint } from '../lib/harness.js';
+export async function cmdConstraint(action, options = {}) {
+    const projectPath = resolve(process.cwd());
+    if (!isInitialized(projectPath)) {
+        p.intro('pmpt constraint');
+        p.log.error('Project not initialized. Run `pmpt init` first.');
+        process.exit(1);
+    }
+    if (action === 'list') {
+        const constraints = readConstraints(projectPath);
+        p.intro('pmpt constraint list');
+        if (constraints.length === 0) {
+            p.log.info('No constraints defined yet.');
+            p.log.message(`  pmpt constraint add "<rule>"`);
+        }
+        else {
+            p.log.message('');
+            constraints.forEach((rule, i) => {
+                p.log.message(`  ${i + 1}. ${rule}`);
+            });
+            p.log.message('');
+            p.log.info(`${constraints.length} constraint(s) in .pmpt/docs/constraints.md`);
+        }
+        p.outro('');
+        return;
+    }
+    if (action === 'add') {
+        p.intro('pmpt constraint add');
+        let rule = options.rule;
+        if (!rule) {
+            const input = await p.text({
+                message: 'Enter constraint rule:',
+                placeholder: 'e.g., UI does not import Service directly',
+                validate: (v) => (!v ? 'Rule cannot be empty' : undefined),
+            });
+            if (p.isCancel(input)) {
+                p.cancel('Cancelled');
+                process.exit(0);
+            }
+            rule = input;
+        }
+        const ok = addConstraint(projectPath, rule);
+        if (!ok) {
+            p.log.error('Could not find ## Constraints section in .pmpt/docs/pmpt.md');
+            process.exit(1);
+        }
+        p.log.success(`Added: ${rule}`);
+        p.log.info('File: .pmpt/docs/pmpt.md');
+        p.outro('');
+        return;
+    }
+    if (action === 'remove') {
+        p.intro('pmpt constraint remove');
+        const constraints = readConstraints(projectPath);
+        if (constraints.length === 0) {
+            p.log.warn('No constraints to remove.');
+            p.outro('');
+            return;
+        }
+        let idx;
+        if (options.index) {
+            idx = parseInt(options.index, 10);
+        }
+        else {
+            // Interactive selection
+            const choice = await p.select({
+                message: 'Select constraint to remove:',
+                options: constraints.map((rule, i) => ({
+                    value: String(i + 1),
+                    label: `${i + 1}. ${rule}`,
+                })),
+            });
+            if (p.isCancel(choice)) {
+                p.cancel('Cancelled');
+                process.exit(0);
+            }
+            idx = parseInt(choice, 10);
+        }
+        const removed = removeConstraint(projectPath, idx);
+        if (removed === null) {
+            p.log.error(`No constraint at index ${idx}.`);
+        }
+        else {
+            p.log.success(`Removed: ${removed}`);
+        }
+        p.outro('');
+        return;
+    }
+}

package/dist/commands/doctor.js

@@ -0,0 +1,220 @@
+import * as p from '@clack/prompts';
+import { execSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { detectPmptMcpPath, getWrapperStatus } from './mcp-setup.js';
+function checkNodeVersion() {
+    const version = process.versions.node;
+    const major = parseInt(version.split('.')[0], 10);
+    if (major >= 18) {
+        return { label: 'Node.js', status: 'ok', detail: `v${version}` };
+    }
+    return {
+        label: 'Node.js',
+        status: 'fail',
+        detail: `v${version} (requires ≥18)`,
+        fix: 'Update Node.js: https://nodejs.org',
+    };
+}
+function checkNvm() {
+    const nvmDir = process.env.NVM_DIR || join(homedir(), '.nvm');
+    const isNvm = !!process.env.NVM_DIR || process.argv[1]?.includes('.nvm/');
+    if (!isNvm && !existsSync(nvmDir)) {
+        return { label: 'nvm', status: 'ok', detail: 'Not using nvm (no PATH issues)' };
+    }
+    // Check if default alias is set
+    let defaultAlias = '';
+    try {
+        const aliasFile = join(nvmDir, 'alias', 'default');
+        if (existsSync(aliasFile)) {
+            defaultAlias = readFileSync(aliasFile, 'utf-8').trim();
+        }
+    }
+    catch { /* ignore */ }
+    if (defaultAlias) {
+        return {
+            label: 'nvm',
+            status: 'warn',
+            detail: `Active (default: ${defaultAlias}). MCP clients may not load nvm in non-interactive shells.`,
+            fix: 'Use "pmpt mcp-setup" to create a stable wrapper, or consider volta/fnm.',
+        };
+    }
+    return {
+        label: 'nvm',
+        status: 'warn',
+        detail: 'Active, no default alias set. MCP path may break across sessions.',
+        fix: 'Run "nvm alias default <version>" and "pmpt mcp-setup".',
+    };
+}
+function checkPmptMcpBinary() {
+    const path = detectPmptMcpPath();
+    if (path) {
+        return { label: 'pmpt-mcp binary', status: 'ok', detail: path };
+    }
+    return {
+        label: 'pmpt-mcp binary',
+        status: 'fail',
+        detail: 'Not found in PATH or sibling directory',
+        fix: 'Run "npm install -g pmpt-cli" to install.',
+    };
+}
+function checkWrapper() {
+    const wrapper = getWrapperStatus();
+    if (!wrapper.exists) {
+        const isNvm = !!process.env.NVM_DIR || process.argv[1]?.includes('.nvm/');
+        if (isNvm) {
+            return {
+                label: 'Wrapper script',
+                status: 'warn',
+                detail: 'Not created (recommended for nvm users)',
+                fix: 'Run "pmpt mcp-setup" to create ~/.pmpt/bin/pmpt-mcp wrapper.',
+            };
+        }
+        return { label: 'Wrapper script', status: 'ok', detail: 'Not needed (not using nvm)' };
+    }
+    if (wrapper.targetValid) {
+        return { label: 'Wrapper script', status: 'ok', detail: `OK → ${wrapper.targetPath}` };
+    }
+    return {
+        label: 'Wrapper script',
+        status: 'fail',
+        detail: `Stale — target binary missing: ${wrapper.targetPath}`,
+        fix: 'Run "pmpt mcp-setup" to update the wrapper after Node version change.',
+    };
+}
+function checkMcpClients() {
+    const results = [];
+    // Claude Code
+    try {
+        execSync('which claude', { stdio: ['pipe', 'pipe', 'pipe'] });
+        try {
+            const list = execSync('claude mcp list', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+            if (list.includes('pmpt')) {
+                results.push({ label: 'Claude Code MCP', status: 'ok', detail: 'pmpt registered' });
+            }
+            else {
+                results.push({
+                    label: 'Claude Code MCP',
+                    status: 'warn',
+                    detail: 'Claude Code found but pmpt not registered',
+                    fix: 'Run "pmpt mcp-setup" and select Claude Code.',
+                });
+            }
+        }
+        catch {
+            results.push({
+                label: 'Claude Code MCP',
+                status: 'warn',
+                detail: 'Claude Code found but "claude mcp list" failed',
+                fix: 'Make sure Claude Code is up to date.',
+            });
+        }
+    }
+    catch {
+        // Claude Code not installed — skip
+    }
+    // Cursor
+    const cursorConfig = join(homedir(), '.cursor', 'mcp.json');
+    if (existsSync(join(homedir(), '.cursor'))) {
+        try {
+            if (existsSync(cursorConfig)) {
+                const content = JSON.parse(readFileSync(cursorConfig, 'utf-8'));
+                if (content?.mcpServers?.pmpt) {
+                    const cmd = content.mcpServers.pmpt.command;
+                    if (existsSync(cmd)) {
+                        results.push({ label: 'Cursor MCP', status: 'ok', detail: `pmpt → ${cmd}` });
+                    }
+                    else {
+                        results.push({
+                            label: 'Cursor MCP',
+                            status: 'fail',
+                            detail: `pmpt registered but binary missing: ${cmd}`,
+                            fix: 'Run "pmpt mcp-setup" to update the path.',
+                        });
+                    }
+                }
+                else {
+                    results.push({
+                        label: 'Cursor MCP',
+                        status: 'warn',
+                        detail: 'Cursor found but pmpt not in mcp.json',
+                        fix: 'Run "pmpt mcp-setup" and select Cursor.',
+                    });
+                }
+            }
+        }
+        catch {
+            results.push({ label: 'Cursor MCP', status: 'warn', detail: 'Could not parse ~/.cursor/mcp.json' });
+        }
+    }
+    // Project .mcp.json
+    const projectMcp = join(process.cwd(), '.mcp.json');
+    if (existsSync(projectMcp)) {
+        try {
+            const content = JSON.parse(readFileSync(projectMcp, 'utf-8'));
+            if (content?.mcpServers?.pmpt) {
+                const cmd = content.mcpServers.pmpt.command;
+                if (existsSync(cmd)) {
+                    results.push({ label: '.mcp.json', status: 'ok', detail: `pmpt → ${cmd}` });
+                }
+                else {
+                    results.push({
+                        label: '.mcp.json',
+                        status: 'fail',
+                        detail: `pmpt registered but binary missing: ${cmd}`,
+                        fix: 'Run "pmpt mcp-setup" to update the path.',
+                    });
+                }
+            }
+        }
+        catch {
+            results.push({ label: '.mcp.json', status: 'warn', detail: 'Could not parse .mcp.json' });
+        }
+    }
+    if (results.length === 0) {
+        results.push({
+            label: 'MCP clients',
+            status: 'warn',
+            detail: 'No MCP client configuration found',
+            fix: 'Run "pmpt mcp-setup" to configure an AI tool.',
+        });
+    }
+    return results;
+}
+const icons = { ok: '✓', warn: '⚠', fail: '✗' };
+const colors = { ok: '\x1b[32m', warn: '\x1b[33m', fail: '\x1b[31m' };
+const reset = '\x1b[0m';
+export async function cmdDoctor() {
+    p.intro('pmpt doctor');
+    const s = p.spinner();
+    s.start('Running diagnostics...');
+    const checks = [
+        checkNodeVersion(),
+        checkNvm(),
+        checkPmptMcpBinary(),
+        checkWrapper(),
+        ...checkMcpClients(),
+    ];
+    s.stop('Diagnostics complete');
+    // Display results
+    const lines = [];
+    let hasIssues = false;
+    for (const check of checks) {
+        const icon = icons[check.status];
+        const color = colors[check.status];
+        lines.push(`${color}${icon}${reset} ${check.label}: ${check.detail}`);
+        if (check.fix) {
+            lines.push(`  → ${check.fix}`);
+            hasIssues = true;
+        }
+    }
+    p.note(lines.join('\n'), 'Diagnostic Results');
+    if (hasIssues) {
+        p.log.warn('Some issues found. Run the suggested fixes above.');
+    }
+    else {
+        p.log.success('Everything looks good!');
+    }
+    p.outro('');
+}

package/dist/commands/init.js

@@ -5,8 +5,9 @@ import { initializeProject, isInitialized, getDocsDir, ensurePmptClaudeMd, ensur
 import { isGitRepo, getGitInfo, formatGitInfo, getCommitCount } from '../lib/git.js';
 import { cmdPlan } from './plan.js';
 import { scanProject, scanResultToAnswers } from '../lib/scanner.js';
-import { savePlanDocuments, initPlanProgress, savePlanProgress } from '../lib/plan.js';
+import { savePlanDocuments, initPlanProgress, savePlanProgress, generateAnswersTemplate } from '../lib/plan.js';
 import { copyToClipboard } from '../lib/clipboard.js';
+import { setupHarnessForTools } from '../lib/harness.js';
 export async function cmdInit(path, options) {
     p.intro('pmpt init');
     const projectPath = path ? resolve(path) : process.cwd();
@@ -100,14 +101,34 @@ export async function cmdInit(path, options) {
         // Add pmpt MCP instructions to CLAUDE.md and register .mcp.json for Claude Code
         ensurePmptClaudeMd(projectPath);
         ensureMcpJson(projectPath);
+        // Ask which AI tool to set up harness for
+        const toolChoice = await p.select({
+            message: 'Which AI coding tool do you use?',
+            options: [
+                { value: 'claude', label: 'Claude Code', hint: 'CLAUDE.md + .pmpt/index.md' },
+                { value: 'cursor', label: 'Cursor', hint: '.cursorrules + .pmpt/index.md' },
+                { value: 'codex', label: 'Codex', hint: 'AGENTS.md + .pmpt/index.md' },
+                { value: 'all', label: 'All of the above', hint: 'Create all entry points' },
+                { value: 'skip', label: 'Skip', hint: 'Set up later with `pmpt harness`' },
+            ],
+        });
+        if (p.isCancel(toolChoice)) {
+            p.cancel('Cancelled');
+            process.exit(0);
+        }
+        if (toolChoice !== 'skip') {
+            setupHarnessForTools(projectPath, basename(projectPath), toolChoice);
+        }
         // Build folder structure display
         const notes = [
             `Path: ${config.projectPath}`,
             '',
             'Folder structure:',
             `  .pmpt/`,
+            `  ├── index.md        AI entry point`,
             `  ├── config.json     Config`,
-            `  ├── docs/           Your docs`,
+            `  ├── docs/`,
+            `  │   └── pmpt.md     Source of truth (architecture, constraints, decisions)`,
             `  └── .history/       Snapshots`,
         ];
         if (config.repo) {
@@ -155,6 +176,7 @@ export async function cmdInit(path, options) {
                 options: [
                     { value: 'auto', label: 'Auto-generate plan', hint: 'Recommended — instant AI prompt from project analysis' },
                     { value: 'manual', label: 'Manual planning', hint: '5 questions interactive flow' },
+                    { value: 'file', label: 'Fill in answers file', hint: 'Windows/PowerShell friendly — edit a JSON file then run pmpt plan --answers-file' },
                     { value: 'skip', label: 'Skip for now' },
                 ],
             });
@@ -162,6 +184,17 @@ export async function cmdInit(path, options) {
                 p.cancel('Cancelled');
                 process.exit(0);
             }
+            if (scanChoice === 'file') {
+                const outFile = 'answers.json';
+                const template = generateAnswersTemplate();
+                writeFileSync(resolve(projectPath, outFile), JSON.stringify(template, null, 2), 'utf-8');
+                p.log.success(`Template created: ${outFile}`);
+                p.log.info('Next steps:');
+                p.log.message(`  1. Open and fill in ${outFile}`);
+                p.log.message(`  2. pmpt plan --answers-file ${outFile}`);
+                p.outro('Ready!');
+                return;
+            }
             if (scanChoice === 'auto') {
                 // Ask for project description
                 const defaultDesc = scanResult.readmeDescription
@@ -236,23 +269,41 @@ export async function cmdInit(path, options) {
             }
             else {
                 ensureMinimalDocs(projectPath);
+                p.log.info('Tip: On Windows/PowerShell, use a template file to avoid paste issues:');
+                p.log.message('  pmpt plan --template   # creates answers.json');
+                p.log.message('  pmpt plan --answers-file answers.json');
                 p.outro('Ready! Run `pmpt plan` when you want to start.');
             }
         }
         else {
             // New/empty project — original flow
-            const startPlan = await p.confirm({
-                message: 'Start planning? (Generate AI prompt with 5 quick questions)',
-                initialValue: true,
+            const startPlan = await p.select({
+                message: 'Start planning?',
+                options: [
+                    { value: 'yes', label: 'Yes — answer 5 questions now', hint: 'Interactive flow' },
+                    { value: 'file', label: 'Fill in answers file', hint: 'Windows/PowerShell friendly — edit a JSON file then run pmpt plan --answers-file' },
+                    { value: 'no', label: 'Skip for now' },
+                ],
             });
-            if (!p.isCancel(startPlan) && startPlan) {
-                p.log.message('');
-                await cmdPlan(projectPath);
-            }
-            else {
+            if (p.isCancel(startPlan) || startPlan === 'no') {
                 ensureMinimalDocs(projectPath);
                 p.outro('Ready! Run `pmpt plan` when you want to start.');
             }
+            else if (startPlan === 'file') {
+                const outFile = 'answers.json';
+                const template = generateAnswersTemplate();
+                writeFileSync(resolve(projectPath, outFile), JSON.stringify(template, null, 2), 'utf-8');
+                ensureMinimalDocs(projectPath);
+                p.log.success(`Template created: ${outFile}`);
+                p.log.info('Next steps:');
+                p.log.message(`  1. Open and fill in ${outFile}`);
+                p.log.message(`  2. pmpt plan --answers-file ${outFile}`);
+                p.outro('Ready!');
+            }
+            else {
+                p.log.message('');
+                await cmdPlan(projectPath);
+            }
         }
     }
     catch (error) {
@@ -271,16 +322,25 @@ function ensureMinimalDocs(projectPath) {
     const skeleton = [
         `# ${name}`,
         '',
+        '## Architecture',
+        '<!-- High-level structure. Update as it evolves. -->',
+        '',
+        '## Active Work',
+        '<!-- What\'s currently being built. Clear when done, move to Snapshot Log. -->',
+        '',
         '## Progress',
         '- Project initialized',
         '',
         '## Snapshot Log',
         '',
         '## Decisions',
+        '<!-- WHY, not just WHAT. Format: - [Decision] → [Reason] -->',
         '',
         '## Constraints',
+        '<!-- Platform/library limitations. Format: - [Tool]: limitation → workaround -->',
         '',
         '## Lessons',
+        '<!-- Anti-patterns. Format: - [What failed] → [Root cause] → [Fix applied] -->',
         '',
     ].join('\n');
     writeFileSync(pmptMdPath, skeleton, 'utf-8');

package/dist/commands/mcp-setup.js

@@ -1,9 +1,12 @@
 import * as p from '@clack/prompts';
 import { execSync } from 'child_process';
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from 'fs';
 import { join, dirname } from 'path';
 import { homedir } from 'os';
-function detectPmptMcpPath() {
+/** Stable wrapper path that survives nvm version switches */
+const WRAPPER_DIR = join(homedir(), '.pmpt', 'bin');
+const WRAPPER_PATH = join(WRAPPER_DIR, 'pmpt-mcp');
+export function detectPmptMcpPath() {
     // Strategy 1: sibling to the current pmpt binary (same bin directory)
     const pmptBin = process.argv[1];
     const siblingPath = join(dirname(pmptBin), 'pmpt-mcp');
@@ -24,6 +27,51 @@ function detectPmptMcpPath() {
     }
     return null;
 }
+/** Detect if nvm is in use */
+function isNvmEnvironment() {
+    return !!process.env.NVM_DIR || process.argv[1]?.includes('.nvm/');
+}
+/**
+ * Create a wrapper script at ~/.pmpt/bin/pmpt-mcp that:
+ * 1. Loads nvm if available
+ * 2. Executes the real pmpt-mcp binary
+ * This makes the MCP path stable across Node version changes.
+ */
+function createWrapperScript(realBinaryPath) {
+    mkdirSync(WRAPPER_DIR, { recursive: true });
+    const nvmDir = process.env.NVM_DIR || join(homedir(), '.nvm');
+    const script = `#!/bin/bash
+# pmpt-mcp wrapper — loads nvm then runs the real binary
+# Auto-generated by pmpt mcp-setup. Re-run "pmpt mcp-setup" to update.
+
+export NVM_DIR="${nvmDir}"
+[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+
+exec "${realBinaryPath}" "$@"
+`;
+    writeFileSync(WRAPPER_PATH, script, { mode: 0o755 });
+    chmodSync(WRAPPER_PATH, 0o755);
+    return WRAPPER_PATH;
+}
+/** Check if wrapper exists and the target binary it points to is still valid */
+export function getWrapperStatus() {
+    if (!existsSync(WRAPPER_PATH)) {
+        return { exists: false, targetValid: false, targetPath: null };
+    }
+    try {
+        const content = readFileSync(WRAPPER_PATH, 'utf-8');
+        const match = content.match(/exec "(.+?)"/);
+        const targetPath = match?.[1] || null;
+        return {
+            exists: true,
+            targetValid: targetPath ? existsSync(targetPath) : false,
+            targetPath,
+        };
+    }
+    catch {
+        return { exists: true, targetValid: false, targetPath: null };
+    }
+}
 function isCommandAvailable(cmd) {
     try {
         const which = process.platform === 'win32' ? 'where' : 'which';
@@ -55,14 +103,15 @@ function isJsonConfigured(configPath) {
     }
 }
 function configureClaudeCode(mcpBinaryPath) {
-    // Remove existing entry first (ignore errors if not found)
-    try {
-        execSync('claude mcp remove pmpt', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
-    }
-    catch {
-        // not configured yet — that's fine
+    // Remove existing entry at any scope first (ignore errors if not found)
+    for (const scope of ['user', 'local', 'project']) {
+        try {
+            execSync(`claude mcp remove --scope ${scope} pmpt`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+        }
+        catch { /* not configured at this scope */ }
     }
-    execSync(`claude mcp add --transport stdio pmpt -- "${mcpBinaryPath}"`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+    // Register at user scope so it works across all projects
+    execSync(`claude mcp add --scope user --transport stdio pmpt -- "${mcpBinaryPath}"`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
 }
 function configureJsonFile(configPath, mcpBinaryPath) {
     let config = {};
@@ -93,6 +142,21 @@ export async function cmdMcpSetup() {
     let mcpPath = detectPmptMcpPath();
     if (mcpPath) {
         s.stop(`Found: ${mcpPath}`);
+        // If nvm environment, offer to create a stable wrapper
+        if (isNvmEnvironment()) {
+            p.log.warn('nvm detected — the binary path may break when you switch Node versions.');
+            const useWrapper = await p.confirm({
+                message: 'Create a stable wrapper at ~/.pmpt/bin/pmpt-mcp? (recommended for nvm users)',
+                initialValue: true,
+            });
+            if (!p.isCancel(useWrapper) && useWrapper) {
+                const wrapperPath = createWrapperScript(mcpPath);
+                p.log.success(`Wrapper created: ${wrapperPath}`);
+                p.log.info(`Points to: ${mcpPath}`);
+                p.log.info('After switching Node versions, run "pmpt mcp-setup" to update the wrapper.');
+                mcpPath = wrapperPath;
+            }
+        }
     }
     else {
         s.stop('Could not auto-detect pmpt-mcp path');

package/dist/commands/plan.js

@@ -1,10 +1,10 @@
 import * as p from '@clack/prompts';
 import { resolve } from 'path';
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { isInitialized, loadConfig } from '../lib/config.js';
 import { copyToClipboard } from '../lib/clipboard.js';
 import { cmdWatch } from './watch.js';
-import { PLAN_QUESTIONS, getPlanProgress, initPlanProgress, savePlanProgress, savePlanDocuments, } from '../lib/plan.js';
+import { PLAN_QUESTIONS, getPlanProgress, initPlanProgress, savePlanProgress, savePlanDocuments, generateAnswersTemplate, } from '../lib/plan.js';
 function loadAnswersFromFile(projectPath, inputPath) {
     const filePath = resolve(projectPath, inputPath);
     if (!existsSync(filePath)) {
@@ -27,6 +27,16 @@ function loadAnswersFromFile(projectPath, inputPath) {
 }
 export async function cmdPlan(path, options) {
     const projectPath = path ? resolve(path) : process.cwd();
+    // Template generation (no init check needed)
+    if (options?.template) {
+        const outFile = resolve(projectPath, options.template);
+        const template = generateAnswersTemplate();
+        writeFileSync(outFile, JSON.stringify(template, null, 2), 'utf-8');
+        p.log.success(`Template created: ${outFile}`);
+        p.log.info('Fill in the fields and run:');
+        p.log.message(`  pmpt plan --answers-file ${options.template}`);
+        return;
+    }
     // Check initialization
     if (!isInitialized(projectPath)) {
         p.intro('pmpt plan');

package/dist/index.js

@@ -45,6 +45,8 @@ import { cmdRecover } from './commands/recover.js';
 import { cmdDiff } from './commands/diff.js';
 import { cmdInternalSeed } from './commands/internal-seed.js';
 import { cmdMcpSetup } from './commands/mcp-setup.js';
+import { cmdDoctor } from './commands/doctor.js';
+import { cmdConstraint } from './commands/constraint.js';
 import { trackCommand } from './lib/api.js';
 import { checkForUpdates } from './lib/update-check.js';
 import { createRequire } from 'module';
@@ -85,6 +87,7 @@ Examples:
   $ pmpt graduate                Graduate a project (Hall of Fame)
   $ pmpt recover                 Recover damaged pmpt.md via AI
   $ pmpt mcp-setup                Configure MCP for AI tools
+  $ pmpt doctor (doc)            Diagnose MCP & environment issues
   $ pmpt feedback (fb)           Share ideas or report bugs
 
 Workflow:
@@ -146,7 +149,28 @@ program
     .description('Quick product planning with 5 questions — auto-generate AI prompt')
     .option('--reset', 'Restart plan from scratch')
     .option('--answers-file <file>', 'Load plan answers from JSON file (non-interactive)')
-    .action(cmdPlan);
+    .option('--template [file]', 'Generate a fillable answers template (default: answers.json)')
+    .action((path, options) => cmdPlan(path, {
+    ...options,
+    template: options.template === true ? 'answers.json' : options.template,
+}));
+program
+    .command('constraint <action>')
+    .description('Manage architecture constraints — add, list, or remove rules')
+    .option('-r, --rule <rule>', 'Rule text (for add)')
+    .option('-i, --index <n>', 'Rule index (for remove)')
+    .addHelpText('after', `
+  Actions:
+    add     Add a constraint rule
+    list    List all constraints
+    remove  Remove a constraint by index
+
+  Examples:
+    pmpt constraint add "UI does not import Service directly"
+    pmpt constraint list
+    pmpt constraint remove 2
+  `)
+    .action((action, options) => cmdConstraint(action, options));
 program
     .command('logout')
     .description('Clear saved GitHub authentication')
@@ -214,6 +238,11 @@ program
     .command('mcp-setup')
     .description('Configure pmpt MCP server for AI tools (Claude Code, Cursor, etc.)')
     .action(cmdMcpSetup);
+program
+    .command('doctor')
+    .alias('doc')
+    .description('Diagnose MCP connection, PATH issues, and environment health')
+    .action(cmdDoctor);
 program
     .command('feedback')
     .alias('fb')

package/dist/lib/harness.js

@@ -0,0 +1,179 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { getConfigDir, getDocsDir } from './config.js';
+// ─── index.md — lightweight map pointing to pmpt.md ───────────────
+export function generateIndexMd(projectName) {
+    return `# ${projectName} — Project Context
+
+> AI entry point. Read this first, then follow the links below.
+
+## Map
+
+| File | Purpose |
+|------|---------|
+| [.pmpt/docs/pmpt.md](.pmpt/docs/pmpt.md) | **Source of truth** — architecture, constraints, decisions, progress |
+| [.pmpt/docs/pmpt.ai.md](.pmpt/docs/pmpt.ai.md) | Full AI prompt — paste into your AI tool to get started |
+
+## Rules for AI
+
+1. Read \`.pmpt/docs/pmpt.md\` before making any code changes
+2. Follow every rule listed in the **## Constraints** section of pmpt.md
+3. After milestones, call \`mcp__pmpt__pmpt_save\` (or \`pmpt save\` in terminal)
+4. Update pmpt.md when architecture, constraints, or features change
+`;
+}
+// ─── Tool-specific entry points ────────────────────────────────────
+export function generateCursorRules() {
+    return `# Project Rules
+
+See \`.pmpt/index.md\` for the project context map.
+
+The single source of truth is \`.pmpt/docs/pmpt.md\`.
+Always check the **## Constraints** section before making code changes.
+After completing milestones, run \`pmpt save\` in terminal.
+`;
+}
+export function generateAgentsMd(projectName) {
+    return `# ${projectName} — Agent Instructions
+
+See \`.pmpt/index.md\` for the project context map.
+
+The single source of truth is \`.pmpt/docs/pmpt.md\`.
+Always check the **## Constraints** section before making code changes.
+After completing milestones, run \`pmpt save\` in terminal.
+`;
+}
+// ─── Setup functions ───────────────────────────────────────────────
+export function ensureIndexMd(projectPath, projectName) {
+    const configDir = getConfigDir(projectPath);
+    mkdirSync(configDir, { recursive: true });
+    const indexPath = join(configDir, 'index.md');
+    if (!existsSync(indexPath)) {
+        writeFileSync(indexPath, generateIndexMd(projectName), 'utf-8');
+    }
+}
+export function ensureCursorRules(projectPath) {
+    const path = join(projectPath, '.cursorrules');
+    if (!existsSync(path)) {
+        writeFileSync(path, generateCursorRules(), 'utf-8');
+    }
+}
+export function ensureAgentsMd(projectPath, projectName) {
+    const path = join(projectPath, 'AGENTS.md');
+    if (!existsSync(path)) {
+        writeFileSync(path, generateAgentsMd(projectName), 'utf-8');
+    }
+}
+export function setupHarnessForTools(projectPath, projectName, tools) {
+    // index.md is always created — it's the lightweight map
+    ensureIndexMd(projectPath, projectName);
+    if (tools === 'cursor' || tools === 'all') {
+        ensureCursorRules(projectPath);
+    }
+    if (tools === 'codex' || tools === 'all') {
+        ensureAgentsMd(projectPath, projectName);
+    }
+    if (tools === 'claude' || tools === 'all') {
+        ensureClaudeMdIndexRef(projectPath);
+    }
+}
+function ensureClaudeMdIndexRef(projectPath) {
+    const claudeMdPath = join(projectPath, 'CLAUDE.md');
+    const marker = '<!-- pmpt-index -->';
+    const section = `${marker}\nSee \`.pmpt/index.md\` for project context. Single source of truth: \`.pmpt/docs/pmpt.md\`.\n<!-- /pmpt-index -->`;
+    if (!existsSync(claudeMdPath))
+        return;
+    const content = readFileSync(claudeMdPath, 'utf-8');
+    if (content.includes(marker))
+        return;
+    const pmptMarker = '<!-- pmpt -->';
+    if (content.includes(pmptMarker)) {
+        writeFileSync(claudeMdPath, content.replace(pmptMarker, section + '\n\n' + pmptMarker), 'utf-8');
+    }
+    else {
+        writeFileSync(claudeMdPath, section + '\n\n' + content, 'utf-8');
+    }
+}
+// ─── Constraint management — reads/writes pmpt.md ## Constraints ──
+export function readConstraints(projectPath) {
+    const pmptMdPath = join(getDocsDir(projectPath), 'pmpt.md');
+    if (!existsSync(pmptMdPath))
+        return [];
+    const lines = readFileSync(pmptMdPath, 'utf-8').split('\n');
+    const inSection = { value: false };
+    const rules = [];
+    for (const line of lines) {
+        if (line.trim() === '## Constraints') {
+            inSection.value = true;
+            continue;
+        }
+        if (inSection.value && line.startsWith('## '))
+            break;
+        if (inSection.value && line.trimStart().startsWith('- ') && !line.includes('<!--')) {
+            rules.push(line.trimStart().slice(2).trim());
+        }
+    }
+    return rules;
+}
+export function addConstraint(projectPath, rule) {
+    const pmptMdPath = join(getDocsDir(projectPath), 'pmpt.md');
+    if (!existsSync(pmptMdPath))
+        return false;
+    const lines = readFileSync(pmptMdPath, 'utf-8').split('\n');
+    let sectionEnd = -1;
+    let inSection = false;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim() === '## Constraints') {
+            inSection = true;
+            continue;
+        }
+        if (inSection && lines[i].startsWith('## ')) {
+            sectionEnd = i;
+            break;
+        }
+    }
+    const newLine = `- ${rule}`;
+    if (sectionEnd !== -1) {
+        // Insert before next section, after any existing content
+        lines.splice(sectionEnd, 0, newLine);
+    }
+    else if (inSection) {
+        lines.push(newLine);
+    }
+    else {
+        return false;
+    }
+    writeFileSync(pmptMdPath, lines.join('\n'), 'utf-8');
+    return true;
+}
+export function removeConstraint(projectPath, index) {
+    const pmptMdPath = join(getDocsDir(projectPath), 'pmpt.md');
+    if (!existsSync(pmptMdPath))
+        return null;
+    const lines = readFileSync(pmptMdPath, 'utf-8').split('\n');
+    let inSection = false;
+    let ruleCount = 0;
+    let removedRule = null;
+    const newLines = lines.filter((line) => {
+        if (line.trim() === '## Constraints') {
+            inSection = true;
+            return true;
+        }
+        if (inSection && line.startsWith('## ')) {
+            inSection = false;
+            return true;
+        }
+        if (inSection && line.trimStart().startsWith('- ') && !line.includes('<!--')) {
+            ruleCount++;
+            if (ruleCount === index) {
+                removedRule = line.trimStart().slice(2).trim();
+                return false;
+            }
+        }
+        return true;
+    });
+    if (removedRule === null)
+        return null;
+    writeFileSync(pmptMdPath, newLines.join('\n'), 'utf-8');
+    return removedRule;
+}

package/dist/lib/plan.js

@@ -118,17 +118,27 @@ After completing each feature above:
 
 ### What to Record in pmpt.md
 
-**## Decisions** — Record WHY, not just WHAT. Include the data or observation that led to the decision.
-- Bad: "Set minimum description length to 150 chars"
-- Good: "Set minimum description length to 150 chars (50-char threshold caused 60% low-quality entries)"
+pmpt.md is the **single source of truth** for this project. AI tools read it to understand context before every session. Keep it accurate.
 
-**## Constraints** — Record platform/library limitations discovered during development.
-- Examples: DB quirks, API limits, framework restrictions, version incompatibilities
-- Format: \`- [Platform]: what doesn't work → workaround used\`
+**## Architecture** — High-level structure. Update when the architecture changes.
+- Example: \`Next.js (SSG) → Cloudflare Workers API → D1 database\`
+- Include the WHY if the stack choice was non-obvious
 
-**## Lessons** — Record anti-patterns and "we tried X, it broke because Y" discoveries.
-- Examples: wrong deletion order causing FK errors, caching issues, race conditions
+**## Active Work** — What's currently being built. One or two items max.
+- Clear this section when done, then move to Snapshot Log
+- Example: \`- Implementing user auth (started 2025-03-17)\`
+
+**## Decisions** — Record WHY, not just WHAT. Include what led to the decision.
+- Bad: "Switched to SQLite"
+- Good: "Switched SQLite → Postgres: deploy target moved to serverless, needed connection pooling"
+
+**## Constraints** — Platform or library limitations discovered during development.
+- Format: \`- [Platform/Tool]: what doesn't work → workaround used\`
+- Example: \`- Cloudflare Workers: no native fs access → use KV for file storage\`
+
+**## Lessons** — Anti-patterns and "tried X, broke because Y" discoveries.
 - Format: \`- [What failed] → [Root cause] → [Fix applied]\`
+- Example: \`- JWT refresh on mobile broke → tokens expired before retry → added sliding expiry\`
 `;
 }
 // Generate human-facing project document (pmpt.md)
@@ -153,24 +163,38 @@ ${contextSection}
 ## Features
 ${features}
 ${techSection}
+## Architecture
+<!-- High-level structure. Update as it evolves. -->
+<!-- Example: "Next.js frontend → Express API → PostgreSQL" -->
+
+## Active Work
+<!-- What's currently being built. Clear when done, move to Snapshot Log. -->
+
 ## Progress
 - [ ] Project setup
 - [ ] Core features implementation
 - [ ] Testing & polish
 
 ## Snapshot Log
-### v1 - Initial Setup
+### v1 — Initial Setup
 - Project initialized with pmpt
 
 ## Decisions
+<!-- WHY, not just WHAT. Include what led to the decision. -->
+<!-- Format: - [Decision] → [Reason / data that led to it] -->
 
 ## Constraints
+<!-- Platform or library limitations discovered during development. -->
+<!-- Format: - [Platform/Tool]: what doesn't work → workaround used -->
 
 ## Lessons
+<!-- Anti-patterns and "tried X, broke because Y" discoveries. -->
+<!-- Format: - [What failed] → [Root cause] → [Fix applied] -->
 
 ---
-*This document tracks your project progress. Update it as you build.*
-*AI instructions are in \`pmpt.ai.md\` — paste that into your AI tool.*
+*This document is the single source of truth for this project.*
+*AI tools read this to understand context, constraints, and current state.*
+*AI instructions are in \`pmpt.ai.md\` — paste that into your AI tool to get started.*
 `;
 }
 // Generate plan document
@@ -200,6 +224,19 @@ ${techSection}
 *Generated by pmpt plan*
 `;
 }
+export function generateAnswersTemplate() {
+    const questions = {};
+    const fields = {};
+    for (const q of PLAN_QUESTIONS) {
+        questions[q.key] = `[${PLAN_QUESTIONS.indexOf(q) + 1}/${PLAN_QUESTIONS.length}] ${q.question}`;
+        fields[q.key] = '';
+    }
+    return {
+        _help: 'Fill in the fields below, then run: pmpt plan --answers-file <this-file>',
+        _questions: questions,
+        ...fields,
+    };
+}
 export function getPlanProgress(projectPath) {
     const planPath = join(getConfigDir(projectPath), PLAN_FILE);
     if (!existsSync(planPath))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmpt-cli",
-  "version": "1.14.21",
+  "version": "1.17.0",
   "description": "Record and share your AI-driven product development journey",
   "type": "module",
   "bin": {