pmpt-cli 1.12.4 → 1.14.0

package/README.md

@@ -130,6 +130,22 @@ pmpt includes a built-in [MCP](https://modelcontextprotocol.io) server so AI too
 
 ### Setup
 
+`pmpt-mcp` is included when you install pmpt — no separate installation needed.
+
+```bash
+npm install -g pmpt   # pmpt + pmpt-mcp both installed
+```
+
+#### Automatic Setup (Recommended)
+
+```bash
+pmpt mcp-setup
+```
+
+Auto-detects the `pmpt-mcp` binary path, lets you choose your AI tool (Claude Code, Cursor, or `.mcp.json`), and writes the config. Solves PATH issues common with nvm.
+
+#### Manual Setup
+
 Add to your `.mcp.json` (or IDE MCP config):
 
 ```json
@@ -142,6 +158,8 @@ Add to your `.mcp.json` (or IDE MCP config):
 }
 ```
 
+> **nvm users**: If your AI tool can't find `pmpt-mcp`, use `pmpt mcp-setup` or replace `"pmpt-mcp"` with the absolute path (run `which pmpt-mcp` to find it).
+
 ### Available Tools
 
 | Tool | Description |

package/dist/commands/graduate.js

@@ -0,0 +1,82 @@
+import * as p from '@clack/prompts';
+import { loadAuth } from '../lib/auth.js';
+import { fetchProjects, graduateProject } from '../lib/api.js';
+export async function cmdGraduate() {
+    const auth = loadAuth();
+    if (!auth?.token || !auth?.username) {
+        p.log.error('Login required. Run `pmpt login` first.');
+        process.exit(1);
+    }
+    p.intro('pmpt graduate');
+    const s = p.spinner();
+    s.start('Loading your projects...');
+    let myProjects;
+    try {
+        const index = await fetchProjects();
+        myProjects = index.projects
+            .filter((proj) => proj.author === auth.username)
+            .filter((proj) => !proj.graduated);
+    }
+    catch (err) {
+        s.stop('Failed to load projects');
+        p.log.error(err instanceof Error ? err.message : 'Failed to fetch projects.');
+        process.exit(1);
+    }
+    s.stop('Projects loaded');
+    if (myProjects.length === 0) {
+        p.log.warn('No eligible projects found. All projects may already be graduated.');
+        p.outro('');
+        return;
+    }
+    const slug = await p.select({
+        message: 'Select a project to graduate:',
+        options: myProjects.map((proj) => ({
+            value: proj.slug,
+            label: proj.slug,
+            hint: proj.description?.slice(0, 50) || '',
+        })),
+    });
+    if (p.isCancel(slug)) {
+        p.cancel('Cancelled');
+        process.exit(0);
+    }
+    p.note([
+        'Graduating a project means:',
+        '  - The project is archived (no more updates)',
+        '  - A graduation badge (🎓) is displayed',
+        '  - It appears in the Hall of Fame',
+        '  - The .pmpt file remains downloadable',
+        '',
+        'This action is intentionally hard to reverse.',
+    ].join('\n'), 'What is graduation?');
+    const confirm = await p.confirm({
+        message: `Graduate "${slug}"? This will archive the project permanently.`,
+        initialValue: false,
+    });
+    if (p.isCancel(confirm) || !confirm) {
+        p.cancel('Cancelled');
+        process.exit(0);
+    }
+    const note = await p.text({
+        message: 'Graduation note (optional):',
+        placeholder: 'e.g., "Reached 1000 users!" or "Acquired by company"',
+    });
+    if (p.isCancel(note)) {
+        p.cancel('Cancelled');
+        process.exit(0);
+    }
+    const s2 = p.spinner();
+    s2.start('Graduating...');
+    try {
+        await graduateProject(auth.token, slug, note || undefined);
+        s2.stop('Graduated!');
+        p.log.success(`Project "${slug}" has graduated! 🎓`);
+        p.log.info('View in Hall of Fame: https://pmptwiki.com/hall-of-fame');
+    }
+    catch (err) {
+        s2.stop('Graduation failed');
+        p.log.error(err instanceof Error ? err.message : 'Failed to graduate project.');
+        process.exit(1);
+    }
+    p.outro('');
+}

package/dist/commands/import.js

@@ -1,59 +1,9 @@
 import * as p from '@clack/prompts';
-import { resolve, join, dirname, sep } from 'path';
-import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, rmSync } from 'fs';
+import { resolve, join } from 'path';
+import { existsSync, readFileSync, writeFileSync, readdirSync, rmSync } from 'fs';
 import { isInitialized, getConfigDir, getHistoryDir, getDocsDir, initializeProject } from '../lib/config.js';
-import { validatePmptFile, isSafeFilename } from '../lib/pmptFile.js';
-/**
- * Restore history from .pmpt file
- */
-function restoreHistory(historyDir, history) {
-    mkdirSync(historyDir, { recursive: true });
-    for (const version of history) {
-        const timestamp = version.timestamp.replace(/[:.]/g, '-').slice(0, 19);
-        const snapshotName = `v${version.version}-${timestamp}`;
-        const snapshotDir = join(historyDir, snapshotName);
-        mkdirSync(snapshotDir, { recursive: true });
-        // Write files (with path traversal protection)
-        for (const [filename, content] of Object.entries(version.files)) {
-            if (!isSafeFilename(filename))
-                continue;
-            const filePath = join(snapshotDir, filename);
-            if (!resolve(filePath).startsWith(resolve(snapshotDir) + sep))
-                continue;
-            const fileDir = dirname(filePath);
-            if (fileDir !== snapshotDir) {
-                mkdirSync(fileDir, { recursive: true });
-            }
-            writeFileSync(filePath, content, 'utf-8');
-        }
-        // Write metadata
-        const metaPath = join(snapshotDir, '.meta.json');
-        writeFileSync(metaPath, JSON.stringify({
-            version: version.version,
-            timestamp: version.timestamp,
-            files: Object.keys(version.files),
-            git: version.git,
-        }, null, 2), 'utf-8');
-    }
-}
-/**
- * Restore docs from .pmpt file
- */
-function restoreDocs(docsDir, docs) {
-    mkdirSync(docsDir, { recursive: true });
-    for (const [filename, content] of Object.entries(docs)) {
-        if (!isSafeFilename(filename))
-            continue;
-        const filePath = join(docsDir, filename);
-        if (!resolve(filePath).startsWith(resolve(docsDir) + sep))
-            continue;
-        const fileDir = dirname(filePath);
-        if (fileDir !== docsDir) {
-            mkdirSync(fileDir, { recursive: true });
-        }
-        writeFileSync(filePath, content, 'utf-8');
-    }
-}
+import { validatePmptFile } from '../lib/pmptFile.js';
+import { restoreHistory, restoreDocs } from './clone.js';
 export async function cmdImport(pmptFile, options) {
     if (!pmptFile) {
         p.log.error('Please provide a .pmpt file path.');

package/dist/commands/mcp-setup.js

@@ -0,0 +1,205 @@
+import * as p from '@clack/prompts';
+import { execSync } from 'child_process';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+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');
+    if (existsSync(siblingPath)) {
+        return siblingPath;
+    }
+    // Strategy 2: which / where command
+    try {
+        const cmd = process.platform === 'win32' ? 'where pmpt-mcp' : 'which pmpt-mcp';
+        const result = execSync(cmd, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        const firstLine = result.split('\n')[0].trim();
+        if (firstLine && existsSync(firstLine)) {
+            return firstLine;
+        }
+    }
+    catch {
+        // not found in PATH
+    }
+    return null;
+}
+function isCommandAvailable(cmd) {
+    try {
+        const which = process.platform === 'win32' ? 'where' : 'which';
+        execSync(`${which} ${cmd}`, { stdio: ['pipe', 'pipe', 'pipe'] });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isClaudeAlreadyConfigured() {
+    try {
+        const result = execSync('claude mcp list', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+        return result.includes('pmpt');
+    }
+    catch {
+        return false;
+    }
+}
+function isJsonConfigured(configPath) {
+    try {
+        if (!existsSync(configPath))
+            return false;
+        const content = JSON.parse(readFileSync(configPath, 'utf-8'));
+        return !!content?.mcpServers?.pmpt;
+    }
+    catch {
+        return false;
+    }
+}
+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
+    }
+    execSync(`claude mcp add --transport stdio pmpt -- "${mcpBinaryPath}"`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+}
+function configureJsonFile(configPath, mcpBinaryPath) {
+    let config = {};
+    if (existsSync(configPath)) {
+        try {
+            config = JSON.parse(readFileSync(configPath, 'utf-8'));
+        }
+        catch {
+            config = {};
+        }
+    }
+    else {
+        mkdirSync(dirname(configPath), { recursive: true });
+    }
+    if (!config.mcpServers || typeof config.mcpServers !== 'object') {
+        config.mcpServers = {};
+    }
+    config.mcpServers.pmpt = {
+        command: mcpBinaryPath,
+    };
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+}
+export async function cmdMcpSetup() {
+    p.intro('pmpt mcp-setup');
+    // Step 1: Detect pmpt-mcp absolute path
+    const s = p.spinner();
+    s.start('Detecting pmpt-mcp location...');
+    let mcpPath = detectPmptMcpPath();
+    if (mcpPath) {
+        s.stop(`Found: ${mcpPath}`);
+    }
+    else {
+        s.stop('Could not auto-detect pmpt-mcp path');
+        p.log.warn('pmpt-mcp binary not found automatically.');
+        p.log.info('Install globally if not yet: npm install -g pmpt');
+        const manualPath = await p.text({
+            message: 'Enter the absolute path to pmpt-mcp:',
+            placeholder: '/usr/local/bin/pmpt-mcp',
+            validate: (value) => {
+                if (!value.trim())
+                    return 'Path is required';
+                if (!existsSync(value.trim()))
+                    return `File not found: ${value.trim()}`;
+                return undefined;
+            },
+        });
+        if (p.isCancel(manualPath)) {
+            p.cancel('Cancelled');
+            process.exit(0);
+        }
+        mcpPath = manualPath.trim();
+    }
+    // Step 2: Detect available MCP clients
+    const claudeAvailable = isCommandAvailable('claude');
+    const claudeConfigured = claudeAvailable && isClaudeAlreadyConfigured();
+    const cursorConfigPath = join(homedir(), '.cursor', 'mcp.json');
+    const cursorDirExists = existsSync(join(homedir(), '.cursor'));
+    const cursorConfigured = isJsonConfigured(cursorConfigPath);
+    const mcpJsonPath = join(process.cwd(), '.mcp.json');
+    const mcpJsonConfigured = isJsonConfigured(mcpJsonPath);
+    const options = [];
+    if (claudeAvailable) {
+        options.push({
+            value: 'claude-code',
+            label: 'Claude Code',
+            hint: claudeConfigured ? 'Already configured — will reconfigure' : 'claude CLI detected',
+            configPath: null,
+            alreadyConfigured: claudeConfigured,
+        });
+    }
+    if (cursorDirExists) {
+        options.push({
+            value: 'cursor',
+            label: 'Cursor',
+            hint: cursorConfigured ? 'Already configured — will reconfigure' : '~/.cursor/mcp.json',
+            configPath: cursorConfigPath,
+            alreadyConfigured: cursorConfigured,
+        });
+    }
+    options.push({
+        value: 'mcp-json',
+        label: '.mcp.json (project root)',
+        hint: mcpJsonConfigured ? 'Already configured — will reconfigure' : 'Works with any MCP-compatible tool',
+        configPath: mcpJsonPath,
+        alreadyConfigured: mcpJsonConfigured,
+    });
+    // Step 3: Select client
+    const selected = await p.select({
+        message: 'Which MCP client do you want to configure?',
+        options: options.map(o => ({
+            value: o.value,
+            label: o.label,
+            hint: o.hint,
+        })),
+    });
+    if (p.isCancel(selected)) {
+        p.cancel('Cancelled');
+        process.exit(0);
+    }
+    const client = options.find(o => o.value === selected);
+    // Step 4: Configure
+    const s2 = p.spinner();
+    s2.start(`Configuring ${client.label}...`);
+    try {
+        switch (client.value) {
+            case 'claude-code':
+                configureClaudeCode(mcpPath);
+                break;
+            case 'cursor':
+                configureJsonFile(client.configPath, mcpPath);
+                break;
+            case 'mcp-json':
+                configureJsonFile(client.configPath, mcpPath);
+                break;
+        }
+        s2.stop(`${client.label} configured!`);
+    }
+    catch (err) {
+        s2.stop('Configuration failed');
+        p.log.error(err instanceof Error ? err.message : 'Failed to write configuration.');
+        process.exit(1);
+    }
+    // Step 5: Summary
+    p.log.success(`MCP server registered for ${client.label}`);
+    if (client.value === 'claude-code') {
+        p.log.info('Registered via claude CLI.');
+    }
+    else {
+        p.log.info(`Config written to: ${client.configPath}`);
+    }
+    p.note([
+        `Binary:  ${mcpPath}`,
+        `Client:  ${client.label}`,
+        '',
+        'Available MCP tools:',
+        '  pmpt_save, pmpt_status, pmpt_history, pmpt_diff,',
+        '  pmpt_quality, pmpt_plan, pmpt_read_context, pmpt_publish',
+    ].join('\n'), 'MCP Setup Complete');
+    p.outro('Restart your AI tool to activate the MCP server.');
+}

package/dist/commands/squash.js

@@ -1,15 +1,99 @@
 import * as p from '@clack/prompts';
-import { resolve, join } from 'path';
-import { existsSync, rmSync, writeFileSync, readFileSync } from 'fs';
+import { resolve, join, basename } from 'path';
+import { existsSync, rmSync, renameSync, writeFileSync, readFileSync } from 'fs';
 import { isInitialized, getHistoryDir } from '../lib/config.js';
 import { getAllSnapshots } from '../lib/history.js';
-export async function cmdSquash(from, to, path) {
-    const projectPath = path ? resolve(path) : process.cwd();
+export async function cmdSquash(from, to, opts) {
+    const projectPath = opts?.path ? resolve(opts.path) : process.cwd();
     if (!isInitialized(projectPath)) {
         p.log.error('Project not initialized. Run `pmpt init` first.');
         process.exit(1);
     }
-    // Parse version numbers
+    const snapshots = getAllSnapshots(projectPath);
+    if (snapshots.length === 0) {
+        p.log.error('No snapshots found.');
+        process.exit(1);
+    }
+    if (opts?.auto) {
+        return autoSquash(projectPath, snapshots);
+    }
+    // Manual squash: require from and to
+    if (!from || !to) {
+        p.log.error('Usage: pmpt squash v2 v5  or  pmpt squash --auto');
+        process.exit(1);
+    }
+    return manualSquash(projectPath, snapshots, from, to);
+}
+/**
+ * Renumber remaining snapshots to v1, v2, v3... sequentially.
+ * Renames directories and updates .meta.json version fields.
+ */
+function renumberSnapshots(projectPath) {
+    const historyDir = getHistoryDir(projectPath);
+    const remaining = getAllSnapshots(projectPath); // sorted by version
+    for (let i = 0; i < remaining.length; i++) {
+        const snap = remaining[i];
+        const newVersion = i + 1;
+        if (snap.version === newVersion)
+            continue; // already correct
+        // Rename directory: v5-20260228T164006 → v2-20260228T164006
+        const dirName = basename(snap.snapshotDir);
+        const newDirName = dirName.replace(/^v\d+/, `v${newVersion}`);
+        const newDir = join(historyDir, newDirName);
+        renameSync(snap.snapshotDir, newDir);
+        // Update .meta.json
+        const metaPath = join(newDir, '.meta.json');
+        if (existsSync(metaPath)) {
+            const meta = JSON.parse(readFileSync(metaPath, 'utf-8'));
+            meta.version = newVersion;
+            writeFileSync(metaPath, JSON.stringify(meta, null, 2), 'utf-8');
+        }
+    }
+}
+async function autoSquash(projectPath, snapshots) {
+    // Find empty snapshots (no changed files)
+    const emptySnapshots = snapshots.filter(s => s.changedFiles && s.changedFiles.length === 0);
+    if (emptySnapshots.length === 0) {
+        p.log.info('No empty snapshots found. Nothing to clean up.');
+        return;
+    }
+    p.intro('pmpt squash --auto');
+    p.log.info(`Found ${emptySnapshots.length} empty snapshot(s) (no file changes):`);
+    for (const s of emptySnapshots) {
+        const git = s.git ? ` [${s.git.commit}]` : '';
+        p.log.message(`  v${s.version} — ${s.timestamp.slice(0, 16)}${git}`);
+    }
+    const confirm = await p.confirm({
+        message: `Delete ${emptySnapshots.length} empty snapshot(s) and renumber?`,
+        initialValue: true,
+    });
+    if (p.isCancel(confirm) || !confirm) {
+        p.cancel('Cancelled');
+        process.exit(0);
+    }
+    const sp = p.spinner();
+    sp.start('Removing empty snapshots...');
+    try {
+        let deleted = 0;
+        for (const snapshot of emptySnapshots) {
+            if (existsSync(snapshot.snapshotDir)) {
+                rmSync(snapshot.snapshotDir, { recursive: true });
+                deleted++;
+            }
+        }
+        renumberSnapshots(projectPath);
+        sp.stop('Cleaned up');
+        const remaining = snapshots.length - deleted;
+        p.log.success(`Removed ${deleted} empty snapshot(s), renumbered to v1-v${remaining}`);
+    }
+    catch (error) {
+        sp.stop('Failed');
+        p.log.error(error.message);
+        process.exit(1);
+    }
+    p.outro('View history: pmpt history');
+}
+async function manualSquash(projectPath, snapshots, from, to) {
     const fromVersion = parseInt(from.replace(/^v/, ''), 10);
     const toVersion = parseInt(to.replace(/^v/, ''), 10);
     if (isNaN(fromVersion) || isNaN(toVersion)) {
@@ -20,11 +104,6 @@ export async function cmdSquash(from, to, path) {
         p.log.error('First version must be less than second version.');
         process.exit(1);
     }
-    const snapshots = getAllSnapshots(projectPath);
-    if (snapshots.length === 0) {
-        p.log.error('No snapshots found.');
-        process.exit(1);
-    }
     const versionList = snapshots.map(s => `v${s.version}`).join(', ');
     // Find snapshots to squash
     const toSquash = snapshots.filter(s => s.version >= fromVersion && s.version <= toVersion);
@@ -46,7 +125,6 @@ export async function cmdSquash(from, to, path) {
     const s = p.spinner();
     s.start('Squashing versions...');
     try {
-        const historyDir = getHistoryDir(projectPath);
         const keepSnapshot = toSquash[0]; // Keep the first one
         const deleteSnapshots = toSquash.slice(1); // Delete the rest
         // Delete the snapshots we're squashing
@@ -64,8 +142,10 @@ export async function cmdSquash(from, to, path) {
             meta.squashedAt = new Date().toISOString();
             writeFileSync(metaPath, JSON.stringify(meta, null, 2), 'utf-8');
         }
+        renumberSnapshots(projectPath);
         s.stop('Squashed');
-        p.log.success(`Squashed v${fromVersion}-v${toVersion} into v${fromVersion}`);
+        const remaining = getAllSnapshots(projectPath);
+        p.log.success(`Squashed v${fromVersion}-v${toVersion}, renumbered to v1-v${remaining.length}`);
         p.log.info(`Deleted ${deleteSnapshots.length} version(s)`);
     }
     catch (error) {

package/dist/index.js

@@ -37,11 +37,13 @@ import { cmdPublish } from './commands/publish.js';
 import { cmdUpdate } from './commands/update.js';
 import { cmdEdit } from './commands/edit.js';
 import { cmdUnpublish } from './commands/unpublish.js';
+import { cmdGraduate } from './commands/graduate.js';
 import { cmdClone } from './commands/clone.js';
 import { cmdExplore } from './commands/browse.js';
 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 { trackCommand } from './lib/api.js';
 import { createRequire } from 'module';
 const require = createRequire(import.meta.url);
@@ -66,6 +68,7 @@ Examples:
   $ pmpt diff v1 v2              Compare two versions
   $ pmpt diff v3                 Compare v3 to working copy
   $ pmpt squash v2 v5            Merge versions v2-v5 into v2
+  $ pmpt squash --auto           Auto-remove empty snapshots
   $ pmpt export                  Export as .pmpt file (single JSON)
   $ pmpt import <file.pmpt>      Import from .pmpt file
   $ pmpt login                   Authenticate with pmptwiki
@@ -73,10 +76,14 @@ Examples:
   $ pmpt update                  Quick re-publish (content only)
   $ pmpt clone <slug>            Clone a project from pmptwiki
   $ pmpt explore (exp)           Explore projects on pmptwiki.com
+  $ 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 feedback (fb)           Share ideas or report bugs
 
 Workflow:
   init → plan → save → publish   Basic publishing flow
+  publish → graduate             Graduate to Hall of Fame
   init → plan → watch            Continuous development
   login → publish → update       Re-publish with updates
 
@@ -113,9 +120,11 @@ program
     .option('-f, --file <name>', 'Compare specific file only')
     .action(cmdDiff);
 program
-    .command('squash <from> <to> [path]')
-    .description('Squash multiple versions into one (e.g., pmpt squash v2 v5)')
-    .action(cmdSquash);
+    .command('squash [from] [to]')
+    .description('Squash versions: pmpt squash v2 v5  or  pmpt squash --auto')
+    .option('--auto', 'Auto-remove empty snapshots (no file changes)')
+    .option('-p, --path <path>', 'Project path')
+    .action((from, to, opts) => cmdSquash(from, to, opts));
 program
     .command('export [path]')
     .description('Export project history as a shareable .pmpt file')
@@ -174,6 +183,10 @@ program
     .command('unpublish')
     .description('Remove a published project from pmptwiki')
     .action(cmdUnpublish);
+program
+    .command('graduate')
+    .description('Graduate a project — archive it with a Hall of Fame badge')
+    .action(cmdGraduate);
 program
     .command('clone <slug>')
     .description('Clone a project from pmptwiki platform')
@@ -187,6 +200,43 @@ program
     .command('recover [path]')
     .description('Generate a recovery prompt to regenerate pmpt.md via AI')
     .action(cmdRecover);
+program
+    .command('mcp-setup')
+    .description('Configure pmpt MCP server for AI tools (Claude Code, Cursor, etc.)')
+    .action(cmdMcpSetup);
+program
+    .command('feedback')
+    .alias('fb')
+    .description('Share ideas, request features, or report bugs')
+    .action(async () => {
+    const prompts = await import('@clack/prompts');
+    const { exec } = await import('child_process');
+    prompts.intro('pmpt feedback');
+    const type = await prompts.select({
+        message: 'What would you like to do?',
+        options: [
+            { value: 'idea', label: 'Suggest a feature or idea' },
+            { value: 'bug', label: 'Report a bug' },
+            { value: 'question', label: 'Ask a question' },
+            { value: 'browse', label: 'Browse existing discussions' },
+        ],
+    });
+    if (prompts.isCancel(type)) {
+        prompts.cancel('Cancelled');
+        process.exit(0);
+    }
+    const urls = {
+        idea: 'https://github.com/pmptwiki/pmpt-cli/discussions/categories/ideas',
+        bug: 'https://github.com/pmptwiki/pmpt-cli/issues/new',
+        question: 'https://github.com/pmptwiki/pmpt-cli/discussions/categories/q-a',
+        browse: 'https://github.com/pmptwiki/pmpt-cli/discussions',
+    };
+    const url = urls[type];
+    const openCmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+    exec(`${openCmd} "${url}"`);
+    prompts.log.success(`Opening ${url}`);
+    prompts.outro('Thanks for your feedback!');
+});
 // Internal automation command (hidden from help)
 program
     .command('internal-seed', { hidden: true })

package/dist/lib/api.js

@@ -1,7 +1,7 @@
 /**
  * pmptwiki API client
  */
-const API_BASE = 'https://pmptwiki-api.sin2da.workers.dev';
+const API_BASE = 'https://pmptwiki-api.raunplaymore.workers.dev';
 const R2_PUBLIC_URL = 'https://pub-ce73b2410943490d80b60ddad9243d31.r2.dev';
 export async function requestDeviceCode() {
     const res = await fetch(`${API_BASE}/auth/device`, {
@@ -74,6 +74,31 @@ export async function unpublishProject(token, slug) {
         throw new Error(err.error);
     }
 }
+export async function graduateProject(token, slug, note) {
+    const res = await fetch(`${API_BASE}/graduate/${slug}`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${token}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ note }),
+    });
+    if (!res.ok) {
+        const err = await res.json().catch(() => ({ error: 'Graduate failed' }));
+        throw new Error(err.error);
+    }
+    return res.json();
+}
+export async function ungraduateProject(token, slug) {
+    const res = await fetch(`${API_BASE}/graduate/${slug}`, {
+        method: 'DELETE',
+        headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!res.ok) {
+        const err = await res.json().catch(() => ({ error: 'Ungraduate failed' }));
+        throw new Error(err.error);
+    }
+}
 export async function fetchPmptFile(slug) {
     const res = await fetch(`${R2_PUBLIC_URL}/projects/${slug}.pmpt`);
     if (!res.ok) {

package/dist/mcp.js

@@ -9,15 +9,18 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { resolve, join } from 'path';
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
 import glob from 'fast-glob';
 import { createRequire } from 'module';
 import { isInitialized, loadConfig, getDocsDir } from './lib/config.js';
 import { createFullSnapshot, getAllSnapshots, getTrackedFiles, resolveFullSnapshot } from './lib/history.js';
 import { computeQuality } from './lib/quality.js';
-import { getPlanProgress } from './lib/plan.js';
+import { getPlanProgress, savePlanProgress, savePlanDocuments, PLAN_QUESTIONS } from './lib/plan.js';
 import { isGitRepo } from './lib/git.js';
 import { diffSnapshots } from './lib/diff.js';
+import { loadAuth } from './lib/auth.js';
+import { publishProject, graduateProject } from './lib/api.js';
+import { createPmptFile } from './lib/pmptFile.js';
 const require = createRequire(import.meta.url);
 const { version } = require('../package.json');
 // ── Server ──────────────────────────────────────────
@@ -95,7 +98,10 @@ function formatDiffs(diffs) {
     return lines.join('\n');
 }
 // ── Tools ───────────────────────────────────────────
-server.tool('pmpt_save', 'Save a snapshot of .pmpt/docs/ files. Call after completing features, fixes, or milestones.', { projectPath: z.string().optional().describe('Project root path. Defaults to cwd.') }, async ({ projectPath }) => {
+server.tool('pmpt_save', 'Save a snapshot of .pmpt/docs/ files. Call after completing features, fixes, or milestones. IMPORTANT: Always provide a summary describing what was accomplished — this gets recorded in the project development log.', {
+    projectPath: z.string().optional().describe('Project root path. Defaults to cwd.'),
+    summary: z.string().optional().describe('What was accomplished since the last save. This is recorded in pmpt.md as a development log entry. Examples: "Implemented user auth with JWT", "Fixed responsive layout on mobile", "Added search filtering by category".'),
+}, async ({ projectPath, summary }) => {
     try {
         const pp = resolveProjectPath(projectPath);
         assertInitialized(pp);
@@ -103,13 +109,37 @@ server.tool('pmpt_save', 'Save a snapshot of .pmpt/docs/ files. Call after compl
         if (tracked.length === 0) {
             return { content: [{ type: 'text', text: 'No files to save. Add .md files to .pmpt/docs/ first.' }] };
         }
-        const entry = createFullSnapshot(pp);
+        // Auto-update pmpt.md with summary before snapshot
+        if (summary) {
+            const docsDir = getDocsDir(pp);
+            const pmptMdPath = join(docsDir, 'pmpt.md');
+            if (existsSync(pmptMdPath)) {
+                let content = readFileSync(pmptMdPath, 'utf-8');
+                const snapshots = getAllSnapshots(pp);
+                const nextVersion = snapshots.length + 1;
+                const date = new Date().toISOString().slice(0, 10);
+                const entry = `\n### v${nextVersion} — ${date}\n- ${summary}\n`;
+                const logIndex = content.indexOf('## Snapshot Log');
+                if (logIndex !== -1) {
+                    const afterHeader = content.indexOf('\n', logIndex);
+                    const nextSection = content.indexOf('\n## ', afterHeader + 1);
+                    const insertPos = nextSection !== -1 ? nextSection : content.length;
+                    content = content.slice(0, insertPos) + entry + content.slice(insertPos);
+                }
+                else {
+                    content += `\n## Snapshot Log${entry}`;
+                }
+                writeFileSync(pmptMdPath, content, 'utf-8');
+            }
+        }
+        const entry = createFullSnapshot(pp, summary ? { note: summary } : undefined);
         const changedCount = entry.changedFiles?.length ?? entry.files.length;
         return {
             content: [{
                     type: 'text',
                     text: [
                         `Snapshot v${entry.version} saved (${changedCount} changed, ${entry.files.length - changedCount} unchanged).`,
+                        summary ? `Summary: ${summary}` : '',
                         '',
                         `Files: ${entry.files.join(', ')}`,
                         entry.changedFiles ? `Changed: ${entry.changedFiles.join(', ')}` : '',
@@ -235,6 +265,385 @@ server.tool('pmpt_quality', 'Check project quality score and publish readiness.'
         return { content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
     }
 });
+server.tool('pmpt_plan_questions', 'Get the planning questions to ask the user. Call this FIRST when a user wants to build something, then ask each question conversationally. After collecting all answers, call pmpt_plan to generate the project.', { projectPath: z.string().optional().describe('Project root path. Defaults to cwd.') }, async ({ projectPath }) => {
+    try {
+        const pp = resolveProjectPath(projectPath);
+        assertInitialized(pp);
+        const existing = getPlanProgress(pp);
+        const lines = [
+            'Ask the user these questions one by one in a natural, conversational way.',
+            'You may skip questions the user has already answered in the conversation.',
+            'Required questions are marked with *.',
+            '',
+        ];
+        for (const q of PLAN_QUESTIONS) {
+            lines.push(`${q.required ? '*' : ' '} ${q.key}: ${q.question}`);
+            if (q.placeholder)
+                lines.push(`    hint: ${q.placeholder}`);
+        }
+        if (existing?.completed && existing.answers) {
+            lines.push('');
+            lines.push('NOTE: A plan already exists. Current answers:');
+            for (const q of PLAN_QUESTIONS) {
+                const val = existing.answers[q.key];
+                if (val)
+                    lines.push(`  ${q.key}: ${val}`);
+            }
+            lines.push('Ask if the user wants to update or start fresh.');
+        }
+        lines.push('');
+        lines.push('After collecting answers, call pmpt_plan with the collected answers.');
+        return { content: [{ type: 'text', text: lines.join('\n') }] };
+    }
+    catch (error) {
+        return { content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
+    }
+});
+server.tool('pmpt_plan', 'Finalize the plan: submit collected answers to generate AI prompt and project docs (plan.md, pmpt.md, pmpt.ai.md). Call pmpt_plan_questions first to get the questions, ask the user conversationally, then call this with the answers.', {
+    projectPath: z.string().optional().describe('Project root path. Defaults to cwd.'),
+    projectName: z.string().describe('Project name (e.g. "my-awesome-app").'),
+    productIdea: z.string().describe('What to build with AI — the core product idea.'),
+    coreFeatures: z.string().describe('Key features, separated by commas or semicolons.'),
+    additionalContext: z.string().optional().describe('Any extra context AI should know.'),
+    techStack: z.string().optional().describe('Preferred tech stack. AI will suggest if omitted.'),
+}, async ({ projectPath, projectName, productIdea, coreFeatures, additionalContext, techStack }) => {
+    try {
+        const pp = resolveProjectPath(projectPath);
+        assertInitialized(pp);
+        const answers = {
+            projectName,
+            productIdea,
+            coreFeatures,
+            additionalContext: additionalContext || '',
+            techStack: techStack || '',
+        };
+        // Save plan progress
+        savePlanProgress(pp, {
+            completed: true,
+            startedAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+            answers,
+        });
+        // Generate and save plan documents (plan.md, pmpt.md, pmpt.ai.md) + initial snapshot
+        const result = savePlanDocuments(pp, answers);
+        return {
+            content: [{
+                    type: 'text',
+                    text: [
+                        `Plan completed for "${projectName}"!`,
+                        '',
+                        `Generated files:`,
+                        `  - ${result.planPath} (project plan)`,
+                        `  - ${result.promptPath} (AI instruction — paste into AI tool)`,
+                        '',
+                        `Questions answered:`,
+                        ...PLAN_QUESTIONS.map(q => `  ${q.key}: ${answers[q.key] || '(skipped)'}`),
+                        '',
+                        `The AI prompt in pmpt.ai.md contains your development instructions.`,
+                        `You can now start building based on the plan. Run pmpt_save after milestones.`,
+                    ].join('\n'),
+                }],
+        };
+    }
+    catch (error) {
+        return { content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
+    }
+});
+server.tool('pmpt_read_context', 'Read project context to understand current state. Call this at the START of a new session to resume where you left off. Returns plan answers, docs content, recent history, and quality score.', {
+    projectPath: z.string().optional().describe('Project root path. Defaults to cwd.'),
+    includeDocsContent: z.boolean().optional().describe('Include full content of docs files. Defaults to true.'),
+}, async ({ projectPath, includeDocsContent }) => {
+    try {
+        const pp = resolveProjectPath(projectPath);
+        assertInitialized(pp);
+        const config = loadConfig(pp);
+        const planProgress = getPlanProgress(pp);
+        const tracked = getTrackedFiles(pp);
+        const snapshots = getAllSnapshots(pp);
+        const quality = computeQuality(buildQualityInput(pp));
+        const docsDir = getDocsDir(pp);
+        const lines = [];
+        // Project overview
+        const projectName = planProgress?.answers?.projectName || config?.lastPublishedSlug || '(unknown)';
+        lines.push(`# Project: ${projectName}`);
+        lines.push(`Quality: ${quality.score}/100 (${quality.grade}) | Snapshots: ${snapshots.length} | Files: ${tracked.length}`);
+        if (config?.lastPublished)
+            lines.push(`Last published: ${config.lastPublished.slice(0, 10)}`);
+        lines.push('');
+        // Plan answers
+        if (planProgress?.completed && planProgress.answers) {
+            lines.push('## Plan');
+            for (const q of PLAN_QUESTIONS) {
+                const val = planProgress.answers[q.key];
+                if (val)
+                    lines.push(`${q.key}: ${val}`);
+            }
+            lines.push('');
+        }
+        // Docs content
+        if (includeDocsContent !== false) {
+            lines.push('## Docs');
+            for (const file of tracked) {
+                const filePath = join(docsDir, file);
+                if (existsSync(filePath)) {
+                    const content = readFileSync(filePath, 'utf-8');
+                    lines.push(`### ${file}`);
+                    lines.push(content);
+                    lines.push('');
+                }
+            }
+        }
+        // Recent history (last 5)
+        if (snapshots.length > 0) {
+            lines.push('## Recent History');
+            const recent = snapshots.slice(-5);
+            for (const s of recent) {
+                const changed = s.changedFiles?.length ?? s.files.length;
+                const git = s.git ? ` [${s.git.commit}]` : '';
+                lines.push(`v${s.version} — ${s.timestamp.slice(0, 16)} — ${changed} changed${git}`);
+            }
+            lines.push('');
+        }
+        // Quality details
+        const failing = quality.details.filter(d => d.score < d.maxScore);
+        if (failing.length > 0) {
+            lines.push('## Improvement Areas');
+            for (const d of failing) {
+                lines.push(`- ${d.label}: ${d.score}/${d.maxScore}${d.tip ? ` — ${d.tip}` : ''}`);
+            }
+        }
+        return { content: [{ type: 'text', text: lines.join('\n') }] };
+    }
+    catch (error) {
+        return { content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
+    }
+});
+server.tool('pmpt_update_doc', 'Update pmpt.md: check off completed features, add progress notes, or append content. Use this after completing work to keep the project document up to date.', {
+    projectPath: z.string().optional().describe('Project root path. Defaults to cwd.'),
+    completedFeatures: z.array(z.string()).optional().describe('Feature names to mark as done (matches against checkbox items in pmpt.md).'),
+    progressNote: z.string().optional().describe('Progress note to append to the Snapshot Log section.'),
+    snapshotVersion: z.string().optional().describe('Version label for the snapshot log entry (e.g. "v3 - Auth Complete"). Auto-generated if omitted.'),
+}, async ({ projectPath, completedFeatures, progressNote, snapshotVersion }) => {
+    try {
+        const pp = resolveProjectPath(projectPath);
+        assertInitialized(pp);
+        const docsDir = getDocsDir(pp);
+        const pmptMdPath = join(docsDir, 'pmpt.md');
+        if (!existsSync(pmptMdPath)) {
+            return { content: [{ type: 'text', text: 'pmpt.md not found. Run pmpt_plan first to generate project docs.' }], isError: true };
+        }
+        let content = readFileSync(pmptMdPath, 'utf-8');
+        const changes = [];
+        // Check off completed features
+        if (completedFeatures && completedFeatures.length > 0) {
+            for (const feature of completedFeatures) {
+                const pattern = new RegExp(`- \\[ \\] (.*${feature.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}.*)`, 'i');
+                const match = content.match(pattern);
+                if (match) {
+                    content = content.replace(match[0], `- [x] ${match[1]}`);
+                    changes.push(`Checked: ${match[1]}`);
+                }
+            }
+        }
+        // Add progress note to Snapshot Log
+        if (progressNote) {
+            const snapshots = getAllSnapshots(pp);
+            const label = snapshotVersion || `v${snapshots.length} - Progress`;
+            const entry = `\n### ${label}\n- ${progressNote}\n`;
+            const logIndex = content.indexOf('## Snapshot Log');
+            if (logIndex !== -1) {
+                // Find the end of the Snapshot Log header line
+                const afterHeader = content.indexOf('\n', logIndex);
+                // Find the next ## section or end of file
+                const nextSection = content.indexOf('\n## ', afterHeader + 1);
+                const insertPos = nextSection !== -1 ? nextSection : content.length;
+                content = content.slice(0, insertPos) + entry + content.slice(insertPos);
+            }
+            else {
+                content += `\n## Snapshot Log${entry}`;
+            }
+            changes.push(`Added log: ${label}`);
+        }
+        if (changes.length === 0) {
+            return { content: [{ type: 'text', text: 'No changes to make. Provide completedFeatures or progressNote.' }] };
+        }
+        writeFileSync(pmptMdPath, content, 'utf-8');
+        return {
+            content: [{
+                    type: 'text',
+                    text: [`Updated pmpt.md:`, ...changes.map(c => `  - ${c}`), '', 'Run pmpt_save to create a snapshot.'].join('\n'),
+                }],
+        };
+    }
+    catch (error) {
+        return { content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
+    }
+});
+server.tool('pmpt_log_decision', 'Record an architectural or technical decision in pmpt.md. Use this when making important choices (tech stack, library selection, design patterns, etc.) so the reasoning is preserved.', {
+    projectPath: z.string().optional().describe('Project root path. Defaults to cwd.'),
+    title: z.string().describe('Short decision title (e.g. "Database: SQLite over PostgreSQL").'),
+    reasoning: z.string().describe('Why this decision was made.'),
+}, async ({ projectPath, title, reasoning }) => {
+    try {
+        const pp = resolveProjectPath(projectPath);
+        assertInitialized(pp);
+        const docsDir = getDocsDir(pp);
+        const pmptMdPath = join(docsDir, 'pmpt.md');
+        if (!existsSync(pmptMdPath)) {
+            return { content: [{ type: 'text', text: 'pmpt.md not found. Run pmpt_plan first.' }], isError: true };
+        }
+        let content = readFileSync(pmptMdPath, 'utf-8');
+        const date = new Date().toISOString().slice(0, 10);
+        const entry = `- **${title}** — ${reasoning} _(${date})_\n`;
+        const decisionsIndex = content.indexOf('## Decisions');
+        if (decisionsIndex !== -1) {
+            const afterHeader = content.indexOf('\n', decisionsIndex);
+            const nextSection = content.indexOf('\n## ', afterHeader + 1);
+            const insertPos = nextSection !== -1 ? nextSection : content.length;
+            content = content.slice(0, insertPos) + entry + content.slice(insertPos);
+        }
+        else {
+            // Insert before Snapshot Log if it exists, otherwise append
+            const logIndex = content.indexOf('## Snapshot Log');
+            if (logIndex !== -1) {
+                content = content.slice(0, logIndex) + `## Decisions\n${entry}\n` + content.slice(logIndex);
+            }
+            else {
+                content += `\n## Decisions\n${entry}`;
+            }
+        }
+        writeFileSync(pmptMdPath, content, 'utf-8');
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Decision recorded: ${title}\nReasoning: ${reasoning}`,
+                }],
+        };
+    }
+    catch (error) {
+        return { content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
+    }
+});
+server.tool('pmpt_publish', 'Publish the project to pmptwiki.com. Requires prior login via `pmpt login` in CLI. Packages project docs and history into a .pmpt file and uploads it.', {
+    projectPath: z.string().optional().describe('Project root path. Defaults to cwd.'),
+    slug: z.string().describe('Project slug (3-50 chars, lowercase alphanumeric and hyphens).'),
+    description: z.string().optional().describe('Project description (max 500 chars).'),
+    tags: z.array(z.string()).optional().describe('Tags for the project (max 10).'),
+    category: z.string().optional().describe('Category: web-app, mobile-app, cli-tool, api-backend, ai-ml, game, library, other.'),
+    productUrl: z.string().optional().describe('Product URL (GitHub repo or live site).'),
+    productUrlType: z.enum(['git', 'url']).optional().describe('Type of product URL.'),
+}, async ({ projectPath, slug, description, tags, category, productUrl, productUrlType }) => {
+    try {
+        const pp = resolveProjectPath(projectPath);
+        assertInitialized(pp);
+        // Check auth
+        const auth = loadAuth();
+        if (!auth) {
+            return { content: [{ type: 'text', text: 'Not logged in. Run `pmpt login` in the terminal first.' }], isError: true };
+        }
+        // Build .pmpt file content
+        const config = loadConfig(pp);
+        const planProgress = getPlanProgress(pp);
+        const snapshots = getAllSnapshots(pp);
+        const docsDir = getDocsDir(pp);
+        const quality = computeQuality(buildQualityInput(pp));
+        if (quality.score < 40) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Quality score ${quality.score}/100 is below minimum (40). Improve your project before publishing.\n\n${quality.details.filter(d => d.score < d.maxScore).map(d => `- ${d.label}: ${d.tip}`).join('\n')}`,
+                    }],
+                isError: true,
+            };
+        }
+        const projectName = planProgress?.answers?.projectName || config?.lastPublishedSlug || slug;
+        // Build versions
+        const history = snapshots.map((s, i) => {
+            const files = resolveFullSnapshot(snapshots, i);
+            return {
+                version: s.version,
+                timestamp: s.timestamp,
+                files,
+                changedFiles: s.changedFiles,
+                note: s.note,
+                git: s.git,
+            };
+        });
+        // Build docs
+        const docs = {};
+        const tracked = getTrackedFiles(pp);
+        for (const file of tracked) {
+            const filePath = join(docsDir, file);
+            if (existsSync(filePath)) {
+                docs[file] = readFileSync(filePath, 'utf-8');
+            }
+        }
+        const meta = {
+            projectName,
+            createdAt: snapshots[0]?.timestamp || new Date().toISOString(),
+            exportedAt: new Date().toISOString(),
+            description: description || '',
+        };
+        const planAnswers = planProgress?.answers
+            ? planProgress.answers
+            : undefined;
+        const pmptContent = createPmptFile(meta, planAnswers, docs, history);
+        // Publish
+        const result = await publishProject(auth.token, {
+            slug,
+            pmptContent,
+            description: description || '',
+            tags: tags || [],
+            category,
+            productUrl,
+            productUrlType,
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: [
+                        `Published "${projectName}" to pmptwiki!`,
+                        '',
+                        `URL: ${result.url}`,
+                        `Download: ${result.downloadUrl}`,
+                        `Slug: ${slug}`,
+                        `Author: @${auth.username}`,
+                    ].join('\n'),
+                }],
+        };
+    }
+    catch (error) {
+        return { content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
+    }
+});
+server.tool('pmpt_graduate', 'Graduate a project on pmptwiki — archives it with a Hall of Fame badge. The project can no longer be updated. Requires prior login via `pmpt login`.', {
+    slug: z.string().describe('Project slug to graduate.'),
+    note: z.string().optional().describe('Graduation note (e.g., "Reached 1000 users!").'),
+}, async ({ slug, note }) => {
+    try {
+        const auth = loadAuth();
+        if (!auth) {
+            return { content: [{ type: 'text', text: 'Not logged in. Run `pmpt login` in the terminal first.' }], isError: true };
+        }
+        const result = await graduateProject(auth.token, slug, note);
+        return {
+            content: [{
+                    type: 'text',
+                    text: [
+                        `Project "${slug}" has graduated! 🎓`,
+                        '',
+                        `Graduated at: ${result.graduatedAt}`,
+                        `Hall of Fame: https://pmptwiki.com/hall-of-fame`,
+                        '',
+                        'The project is now archived. No further updates are allowed.',
+                    ].join('\n'),
+                }],
+        };
+    }
+    catch (error) {
+        return { content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
+    }
+});
 // ── Start ───────────────────────────────────────────
 async function main() {
     const transport = new StdioServerTransport();

package/package.json

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