@hienlh/ppm 0.9.62 → 0.9.64

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.9.63] - 2026-04-08
+
+### Fixed
+- **Cloud auto-link**: `ppm cloud login` now auto-links device (no separate `ppm cloud link` needed). `ppm cloud logout` auto-unlinks.
+- **Supervisor cloud monitor**: Supervisor periodically checks cloud-device.json and auto-connects/disconnects/reconnects WS as needed. Fixes "stuck offline" after upgrade or file loss.
+- **Stale tests**: Aligned usage-cache and chat-routes tests with current API response shapes.
+
 ## [0.9.62] - 2026-04-08
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hienlh/ppm",
-  "version": "0.9.62",
+  "version": "0.9.64",
   "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
   "author": "hienlh",
   "license": "MIT",
@@ -18,6 +18,7 @@
     "build": "bun run build:web && bun build src/index.ts --compile --outfile dist/ppm",
     "start": "bun run src/index.ts start",
     "typecheck": "bunx tsc --noEmit",
+    "generate:bot": "bun scripts/generate-bot-coordinator.ts --update",
     "prepublishOnly": "bun run build:web"
   },
   "devDependencies": {

package/scripts/generate-bot-coordinator.ts

@@ -0,0 +1,397 @@
+#!/usr/bin/env bun
+/**
+ * Auto-generate PPMBot coordinator identity from Commander.js CLI source.
+ *
+ * Parses src/index.ts + src/cli/commands/*.ts to extract all commands,
+ * descriptions, options, and arguments. Produces coordinator.md content
+ * with full CLI reference, decision framework, and safety rules.
+ *
+ * Usage:
+ *   bun scripts/generate-bot-coordinator.ts              # print to stdout
+ *   bun scripts/generate-bot-coordinator.ts --update      # write coordinator.md + update source
+ *   bun scripts/generate-bot-coordinator.ts --write-md    # only write ~/.ppm/bot/coordinator.md
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+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");
+
+// ── Types ──────────────────────────────────────────────────────────────
+
+interface CliOption {
+  flags: string;
+  description: string;
+  defaultValue?: string;
+  required?: boolean;
+}
+
+interface CliCommand {
+  /** Full display name including parent path, e.g. "branch create" */
+  displayName: string;
+  description: string;
+  args: string[];
+  options: CliOption[];
+}
+
+interface CommandGroup {
+  name: string;
+  description: string;
+  commands: CliCommand[];
+}
+
+// ── Parsing ────────────────────────────────────────────────────────────
+
+/** Extract first quoted string from a regex match, handling mixed quote types */
+function extractQuoted(line: string, after: string): string | null {
+  const idx = line.indexOf(after);
+  if (idx === -1) return null;
+  const rest = line.slice(idx + after.length);
+
+  // Match opening quote, then capture until same closing quote
+  const m = rest.match(/["'`]((?:[^"'`\\]|\\.)*)["'`]/);
+  return m ? m[1]! : null;
+}
+
+/** Extract string argument from .description("...") — handles embedded quotes */
+function extractDescription(line: string): string | null {
+  // Try specific patterns: .description("..."), .description('...')
+  const dblMatch = line.match(/\.description\(\s*"([^"]*)"\s*\)/);
+  if (dblMatch) return dblMatch[1]!;
+
+  const sglMatch = line.match(/\.description\(\s*'([^']*)'\s*\)/);
+  if (sglMatch) return sglMatch[1]!;
+
+  const btMatch = line.match(/\.description\(\s*`([^`]*)`\s*\)/);
+  if (btMatch) return btMatch[1]!;
+
+  return null;
+}
+
+/**
+ * Parse a Commander.js source file into commands.
+ * Tracks variable assignments to resolve nested groups:
+ *   const branch = git.command("branch")  →  branch.command("create") is "branch create"
+ *
+ * Handles multi-line chaining where receiver is on previous line:
+ *   branch
+ *     .command("create <name>")
+ */
+function parseFile(filePath: string): CliCommand[] {
+  const src = readFileSync(filePath, "utf-8");
+  const lines = src.split("\n");
+  const commands: CliCommand[] = [];
+
+  // Track variable → parent path mapping
+  // e.g. "git" → "", "branch" → "branch", "mem" → "memory"
+  const varParent = new Map<string, string>();
+
+  // Track function parameters as potential receivers: function xxx(param: Command)
+  for (const line of lines) {
+    const funcParamMatch = line.match(
+      /function\s+\w+\(\s*(\w+)\s*:\s*Command\s*\)/,
+    );
+    if (funcParamMatch) {
+      varParent.set(funcParamMatch[1]!, "");
+    }
+  }
+
+  /** Last standalone variable seen (for multi-line chaining: `branch\n  .command(...)`) */
+  let lastStandaloneVar = "";
+
+  let currentCmd: {
+    displayName: string;
+    description: string;
+    args: string[];
+    options: CliOption[];
+  } | null = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+
+    // Track standalone variable references (for multi-line chaining)
+    const standaloneMatch = line.match(/^\s+(\w+)\s*$/);
+    if (standaloneMatch) {
+      lastStandaloneVar = standaloneMatch[1]!;
+    }
+
+    // Detect variable assignment: const/let varName = something.command("name")
+    const assignMatch = line.match(
+      /(?:const|let)\s+(\w+)\s*=\s*(\w+)\.command\(\s*["'`](\w+)["'`]\s*\)/,
+    );
+    if (assignMatch) {
+      const varName = assignMatch[1]!;
+      const receiver = assignMatch[2]!;
+      const cmdName = assignMatch[3]!;
+
+      // If this creates a known CLI group (git, bot, etc.), its path stays ""
+      // because formatCommand already prepends "ppm <group>"
+      if (cmdName in GROUP_MAP) {
+        varParent.set(varName, "");
+      } else {
+        const parentPath = varParent.get(receiver);
+        if (parentPath !== undefined) {
+          varParent.set(varName, parentPath ? `${parentPath} ${cmdName}` : cmdName);
+        } else {
+          varParent.set(varName, "");
+        }
+      }
+      continue;
+    }
+
+    // Detect chained .command("name") — not an assignment
+    const cmdMatch = line.match(/\.command\(\s*["'`]([^"'`]+)["'`]\s*\)/);
+    if (cmdMatch) {
+      // Save previous command
+      if (currentCmd) {
+        commands.push({ ...currentCmd });
+      }
+
+      const fullArg = cmdMatch[1]!;
+      const parts = fullArg.split(/\s+/);
+      const name = parts[0]!;
+      const args = parts.slice(1);
+
+      // Determine receiver: same line or previous line (multi-line chaining)
+      const sameLineReceiver = line.match(/(\w+)\.command\(/);
+      let receiver = sameLineReceiver ? sameLineReceiver[1]! : "";
+
+      // If receiver looks like a keyword (not a variable), try lastStandaloneVar
+      if (!receiver || receiver === "command") {
+        // .command() at start of line → look at previous non-empty line
+        receiver = lastStandaloneVar;
+      }
+
+      const parentPath = varParent.get(receiver) ?? "";
+      const displayName = parentPath ? `${parentPath} ${name}` : name;
+
+      currentCmd = { displayName, description: "", args, options: [] };
+      lastStandaloneVar = "";
+      continue;
+    }
+
+    if (!currentCmd) continue;
+
+    // Description
+    const desc = extractDescription(line);
+    if (desc !== null && line.includes(".description(")) {
+      currentCmd.description = desc;
+    }
+
+    // Option: .option("flags", "desc", "default?")
+    const optMatch = line.match(
+      /\.option\(\s*["'`]([^"'`]+)["'`]\s*,\s*["'`]([^"'`]+)["'`](?:\s*,\s*["'`]([^"'`]+)["'`])?\s*\)/,
+    );
+    if (optMatch) {
+      currentCmd.options.push({
+        flags: optMatch[1]!,
+        description: optMatch[2]!,
+        defaultValue: optMatch[3],
+      });
+    }
+
+    // Required option
+    const reqMatch = line.match(
+      /\.requiredOption\(\s*["'`]([^"'`]+)["'`]\s*,\s*["'`]([^"'`]+)["'`](?:\s*,\s*["'`]([^"'`]+)["'`])?\s*\)/,
+    );
+    if (reqMatch) {
+      currentCmd.options.push({
+        flags: reqMatch[1]!,
+        description: reqMatch[2]!,
+        defaultValue: reqMatch[3],
+        required: true,
+      });
+    }
+
+    // Argument: .argument("name")
+    const argMatch = line.match(/\.argument\(\s*["'`]([^"'`]+)["'`]/);
+    if (argMatch) {
+      currentCmd.args.push(argMatch[1]!);
+    }
+  }
+
+  // Push last command
+  if (currentCmd) {
+    commands.push({ ...currentCmd });
+  }
+
+  return commands;
+}
+
+/** Known command groups with their source files */
+const GROUP_MAP: Record<string, { description: string; file: string }> = {
+  projects: { description: "Manage registered projects", file: "projects.ts" },
+  config: { description: "Configuration management", file: "config-cmd.ts" },
+  git: { description: "Git operations for a project", file: "git-cmd.ts" },
+  chat: { description: "AI chat sessions", file: "chat-cmd.ts" },
+  db: { description: "Database connections & queries", file: "db-cmd.ts" },
+  autostart: { description: "Auto-start on boot", file: "autostart.ts" },
+  cloud: { description: "PPM Cloud — device registry + tunnel", file: "cloud.ts" },
+  ext: { description: "Manage PPM extensions", file: "ext-cmd.ts" },
+  bot: { description: "PPMBot coordinator utilities", file: "bot-cmd.ts" },
+};
+
+function buildGroups(): CommandGroup[] {
+  const groups: CommandGroup[] = [];
+
+  // Top-level commands from index.ts
+  const indexCmds = parseFile(INDEX_PATH);
+  const groupNames = new Set(Object.keys(GROUP_MAP));
+  const topLevel = indexCmds.filter((c) => !groupNames.has(c.displayName));
+
+  if (topLevel.length > 0) {
+    groups.push({
+      name: "core",
+      description: "Server & system management",
+      commands: topLevel,
+    });
+  }
+
+  // Sub-command groups from individual files
+  for (const [groupName, info] of Object.entries(GROUP_MAP)) {
+    const filePath = join(CMD_DIR, info.file);
+    if (!existsSync(filePath)) continue;
+
+    const cmds = parseFile(filePath);
+
+    // Filter out the group parent command and pure sub-group declarations
+    // (e.g. "branch" with no description = just a group container)
+    const subCmds = cmds.filter((c) => {
+      if (c.displayName === groupName) return false;
+      // Skip pure group containers (no description, no args)
+      if (!c.description && c.args.length === 0 && c.options.length === 0) return false;
+      return true;
+    });
+
+    groups.push({
+      name: groupName,
+      description: info.description,
+      commands: subCmds,
+    });
+  }
+
+  return groups;
+}
+
+// ── Output Generation ──────────────────────────────────────────────────
+
+function formatOption(opt: CliOption): string {
+  const req = opt.required ? " (required)" : "";
+  const def = opt.defaultValue ? ` [default: ${opt.defaultValue}]` : "";
+  return `  ${opt.flags} — ${opt.description}${req}${def}`;
+}
+
+function formatCommand(group: string, cmd: CliCommand): string {
+  const args = cmd.args.length > 0 ? " " + cmd.args.join(" ") : "";
+  const prefix = group === "core" ? "ppm" : `ppm ${group}`;
+  let line = `${prefix} ${cmd.displayName}${args}`;
+  if (cmd.description) line += `\n  ${cmd.description}`;
+  if (cmd.options.length > 0) {
+    line += "\n" + cmd.options.map(formatOption).join("\n");
+  }
+  return line;
+}
+
+/** Generate CLI-only reference (for cli-reference.md) */
+function generateCliReference(groups: CommandGroup[]): string {
+  const sections: string[] = [];
+  sections.push(`# PPM CLI Reference`);
+
+  for (const group of groups) {
+    const heading = group.name === "core"
+      ? `## Core Commands (${group.description})`
+      : `## ppm ${group.name} — ${group.description}`;
+    sections.push(heading);
+
+    const cmdLines = group.commands.map((c) => formatCommand(group.name, c));
+    sections.push("```");
+    sections.push(cmdLines.join("\n\n"));
+    sections.push("```");
+  }
+
+  sections.push(`
+## 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`);
+
+  return sections.join("\n");
+}
+
+// ── Source Code Update ────────────────────────────────────────────────
+
+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 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_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_CLI_REFERENCE");
+    process.exit(1);
+  }
+
+  const updated = src.slice(0, afterStart) + escaped + src.slice(endIdx);
+  writeFileSync(CLI_DEFAULT_PATH, updated);
+  console.log(`Updated: ${CLI_DEFAULT_PATH}`);
+}
+
+function writeCliReferenceMd(cliRef: string): void {
+  const dir = join(homedir(), ".ppm", "bot");
+  mkdirSync(dir, { recursive: true });
+  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 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")) {
+  writeCliReferenceMd(cliRef);
+} else {
+  // Default: stdout
+  console.log(cliRef);
+}

package/src/cli/commands/cloud.ts

@@ -28,7 +28,21 @@ export function registerCloudCommands(program: Command): void {
       const existing = getCloudAuth();
       if (existing) {
         console.log(`  Already logged in as ${existing.email}`);
-        console.log(`  Run 'ppm cloud logout' to switch accounts.\n`);
+
+        // Auto-link if not yet linked
+        const { getCloudDevice, linkDevice } = await import("../../services/cloud.service.ts");
+        if (!getCloudDevice()) {
+          try {
+            const device = await linkDevice();
+            console.log(`  ✓  Machine linked: ${device.name}\n`);
+          } catch (linkErr: unknown) {
+            const linkMsg = linkErr instanceof Error ? linkErr.message : String(linkErr);
+            console.warn(`  ⚠  Auto-link failed: ${linkMsg}`);
+          }
+        } else {
+          console.log(`  Run 'ppm cloud logout' to switch accounts.`);
+        }
+        console.log();
         return;
       }
 
@@ -51,8 +65,19 @@ export function registerCloudCommands(program: Command): void {
           }
         }
 
-        console.log(`\n  ✓  Logged in as ${auth.email}\n`);
-        console.log(`  Next: run 'ppm cloud link' to register this machine.\n`);
+        console.log(`\n  ✓  Logged in as ${auth.email}`);
+
+        // Auto-link device after login
+        try {
+          const { linkDevice } = await import("../../services/cloud.service.ts");
+          const device = await linkDevice();
+          console.log(`  ✓  Machine linked: ${device.name}`);
+        } catch (linkErr: unknown) {
+          const linkMsg = linkErr instanceof Error ? linkErr.message : String(linkErr);
+          console.warn(`  ⚠  Auto-link failed: ${linkMsg}`);
+          console.log(`  Run 'ppm cloud link' manually to register this machine.`);
+        }
+        console.log();
       } catch (err: unknown) {
         const msg = err instanceof Error ? err.message : String(err);
         console.error(`  ✗  Login failed: ${msg}\n`);
@@ -64,17 +89,28 @@ export function registerCloudCommands(program: Command): void {
     .command("logout")
     .description("Sign out from PPM Cloud")
     .action(async () => {
-      const { removeCloudAuth, getCloudAuth } = await import(
+      const { removeCloudAuth, getCloudAuth, unlinkDevice, getCloudDevice } = await import(
         "../../services/cloud.service.ts"
       );
 
       const auth = getCloudAuth();
-      removeCloudAuth();
-      if (auth) {
-        console.log(`  ✓  Logged out (was: ${auth.email})\n`);
-      } else {
+      if (!auth) {
         console.log(`  Not logged in.\n`);
+        return;
+      }
+
+      // Auto-unlink device before removing auth
+      if (getCloudDevice()) {
+        try {
+          await unlinkDevice();
+          console.log(`  ✓  Machine unlinked`);
+        } catch {
+          // Non-blocking — still logout even if unlink fails
+        }
       }
+
+      removeCloudAuth();
+      console.log(`  ✓  Logged out (was: ${auth.email})\n`);
     });
 
   cmd

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,57 +11,66 @@ 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";
 
 export const DEFAULT_COORDINATOR_IDENTITY = `# PPMBot — AI Project Coordinator
 
-You are PPMBot, a personal AI project coordinator and team leader. You communicate with users via Telegram.
+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
-- Act as a team leader coordinating work across multiple projects
 
 ## 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
-3. Is this about PPM config or bot management? → Handle directly
-4. Ambiguous project? → Ask user to clarify
-
-## Coordination Tools (via Bash)
-
-### Delegate a task to a project
-ppm bot delegate --chat <chatId> --project <name> --prompt "<enriched task description>"
-Returns task ID. 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
+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\` 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
+- \`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 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 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
 
 ## 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 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");
 
@@ -75,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 {

package/src/services/supervisor.ts

@@ -65,6 +65,8 @@ let tunnelProbeTimer: ReturnType<typeof setInterval> | null = null;
 let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
 let upgradeCheckTimer: ReturnType<typeof setInterval> | null = null;
 let upgradeDelayTimer: ReturnType<typeof setTimeout> | null = null;
+let cloudMonitorTimer: ReturnType<typeof setInterval> | null = null;
+let cloudConnected = false; // tracks whether we've initiated a cloud WS connection
 
 // Saved at startup for self-replace
 let originalArgv: string[] = [];
@@ -488,11 +490,11 @@ async function notifyStateChange(from: string, to: string, reason: string) {
 }
 
 /** Connect supervisor to Cloud via WebSocket (if device is linked) */
-async function connectCloud(opts: { port: number }, serverArgs: string[], logFd: number) {
+async function connectCloud(opts: { port: number }, serverArgs: string[], logFd: number): Promise<boolean> {
   try {
     const { getCloudDevice } = await import("./cloud.service.ts");
     const device = getCloudDevice();
-    if (!device) return; // not linked to cloud
+    if (!device) return false; // not linked to cloud
 
     const { connect, onCommand } = await import("./cloud-ws.service.ts");
     const { VERSION } = await import("../version.ts");
@@ -609,11 +611,48 @@ async function connectCloud(opts: { port: number }, serverArgs: string[], logFd:
           sendResult(false, `Unknown action: ${cmd.action}`);
       }
     });
+    cloudConnected = true;
+    return true;
   } catch (e) {
     log("WARN", `Cloud WS setup failed: ${e}`);
+    return false;
   }
 }
 
+/** Periodically check if cloud-device.json appeared/disappeared and connect/disconnect */
+function startCloudMonitor(opts: { port: number }, serverArgs: string[], logFd: number) {
+  const CLOUD_MONITOR_INTERVAL_MS = 60_000; // check every 60s
+  cloudMonitorTimer = setInterval(async () => {
+    if (shuttingDown) return;
+    try {
+      const { getCloudDevice } = await import("./cloud.service.ts");
+      const device = getCloudDevice();
+      const { isConnected } = await import("./cloud-ws.service.ts");
+
+      if (device && !cloudConnected) {
+        // Device linked but WS not connected — connect now
+        log("INFO", "Cloud monitor: device linked detected, connecting to cloud");
+        await connectCloud(opts, serverArgs, logFd);
+      } else if (device && cloudConnected && !isConnected()) {
+        // Device linked, we attempted connection but WS is dead — reconnect
+        log("WARN", "Cloud monitor: WS disconnected, reconnecting");
+        const { disconnect } = await import("./cloud-ws.service.ts");
+        disconnect();
+        cloudConnected = false;
+        await connectCloud(opts, serverArgs, logFd);
+      } else if (!device && cloudConnected) {
+        // Device unlinked — disconnect
+        log("INFO", "Cloud monitor: device unlinked, disconnecting from cloud");
+        const { disconnect } = await import("./cloud-ws.service.ts");
+        disconnect();
+        cloudConnected = false;
+      }
+    } catch (e) {
+      log("WARN", `Cloud monitor error: ${e}`);
+    }
+  }, CLOUD_MONITOR_INTERVAL_MS);
+}
+
 // ─── Soft stop (server only, supervisor stays alive) ──────────────────
 let _softStopRunning = false;
 export async function softStop() {
@@ -674,6 +713,7 @@ export function shutdown() {
   if (heartbeatTimer) clearInterval(heartbeatTimer);
   if (upgradeCheckTimer) clearInterval(upgradeCheckTimer);
   if (upgradeDelayTimer) clearTimeout(upgradeDelayTimer);
+  if (cloudMonitorTimer) clearInterval(cloudMonitorTimer);
 
   if (serverChild) { try { serverChild.kill(); } catch {} }
   if (tunnelChild) { try { tunnelChild.kill(); } catch {} }
@@ -801,8 +841,9 @@ export async function runSupervisor(opts: {
     }, 1000);
   }
 
-  // Connect to Cloud via WebSocket (if device is linked)
+  // Connect to Cloud via WebSocket (if device is linked) + start monitoring
   connectCloud(opts, serverArgs, logFd);
+  startCloudMonitor(opts, serverArgs, logFd);
 
   // Spawn server + tunnel in parallel
   const promises: Promise<void>[] = [spawnServer(serverArgs, logFd)];