@hienlh/ppm 0.9.63 → 0.9.64

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hienlh/ppm",
-  "version": "0.9.63",
+  "version": "0.9.64",
   "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
   "author": "hienlh",
   "license": "MIT",

package/scripts/generate-bot-coordinator.ts

@@ -19,8 +19,6 @@ import { homedir } from "node:os";
 const ROOT = resolve(import.meta.dir, "..");
 const INDEX_PATH = join(ROOT, "src", "index.ts");
 const CMD_DIR = join(ROOT, "src", "cli", "commands");
-const SESSION_PATH = join(ROOT, "src", "services", "ppmbot", "ppmbot-session.ts");
-const COORDINATOR_MD = join(homedir(), ".ppm", "bot", "coordinator.md");
 
 // ── Types ──────────────────────────────────────────────────────────────
 
@@ -297,51 +295,15 @@ function formatCommand(group: string, cmd: CliCommand): string {
   return line;
 }
 
-function generateCoordinatorMd(groups: CommandGroup[]): string {
+/** Generate CLI-only reference (for cli-reference.md) */
+function generateCliReference(groups: CommandGroup[]): string {
   const sections: string[] = [];
-
-  sections.push(`# PPMBot — AI Project Coordinator
-
-You are PPMBot, a personal AI project coordinator and team leader. You communicate with users via Telegram and have full control over PPM through CLI commands.
-
-## Role
-- Answer direct questions immediately (coding, general knowledge, quick advice)
-- Delegate project-specific tasks to subagents using \`ppm bot delegate\`
-- Track delegated task status and report results proactively
-- Manage PPM server, projects, config, git, cloud, extensions, and databases
-- Remember user preferences across conversations
-
-## Decision Framework
-1. Can I answer this directly without project context? → Answer now
-2. Does this reference a specific project or need file access? → Delegate with \`ppm bot delegate\`
-3. Is this about PPM management (server/config/projects/git/db/cloud/ext)? → Use CLI commands directly
-4. Is this a destructive operation? → Confirm with user first
-5. Ambiguous project? → Ask user to clarify
-
-## Safety Rules (CRITICAL)
-Before executing destructive commands, ALWAYS confirm with the user:
-- \`ppm stop\` / \`ppm down\` / \`ppm restart\` → "Are you sure you want to stop/restart PPM?"
-- \`ppm db query <name> <sql>\` with writes → warn about data modification risk
-- \`ppm projects remove\` → confirm project name, warn it removes from registry
-- \`ppm config set\` → show current value with \`ppm config get\` BEFORE changing
-- \`ppm cloud logout\` / \`ppm cloud unlink\` → confirm, warn about losing cloud sync
-- \`ppm git reset\` → warn about potential data loss
-- \`ppm ext remove\` → confirm extension name
-
-## Operational Patterns
-- Before restart: check \`ppm status\` first
-- Before config change: read current value with \`ppm config get <key>\`
-- Before git push: check \`ppm git status --project <name>\` first
-- For DB operations: always specify connection name
-- For git operations: always use \`--project <name>\` flag`);
-
-  // CLI Reference
-  sections.push(`\n## CLI Command Reference`);
+  sections.push(`# PPM CLI Reference`);
 
   for (const group of groups) {
     const heading = group.name === "core"
-      ? `### Core Commands (${group.description})`
-      : `### ppm ${group.name} — ${group.description}`;
+      ? `## Core Commands (${group.description})`
+      : `## ppm ${group.name} — ${group.description}`;
     sections.push(heading);
 
     const cmdLines = group.commands.map((c) => formatCommand(group.name, c));
@@ -350,103 +312,86 @@ Before executing destructive commands, ALWAYS confirm with the user:
     sections.push("```");
   }
 
-  // Delegation section (always present, emphasized as primary tool)
   sections.push(`
-## Task Delegation (Primary Tool)
-
-### Delegate a task to a project
-\`\`\`
-ppm bot delegate --chat <chatId> --project <name> --prompt "<enriched task description>"
-\`\`\`
-Returns task ID in JSON. Tell user you're working on it.
-
-### Check task status
-\`\`\`
-ppm bot task-status <task-id>
-\`\`\`
-
-### Get task result
-\`\`\`
-ppm bot task-result <task-id>
-\`\`\`
-
-### List recent tasks
+## Quick Reference — Task Delegation
 \`\`\`
+ppm bot delegate --chat <chatId> --project <name> --prompt "<enriched task>"
+ppm bot task-status <id>
+ppm bot task-result <id>
 ppm bot tasks
 \`\`\`
 
-## Memory Management
+## Quick Reference — Memory
 \`\`\`
-ppm bot memory save "<content>" -c <category>    # categories: fact|preference|decision|architecture|issue
-ppm bot memory list                               # list saved memories
-ppm bot memory forget "<topic>"                   # delete matching memories
+ppm bot memory save "<content>" -c <category>
+ppm bot memory list
+ppm bot memory forget "<topic>"
 \`\`\`
 
-## Response Style
-- Keep responses concise (Telegram context — mobile-friendly)
-- Use short paragraphs, no walls of text
-- When delegating: acknowledge immediately, notify on completion
-- Support Vietnamese and English naturally
-- When showing CLI output: format for readability
-
-## Important
-- When delegating, write an enriched prompt with full context — not just the raw user message
-- Include relevant details: what the user wants, which files/features, acceptance criteria
-- Each delegation creates a fresh AI session in the target project workspace
-- Use \`--json\` flag when you need to parse command output programmatically`);
+## Tips
+- Use \`--json\` flag when parsing command output programmatically
+- For git/chat/db operations: always specify \`--project <name>\` or connection name`);
 
   return sections.join("\n");
 }
 
 // ── Source Code Update ────────────────────────────────────────────────
 
-function updateSourceDefault(content: string): void {
-  const src = readFileSync(SESSION_PATH, "utf-8");
+const CLI_DEFAULT_PATH = join(ROOT, "src", "services", "ppmbot", "cli-reference-default.ts");
+
+function updateBundledDefault(cliRef: string): void {
+  const escaped = cliRef
+    .replace(/\\/g, "\\\\")
+    .replace(/`/g, "\\`")
+    .replace(/\$\{/g, "\\${");
 
-  const startMarker = "export const DEFAULT_COORDINATOR_IDENTITY = `";
+  const src = readFileSync(CLI_DEFAULT_PATH, "utf-8");
+  const startMarker = "export const DEFAULT_CLI_REFERENCE = `";
   const startIdx = src.indexOf(startMarker);
   if (startIdx === -1) {
-    console.error("Could not find DEFAULT_COORDINATOR_IDENTITY in source");
+    console.error("Could not find DEFAULT_CLI_REFERENCE in cli-reference-default.ts");
     process.exit(1);
   }
 
   const afterStart = startIdx + startMarker.length;
   const endIdx = src.indexOf("\n`;\n", afterStart);
   if (endIdx === -1) {
-    console.error("Could not find closing backtick for DEFAULT_COORDINATOR_IDENTITY");
+    console.error("Could not find closing backtick for DEFAULT_CLI_REFERENCE");
     process.exit(1);
   }
 
-  // Escape backticks and ${} for template literal safety
-  const escaped = content
-    .replace(/\\/g, "\\\\")
-    .replace(/`/g, "\\`")
-    .replace(/\$\{/g, "\\${");
-
   const updated = src.slice(0, afterStart) + escaped + src.slice(endIdx);
-  writeFileSync(SESSION_PATH, updated);
-  console.log(`Updated: ${SESSION_PATH}`);
+  writeFileSync(CLI_DEFAULT_PATH, updated);
+  console.log(`Updated: ${CLI_DEFAULT_PATH}`);
 }
 
-function writeCoordinatorMd(content: string): void {
+function writeCliReferenceMd(cliRef: string): void {
   const dir = join(homedir(), ".ppm", "bot");
   mkdirSync(dir, { recursive: true });
-  writeFileSync(COORDINATOR_MD, content);
-  console.log(`Written: ${COORDINATOR_MD}`);
+  const cliRefPath = join(dir, "cli-reference.md");
+  // Read version from package.json
+  const pkg = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf-8"));
+  writeFileSync(cliRefPath, `<!-- ppm-version: ${pkg.version} -->\n${cliRef}`);
+  console.log(`Written: ${cliRefPath}`);
 }
 
 // ── Main ───────────────────────────────────────────────────────────────
 
 const cliArgs = process.argv.slice(2);
 const groups = buildGroups();
-const output = generateCoordinatorMd(groups);
-
-if (cliArgs.includes("--update")) {
-  writeCoordinatorMd(output);
-  updateSourceDefault(output);
+const cliRef = generateCliReference(groups);
+
+if (cliArgs.includes("--cli-only")) {
+  // Runtime mode: just output CLI reference to stdout (used by ensureCliReference)
+  console.log(cliRef);
+} else if (cliArgs.includes("--update")) {
+  // Dev mode: write cli-reference.md + update bundled default
+  writeCliReferenceMd(cliRef);
+  updateBundledDefault(cliRef);
   console.log("\nDone. Review the changes and test with PPMBot.");
 } else if (cliArgs.includes("--write-md")) {
-  writeCoordinatorMd(output);
+  writeCliReferenceMd(cliRef);
 } else {
-  console.log(output);
+  // Default: stdout
+  console.log(cliRef);
 }

package/src/services/ppmbot/cli-reference-default.ts

@@ -0,0 +1,330 @@
+/**
+ * Bundled CLI reference fallback for compiled binary (when generator script is unavailable).
+ * Auto-generated by: bun scripts/generate-bot-coordinator.ts --update-default
+ *
+ * To regenerate: bun generate:bot
+ */
+
+// prettier-ignore
+export const DEFAULT_CLI_REFERENCE = `# PPM CLI Reference
+## Core Commands (Server & system management)
+\`\`\`
+ppm start
+  Start the PPM server (background by default)
+  -p, --port <port> — Port to listen on
+  -s, --share — (deprecated) Tunnel is now always enabled
+  -c, --config <path> — Path to config file (YAML import into DB)
+
+ppm stop
+  Stop the PPM server (supervisor stays alive)
+  -a, --all — Kill all PPM and cloudflared processes (including untracked)
+  --kill — Full shutdown (kills supervisor too)
+
+ppm down
+  Fully shut down PPM (supervisor + server + tunnel)
+
+ppm restart
+  Restart the server (keeps tunnel alive)
+  -c, --config <path> — Path to config file
+  --force — Force resume from paused state
+
+ppm status
+  Show PPM daemon status
+  -a, --all — Show all PPM and cloudflared processes (including untracked)
+  --json — Output as JSON
+
+ppm open
+  Open PPM in browser
+  -c, --config <path> — Path to config file
+
+ppm logs
+  View PPM daemon logs
+  -n, --tail <lines> — Number of lines to show [default: 50]
+  -f, --follow — Follow log output
+  --clear — Clear log file
+
+ppm report
+  Report a bug on GitHub (pre-fills env info + logs)
+
+ppm init
+  Initialize PPM configuration (interactive or via flags)
+  -p, --port <port> — Port to listen on
+  --scan <path> — Directory to scan for git repos
+  --auth — Enable authentication
+  --no-auth — Disable authentication
+  --password <pw> — Set access password
+  --share — Pre-install cloudflared for sharing
+  -y, --yes — Non-interactive mode (use defaults + flags)
+
+ppm upgrade
+  Check for and install PPM updates
+\`\`\`
+## ppm projects — Manage registered projects
+\`\`\`
+ppm projects list
+  List all registered projects
+
+ppm projects add <path>
+  Add a project to the registry
+  -n, --name <name> — Project name (defaults to folder name)
+
+ppm projects remove <name>
+  Remove a project from the registry
+\`\`\`
+## ppm config — Configuration management
+\`\`\`
+ppm config get <key>
+  Get a config value (e.g. port, auth.enabled)
+
+ppm config set <key> <value>
+  Set a config value (e.g. port 9090)
+\`\`\`
+## ppm git — Git operations for a project
+\`\`\`
+ppm git status
+  Show working tree status
+  -p, --project <name> — Project name or path
+
+ppm git log
+  Show recent commits
+  -p, --project <name> — Project name or path
+  -n, --count <n> — Number of commits to show [default: 20]
+
+ppm git diff [ref1] [ref2]
+  Show diff between refs or working tree
+  -p, --project <name> — Project name or path
+
+ppm git stage <files...>
+  Stage files (use "." to stage all)
+  -p, --project <name> — Project name or path
+
+ppm git unstage <files...>
+  Unstage files
+  -p, --project <name> — Project name or path
+
+ppm git commit
+  Commit staged changes
+  -p, --project <name> — Project name or path
+  -m, --message <msg> — Commit message (required)
+
+ppm git push
+  Push to remote
+  -p, --project <name> — Project name or path
+  --remote <remote> — Remote name [default: origin]
+  --branch <branch> — Branch name
+
+ppm git pull
+  Pull from remote
+  -p, --project <name> — Project name or path
+  --remote <remote> — Remote name
+  --branch <branch> — Branch name
+
+ppm git branch create <name>
+  Create and checkout a new branch
+  -p, --project <name> — Project name or path
+  --from <ref> — Base ref (commit/branch/tag)
+
+ppm git branch checkout <name>
+  Switch to a branch
+  -p, --project <name> — Project name or path
+
+ppm git branch delete <name>
+  Delete a branch
+  -p, --project <name> — Project name or path
+  -f, --force — Force delete
+
+ppm git branch merge <source>
+  Merge a branch into current branch
+  -p, --project <name> — Project name or path
+\`\`\`
+## ppm chat — AI chat sessions
+\`\`\`
+ppm chat list
+  List all chat sessions
+  -p, --project <name> — Filter by project name
+
+ppm chat create
+  Create a new chat session
+  -p, --project <name> — Project name or path
+  --provider <provider> — AI provider (default: claude)
+
+ppm chat send <session-id> <message>
+  Send a message and stream response to stdout
+  -p, --project <name> — Project name or path
+
+ppm chat resume <session-id>
+  Resume an interactive chat session
+  -p, --project <name> — Project name or path
+
+ppm chat delete <session-id>
+  Delete a chat session
+\`\`\`
+## ppm db — Database connections & queries
+\`\`\`
+ppm db list
+  List all saved database connections
+
+ppm db add
+  Add a new database connection
+  -n, --name <name> — Connection name (unique) (required)
+  -t, --type <type> — Database type: sqlite | postgres (required)
+  -c, --connection-string <url> — PostgreSQL connection string
+  -f, --file <path> — SQLite file path (absolute)
+  -g, --group <group> — Group name
+  --color <color> — Tab color (hex, e.g. #3b82f6)
+
+ppm db remove <name>
+  Remove a saved connection (by name or ID)
+
+ppm db test <name>
+  Test a saved connection
+
+ppm db tables <name>
+  List tables in a database connection
+
+ppm db schema <name> <table>
+  Show table schema (columns, types, constraints)
+  -s, --schema <schema> — PostgreSQL schema name [default: public]
+
+ppm db data <name> <table>
+  View table data (paginated)
+  -p, --page <page> — Page number [default: 1]
+  -l, --limit <limit> — Rows per page [default: 50]
+  --order <column> — Order by column
+  --desc — Descending order
+  -s, --schema <schema> — PostgreSQL schema name [default: public]
+
+ppm db query <name> <sql>
+  Execute a SQL query against a saved connection
+\`\`\`
+## ppm autostart — Auto-start on boot
+\`\`\`
+ppm autostart enable
+  Register PPM to start automatically on boot
+  -p, --port <port> — Override port
+  -s, --share — (deprecated) Tunnel is now always enabled
+  -c, --config <path> — Config file path
+  --profile <name> — DB profile name
+
+ppm autostart disable
+  Remove PPM auto-start registration
+
+ppm autostart status
+  Show auto-start status
+  --json — Output as JSON
+\`\`\`
+## ppm cloud — PPM Cloud — device registry + tunnel
+\`\`\`
+ppm cloud login
+  Sign in with Google
+  --url <url> — Cloud URL override
+  --device-code — Force device code flow (for remote terminals)
+
+ppm cloud logout
+  Sign out from PPM Cloud
+
+ppm cloud link
+  Register this machine with PPM Cloud
+  -n, --name <name> — Machine display name
+
+ppm cloud unlink
+  Remove this machine from PPM Cloud
+
+ppm cloud status
+  Show PPM Cloud connection status
+  --json — Output as JSON
+
+ppm cloud devices
+  List all registered devices from cloud
+  --json — Output as JSON
+\`\`\`
+## ppm ext — Manage PPM extensions
+\`\`\`
+ppm ext install <name>
+  Install an extension from npm
+
+ppm ext remove <name>
+  Remove an installed extension
+
+ppm ext list
+  List installed extensions
+
+ppm ext enable <name>
+  Enable an extension
+
+ppm ext disable <name>
+  Disable an extension
+
+ppm ext dev <path>
+  Symlink a local extension for development
+\`\`\`
+## ppm bot — PPMBot coordinator utilities
+\`\`\`
+ppm bot delegate
+  Delegate a task to a project subagent
+  --chat <id> — Telegram chat ID (required)
+  --project <name> — Project name (required)
+  --prompt <text> — Enriched task prompt (required)
+  --timeout <ms> — Timeout in milliseconds [default: 900000]
+
+ppm bot task-status <id>
+  Get status of a delegated task
+
+ppm bot task-result <id>
+  Get full result of a completed task
+
+ppm bot tasks
+  List recent delegated tasks
+  --chat <id> — Telegram chat ID (auto-detected if single)
+
+ppm bot memory save <content>
+  Save a cross-project memory
+  -c, --category <cat> — Category: fact|preference|decision|architecture|issue [default: fact]
+  -s, --session <id> — Session ID (optional)
+
+ppm bot memory list
+  List active cross-project memories
+  -l, --limit <n> — Max results [default: 30]
+  --json — Output as JSON
+
+ppm bot memory forget <topic>
+  Delete memories matching a topic (FTS5 search)
+
+ppm bot project list
+  List available projects
+  --json — Output as JSON
+
+ppm bot status
+  Show current status and running tasks
+  --chat <id> — Telegram chat ID (auto-detected if single)
+  --json — Output as JSON
+
+ppm bot version
+  Show PPM version
+
+ppm bot restart
+  Restart the PPM server
+
+ppm bot help
+  Show all bot CLI commands
+\`\`\`
+
+## Quick Reference — Task Delegation
+\`\`\`
+ppm bot delegate --chat <chatId> --project <name> --prompt "<enriched task>"
+ppm bot task-status <id>
+ppm bot task-result <id>
+ppm bot tasks
+\`\`\`
+
+## Quick Reference — Memory
+\`\`\`
+ppm bot memory save "<content>" -c <category>
+ppm bot memory list
+ppm bot memory forget "<topic>"
+\`\`\`
+
+## Tips
+- Use \`--json\` flag when parsing command output programmatically
+- For git/chat/db operations: always specify \`--project <name>\` or connection name
+`;

package/src/services/ppmbot/ppmbot-service.ts

@@ -14,7 +14,7 @@ import {
   markBotTaskReported,
 } from "../db.service.ts";
 import { PPMBotTelegram } from "./ppmbot-telegram.ts";
-import { PPMBotSessionManager, ensureCoordinatorWorkspace, DEFAULT_COORDINATOR_IDENTITY } from "./ppmbot-session.ts";
+import { PPMBotSessionManager, ensureCoordinatorWorkspace, readCliReference, DEFAULT_COORDINATOR_IDENTITY } from "./ppmbot-session.ts";
 import { PPMBotMemory } from "./ppmbot-memory.ts";
 import { streamToTelegram } from "./ppmbot-streamer.ts";
 import { escapeHtml } from "./ppmbot-formatter.ts";
@@ -286,6 +286,13 @@ I'll answer directly or delegate to your project's AI.`;
       parts.push(identity);
     }
 
+    // CLI reference (from cli-reference.md)
+    const cliRef = readCliReference();
+    if (cliRef) {
+      parts.push(`\n## CLI Reference`);
+      parts.push(cliRef);
+    }
+
     // Session info
     parts.push(`\n## Session Info`);
     parts.push(`Chat ID: ${chatId}`);

package/src/services/ppmbot/ppmbot-session.ts

@@ -1,8 +1,9 @@
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync as fsRead, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { chatService } from "../chat.service.ts";
 import { configService } from "../config.service.ts";
+import { VERSION } from "../../version.ts";
 import {
   getActivePPMBotSession,
   createPPMBotSession,
@@ -10,6 +11,7 @@ import {
   touchPPMBotSession,
   getDistinctPPMBotProjectNames,
 } from "../db.service.ts";
+import { DEFAULT_CLI_REFERENCE } from "./cli-reference-default.ts";
 import type { PPMBotActiveSession, PPMBotSessionRow } from "../../types/ppmbot.ts";
 import type { PPMBotConfig, ProjectConfig } from "../../types/config.ts";
 
@@ -34,371 +36,41 @@ You are PPMBot, a personal AI project coordinator and team leader. You communica
 ## Safety Rules (CRITICAL)
 Before executing destructive commands, ALWAYS confirm with the user:
 - \`ppm stop\` / \`ppm down\` / \`ppm restart\` → "Are you sure you want to stop/restart PPM?"
-- \`ppm db query <name> <sql>\` with writes → warn about data modification risk
-- \`ppm projects remove\` → confirm project name, warn it removes from registry
+- \`ppm db query\` with writes → warn about data modification risk
+- \`ppm projects remove\` → confirm project name
 - \`ppm config set\` → show current value with \`ppm config get\` BEFORE changing
-- \`ppm cloud logout\` / \`ppm cloud unlink\` → confirm, warn about losing cloud sync
-- \`ppm git reset\` → warn about potential data loss
+- \`ppm cloud logout\` / \`ppm cloud unlink\` → confirm
+- \`ppm git branch delete\` → warn about potential data loss
 - \`ppm ext remove\` → confirm extension name
 
 ## Operational Patterns
 - Before restart: check \`ppm status\` first
-- Before config change: read current value with \`ppm config get <key>\`
-- Before git push: check \`ppm git status --project <name>\` first
+- Before config change: read current with \`ppm config get <key>\`
+- Before git push: check \`ppm git status --project <name>\`
 - For DB operations: always specify connection name
 - For git operations: always use \`--project <name>\` flag
 
-## CLI Command Reference
-### Core Commands (Server & system management)
-\`\`\`
-ppm start
-  Start the PPM server (background by default)
-  -p, --port <port> — Port to listen on
-  -s, --share — (deprecated) Tunnel is now always enabled
-  -c, --config <path> — Path to config file (YAML import into DB)
-
-ppm stop
-  Stop the PPM server (supervisor stays alive)
-  -a, --all — Kill all PPM and cloudflared processes (including untracked)
-  --kill — Full shutdown (kills supervisor too)
-
-ppm down
-  Fully shut down PPM (supervisor + server + tunnel)
-
-ppm restart
-  Restart the server (keeps tunnel alive)
-  -c, --config <path> — Path to config file
-  --force — Force resume from paused state
-
-ppm status
-  Show PPM daemon status
-  -a, --all — Show all PPM and cloudflared processes (including untracked)
-  --json — Output as JSON
-
-ppm open
-  Open PPM in browser
-  -c, --config <path> — Path to config file
-
-ppm logs
-  View PPM daemon logs
-  -n, --tail <lines> — Number of lines to show [default: 50]
-  -f, --follow — Follow log output
-  --clear — Clear log file
-
-ppm report
-  Report a bug on GitHub (pre-fills env info + logs)
-
-ppm init
-  Initialize PPM configuration (interactive or via flags)
-  -p, --port <port> — Port to listen on
-  --scan <path> — Directory to scan for git repos
-  --auth — Enable authentication
-  --no-auth — Disable authentication
-  --password <pw> — Set access password
-  --share — Pre-install cloudflared for sharing
-  -y, --yes — Non-interactive mode (use defaults + flags)
-
-ppm upgrade
-  Check for and install PPM updates
-\`\`\`
-### ppm projects — Manage registered projects
-\`\`\`
-ppm projects list
-  List all registered projects
-
-ppm projects add <path>
-  Add a project to the registry
-  -n, --name <name> — Project name (defaults to folder name)
-
-ppm projects remove <name>
-  Remove a project from the registry
-\`\`\`
-### ppm config — Configuration management
-\`\`\`
-ppm config get <key>
-  Get a config value (e.g. port, auth.enabled)
-
-ppm config set <key> <value>
-  Set a config value (e.g. port 9090)
-\`\`\`
-### ppm git — Git operations for a project
-\`\`\`
-ppm git status
-  Show working tree status
-  -p, --project <name> — Project name or path
-
-ppm git log
-  Show recent commits
-  -p, --project <name> — Project name or path
-  -n, --count <n> — Number of commits to show [default: 20]
-
-ppm git diff [ref1] [ref2]
-  Show diff between refs or working tree
-  -p, --project <name> — Project name or path
-
-ppm git stage <files...>
-  Stage files (use "." to stage all)
-  -p, --project <name> — Project name or path
-
-ppm git unstage <files...>
-  Unstage files
-  -p, --project <name> — Project name or path
-
-ppm git commit
-  Commit staged changes
-  -p, --project <name> — Project name or path
-  -m, --message <msg> — Commit message (required)
-
-ppm git push
-  Push to remote
-  -p, --project <name> — Project name or path
-  --remote <remote> — Remote name [default: origin]
-  --branch <branch> — Branch name
-
-ppm git pull
-  Pull from remote
-  -p, --project <name> — Project name or path
-  --remote <remote> — Remote name
-  --branch <branch> — Branch name
-
-ppm git branch create <name>
-  Create and checkout a new branch
-  -p, --project <name> — Project name or path
-  --from <ref> — Base ref (commit/branch/tag)
-
-ppm git branch checkout <name>
-  Switch to a branch
-  -p, --project <name> — Project name or path
-
-ppm git branch delete <name>
-  Delete a branch
-  -p, --project <name> — Project name or path
-  -f, --force — Force delete
-
-ppm git branch merge <source>
-  Merge a branch into current branch
-  -p, --project <name> — Project name or path
-\`\`\`
-### ppm chat — AI chat sessions
-\`\`\`
-ppm chat list
-  List all chat sessions
-  -p, --project <name> — Filter by project name
-
-ppm chat create
-  Create a new chat session
-  -p, --project <name> — Project name or path
-  --provider <provider> — AI provider (default: claude)
-
-ppm chat send <session-id> <message>
-  Send a message and stream response to stdout
-  -p, --project <name> — Project name or path
-
-ppm chat resume <session-id>
-  Resume an interactive chat session
-  -p, --project <name> — Project name or path
-
-ppm chat delete <session-id>
-  Delete a chat session
-\`\`\`
-### ppm db — Database connections & queries
-\`\`\`
-ppm db list
-  List all saved database connections
-
-ppm db add
-  Add a new database connection
-  -n, --name <name> — Connection name (unique) (required)
-  -t, --type <type> — Database type: sqlite | postgres (required)
-  -c, --connection-string <url> — PostgreSQL connection string
-  -f, --file <path> — SQLite file path (absolute)
-  -g, --group <group> — Group name
-  --color <color> — Tab color (hex, e.g. #3b82f6)
-
-ppm db remove <name>
-  Remove a saved connection (by name or ID)
-
-ppm db test <name>
-  Test a saved connection
-
-ppm db tables <name>
-  List tables in a database connection
-
-ppm db schema <name> <table>
-  Show table schema (columns, types, constraints)
-  -s, --schema <schema> — PostgreSQL schema name [default: public]
-
-ppm db data <name> <table>
-  View table data (paginated)
-  -p, --page <page> — Page number [default: 1]
-  -l, --limit <limit> — Rows per page [default: 50]
-  --order <column> — Order by column
-  --desc — Descending order
-  -s, --schema <schema> — PostgreSQL schema name [default: public]
-
-ppm db query <name> <sql>
-  Execute a SQL query against a saved connection
-\`\`\`
-### ppm autostart — Auto-start on boot
-\`\`\`
-ppm autostart enable
-  Register PPM to start automatically on boot
-  -p, --port <port> — Override port
-  -s, --share — (deprecated) Tunnel is now always enabled
-  -c, --config <path> — Config file path
-  --profile <name> — DB profile name
-
-ppm autostart disable
-  Remove PPM auto-start registration
-
-ppm autostart status
-  Show auto-start status
-  --json — Output as JSON
-\`\`\`
-### ppm cloud — PPM Cloud — device registry + tunnel
-\`\`\`
-ppm cloud login
-  Sign in with Google
-  --url <url> — Cloud URL override
-  --device-code — Force device code flow (for remote terminals)
-
-ppm cloud logout
-  Sign out from PPM Cloud
-
-ppm cloud link
-  Register this machine with PPM Cloud
-  -n, --name <name> — Machine display name
-
-ppm cloud unlink
-  Remove this machine from PPM Cloud
-
-ppm cloud status
-  Show PPM Cloud connection status
-  --json — Output as JSON
-
-ppm cloud devices
-  List all registered devices from cloud
-  --json — Output as JSON
-\`\`\`
-### ppm ext — Manage PPM extensions
-\`\`\`
-ppm ext install <name>
-  Install an extension from npm
-
-ppm ext remove <name>
-  Remove an installed extension
-
-ppm ext list
-  List installed extensions
-
-ppm ext enable <name>
-  Enable an extension
-
-ppm ext disable <name>
-  Disable an extension
-
-ppm ext dev <path>
-  Symlink a local extension for development
-\`\`\`
-### ppm bot — PPMBot coordinator utilities
-\`\`\`
-ppm bot delegate
-  Delegate a task to a project subagent
-  --chat <id> — Telegram chat ID (required)
-  --project <name> — Project name (required)
-  --prompt <text> — Enriched task prompt (required)
-  --timeout <ms> — Timeout in milliseconds [default: 900000]
-
-ppm bot task-status <id>
-  Get status of a delegated task
-
-ppm bot task-result <id>
-  Get full result of a completed task
-
-ppm bot tasks
-  List recent delegated tasks
-  --chat <id> — Telegram chat ID (auto-detected if single)
-
-ppm bot memory save <content>
-  Save a cross-project memory
-  -c, --category <cat> — Category: fact|preference|decision|architecture|issue [default: fact]
-  -s, --session <id> — Session ID (optional)
-
-ppm bot memory list
-  List active cross-project memories
-  -l, --limit <n> — Max results [default: 30]
-  --json — Output as JSON
-
-ppm bot memory forget <topic>
-  Delete memories matching a topic (FTS5 search)
-
-ppm bot project list
-  List available projects
-  --json — Output as JSON
-
-ppm bot status
-  Show current status and running tasks
-  --chat <id> — Telegram chat ID (auto-detected if single)
-  --json — Output as JSON
-
-ppm bot version
-  Show PPM version
-
-ppm bot restart
-  Restart the PPM server
-
-ppm bot help
-  Show all bot CLI commands
-\`\`\`
-
-## Task Delegation (Primary Tool)
-
-### Delegate a task to a project
-\`\`\`
-ppm bot delegate --chat <chatId> --project <name> --prompt "<enriched task description>"
-\`\`\`
-Returns task ID in JSON. Tell user you're working on it.
-
-### Check task status
-\`\`\`
-ppm bot task-status <task-id>
-\`\`\`
-
-### Get task result
-\`\`\`
-ppm bot task-result <task-id>
-\`\`\`
-
-### List recent tasks
-\`\`\`
-ppm bot tasks
-\`\`\`
-
-## Memory Management
-\`\`\`
-ppm bot memory save "<content>" -c <category>    # categories: fact|preference|decision|architecture|issue
-ppm bot memory list                               # list saved memories
-ppm bot memory forget "<topic>"                   # delete matching memories
-\`\`\`
+## CLI Commands
+Full CLI reference is in \`cli-reference.md\` (auto-injected into context).
 
 ## Response Style
-- Keep responses concise (Telegram context — mobile-friendly)
-- Use short paragraphs, no walls of text
+- Keep responses concise (Telegram — mobile-friendly)
+- Short paragraphs, no walls of text
 - When delegating: acknowledge immediately, notify on completion
 - Support Vietnamese and English naturally
-- When showing CLI output: format for readability
 
 ## Important
-- When delegating, write an enriched prompt with full context — not just the raw user message
-- Include relevant details: what the user wants, which files/features, acceptance criteria
+- When delegating, write enriched prompts with full context — not just raw user message
+- Include: what user wants, which files/features, acceptance criteria
 - Each delegation creates a fresh AI session in the target project workspace
-- Use \`--json\` flag when you need to parse command output programmatically
+- Use \`--json\` flag when parsing command output programmatically
 `;
 
-/** Ensure ~/.ppm/bot/ workspace exists with coordinator.md */
+/** Ensure ~/.ppm/bot/ workspace exists with coordinator.md + cli-reference.md */
 export function ensureCoordinatorWorkspace(): void {
   const botDir = join(homedir(), ".ppm", "bot");
   const coordinatorMd = join(botDir, "coordinator.md");
+  const cliRefPath = join(botDir, "cli-reference.md");
   const settingsDir = join(botDir, ".claude");
   const settingsFile = join(settingsDir, "settings.local.json");
 
@@ -413,6 +85,63 @@ export function ensureCoordinatorWorkspace(): void {
       permissions: { allow: ["Bash", "Read", "Write", "Edit", "Glob", "Grep"] },
     }, null, 2));
   }
+
+  // Auto-generate cli-reference.md if missing or version mismatch
+  ensureCliReference(cliRefPath);
+}
+
+/** Read CLI reference from disk (for context injection) */
+export function readCliReference(): string {
+  const cliRefPath = join(homedir(), ".ppm", "bot", "cli-reference.md");
+  try {
+    return fsRead(cliRefPath, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Generate cli-reference.md if missing or version differs.
+ * Embeds version header: `<!-- ppm-version: x.x.x -->`
+ */
+function ensureCliReference(cliRefPath: string): void {
+  // Check existing version
+  if (existsSync(cliRefPath)) {
+    try {
+      const existing = fsRead(cliRefPath, "utf-8");
+      const versionMatch = existing.match(/<!-- ppm-version: (.+?) -->/);
+      if (versionMatch && versionMatch[1] === VERSION) return; // up to date
+    } catch { /* regenerate on read error */ }
+  }
+
+  try {
+    const content = generateCliReference();
+    writeFileSync(cliRefPath, content);
+    console.log(`[ppmbot] Generated cli-reference.md (v${VERSION})`);
+  } catch (err) {
+    console.warn(`[ppmbot] Failed to generate cli-reference.md:`, (err as Error).message);
+  }
+}
+
+/** Generate CLI reference by running the generator script */
+function generateCliReference(): string {
+  const { spawnSync } = require("node:child_process") as typeof import("node:child_process");
+  const scriptPath = join(import.meta.dir, "../../../scripts/generate-bot-coordinator.ts");
+
+  // If generator script exists (dev/source install), run it
+  if (existsSync(scriptPath)) {
+    const result = spawnSync("bun", [scriptPath, "--cli-only"], {
+      cwd: join(import.meta.dir, "../../.."),
+      timeout: 10_000,
+      encoding: "utf-8",
+    });
+    if (result.status === 0 && result.stdout) {
+      return `<!-- ppm-version: ${VERSION} -->\n${result.stdout}`;
+    }
+  }
+
+  // Fallback: generate from bundled constant
+  return `<!-- ppm-version: ${VERSION} -->\n${DEFAULT_CLI_REFERENCE}`;
 }
 
 export class PPMBotSessionManager {