postgresai 0.16.0-dev.5 → 0.16.0-dev.6

package/bin/postgres-ai.ts

@@ -5424,7 +5424,7 @@ interface JoeCliOpts {
 // ============================================================================
 // DBLab companion command surface (Joe API v2 · SPEC §8)
 //
-// `pgai clone|branch|snapshot …` proxy the SAME Platform DBLab API the Console
+// `pgai dblab clone|branch|snapshot …` proxy the SAME Platform DBLab API the Console
 // already drives (v1.dblab_api_call). Every verb is `--project <id|alias>`
 // scoped: the project's single DBLab instance is resolved server-side listing,
 // then the verb is proxied. Destructive verbs (clone reset/destroy, branch
@@ -5465,7 +5465,7 @@ function printJoeOutcome(command: JoeCommand, outcome: ExecuteJoeOutcome, json:
             status: outcome.status,
             session_id: outcome.sessionId,
             budget_expired: true,
-            resume: `pgai result ${outcome.commandId}`,
+            resume: `pgai joe result ${outcome.commandId}`,
           },
           null,
           2
@@ -5473,7 +5473,7 @@ function printJoeOutcome(command: JoeCommand, outcome: ExecuteJoeOutcome, json:
       );
     } else {
       console.log(
-        `submitted ${outcome.commandId} · ${outcome.status} · budget ${budgetSeconds}s reached — resume:  pgai result ${outcome.commandId}`
+        `submitted ${outcome.commandId} · ${outcome.status} · budget ${budgetSeconds}s reached — resume:  pgai joe result ${outcome.commandId}`
       );
     }
     return;
@@ -5501,7 +5501,7 @@ function printJoeOutcome(command: JoeCommand, outcome: ExecuteJoeOutcome, json:
   // Server-side timed_out (the dispatcher gave up). The genuine reply may still
   // land; suggest a resume, but signal failure with a non-zero exit.
   console.error(
-    `command ${outcome.commandId} timed out on the server — resume:  pgai result ${outcome.commandId}`
+    `command ${outcome.commandId} timed out on the server — resume:  pgai joe result ${outcome.commandId}`
   );
   process.exitCode = 1;
 }
@@ -5564,8 +5564,17 @@ function withJoeOptions(cmd: import("commander").Command): import("commander").C
     .option("--json", "output raw JSON");
 }
 
+// ---------------------------------------------------------------------------
+// Joe command group — every Joe verb lives under `pgai joe <verb>` (grouped CLI,
+// USER-AUTHORIZED restructure). The MCP tool names stay flat/unchanged; only the
+// CLI invocation path is grouped. `projects` stays top-level (org-level, SPEC §6).
+// ---------------------------------------------------------------------------
+const joe = program
+  .command("joe")
+  .description("Joe API v2 — plan/EXPLAIN/exec queries on ephemeral DBLab clones");
+
 withJoeOptions(
-  program
+  joe
     .command("plan <sql>")
     .description("plan a query (EXPLAIN, plan-only — no execution; the fast/safe default)")
 ).action(async (sql: string, opts: JoeCliOpts) => {
@@ -5573,7 +5582,7 @@ withJoeOptions(
 });
 
 withJoeOptions(
-  program
+  joe
     .command("explain <sql>")
     .description("EXPLAIN ANALYZE a query (EXECUTES on the hardened, ephemeral clone)")
 ).action(async (sql: string, opts: JoeCliOpts) => {
@@ -5581,7 +5590,7 @@ withJoeOptions(
 });
 
 withJoeOptions(
-  program
+  joe
     .command("exec <sql>")
     .description("run arbitrary DDL/DML on the clone (e.g. create index, analyze)")
 ).action(async (sql: string, opts: JoeCliOpts) => {
@@ -5589,7 +5598,7 @@ withJoeOptions(
 });
 
 withJoeOptions(
-  program
+  joe
     .command("hypo <indexSql>")
     .description("HypoPG hypothetical index + re-plan (no real index, no data change)")
     .requiredOption("--query <sql>", "target query the hypothetical index is evaluated against")
@@ -5598,7 +5607,7 @@ withJoeOptions(
 });
 
 withJoeOptions(
-  program
+  joe
     .command("activity")
     .description("running-activity snapshot (pg_stat_activity; query text redacted)")
 ).action(async (opts: JoeCliOpts) => {
@@ -5606,7 +5615,7 @@ withJoeOptions(
 });
 
 withJoeOptions(
-  program
+  joe
     .command("terminate <pid>")
     .description("pg_terminate_backend(pid) on the clone")
 ).action(async (pid: string, opts: JoeCliOpts) => {
@@ -5620,7 +5629,7 @@ withJoeOptions(
 });
 
 withJoeOptions(
-  program
+  joe
     .command("reset")
     .description("reset/recreate the session's thin clone")
 ).action(async (opts: JoeCliOpts) => {
@@ -5628,7 +5637,7 @@ withJoeOptions(
 });
 
 withJoeOptions(
-  program
+  joe
     .command("describe <object>")
     .description("\\d-family schema/relation/index metadata")
     .option("--variant <variant>", "\\d-family variant (e.g. \\d+, \\di, \\dt)")
@@ -5699,9 +5708,18 @@ async function resolveDblabTarget(
   return { apiKey, apiBaseUrl, orgId, instanceId };
 }
 
+// ---------------------------------------------------------------------------
+// DBLab command group — every DBLab verb lives under
+// `pgai dblab <clone|branch|snapshot> …` (grouped CLI, USER-AUTHORIZED restructure).
+// MCP tool names (clone_create/…) stay flat/unchanged; only the CLI path is grouped.
+// ---------------------------------------------------------------------------
+const dblab = program
+  .command("dblab")
+  .description("DBLab thin-clone / branch / snapshot management (proxies the Platform DBLab API)");
+
 // ---- clone ----------------------------------------------------------------
 
-const clone = program.command("clone").description("DBLab thin-clone management (proxies the Platform DBLab API)");
+const clone = dblab.command("clone").description("DBLab thin-clone management (proxies the Platform DBLab API)");
 
 clone
   .command("create")
@@ -5735,8 +5753,9 @@ clone
     }
   });
 
-// Resume / inspect a previously submitted command by id.
-program
+// Resume / inspect a previously submitted command by id. Part of the `joe` group
+// (`pgai joe status <commandId>`) — distinct from `pgai dblab clone status <cloneId>`.
+joe
   .command("status <commandId>")
   .description("show a Joe command's status (metadata only)")
   .option("--debug", "enable debug output")
@@ -5782,7 +5801,7 @@ clone
     }
   });
 
-program
+joe
   .command("result <commandId>")
   .description("fetch a Joe command's result by id (resume a timed-out one-shot)")
   .option("--debug", "enable debug output")
@@ -5881,7 +5900,7 @@ clone
 
 // ---- branch ---------------------------------------------------------------
 
-const branch = program.command("branch").description("DBLab branch management (proxies the Platform DBLab API)");
+const branch = dblab.command("branch").description("DBLab branch management (proxies the Platform DBLab API)");
 
 branch
   .command("list")
@@ -5961,7 +5980,7 @@ branch
 
 // ---- snapshot -------------------------------------------------------------
 
-const snapshot = program.command("snapshot").description("DBLab snapshot management (proxies the Platform DBLab API)");
+const snapshot = dblab.command("snapshot").description("DBLab snapshot management (proxies the Platform DBLab API)");
 
 snapshot
   .command("list")

package/dist/bin/postgres-ai.js

@@ -13425,7 +13425,7 @@ var {
 // package.json
 var package_default = {
   name: "postgresai",
-  version: "0.16.0-dev.5",
+  version: "0.16.0-dev.6",
   description: "postgres_ai CLI",
   license: "Apache-2.0",
   private: false,
@@ -16256,7 +16256,7 @@ var Result = import_lib.default.Result;
 var TypeOverrides = import_lib.default.TypeOverrides;
 var defaults = import_lib.default.defaults;
 // package.json
-var version = "0.16.0-dev.5";
+var version = "0.16.0-dev.6";
 var package_default2 = {
   name: "postgresai",
   version,
@@ -25145,7 +25145,7 @@ async function runJoeTool(params) {
     session_id: outcome.sessionId,
     status: outcome.status,
     budget_expired: outcome.budgetExpired,
-    resume: outcome.budgetExpired ? `pgai result ${outcome.commandId}` : undefined,
+    resume: outcome.budgetExpired ? `pgai joe result ${outcome.commandId}` : undefined,
     result: outcome.result
   };
   const isError = outcome.status === "error" || outcome.status === "timed_out";
@@ -39715,10 +39715,10 @@ function printJoeOutcome(command, outcome, json3) {
         status: outcome.status,
         session_id: outcome.sessionId,
         budget_expired: true,
-        resume: `pgai result ${outcome.commandId}`
+        resume: `pgai joe result ${outcome.commandId}`
       }, null, 2));
     } else {
-      console.log(`submitted ${outcome.commandId} \xB7 ${outcome.status} \xB7 budget ${budgetSeconds}s reached \u2014 resume:  pgai result ${outcome.commandId}`);
+      console.log(`submitted ${outcome.commandId} \xB7 ${outcome.status} \xB7 budget ${budgetSeconds}s reached \u2014 resume:  pgai joe result ${outcome.commandId}`);
     }
     return;
   }
@@ -39740,7 +39740,7 @@ function printJoeOutcome(command, outcome, json3) {
     process.exitCode = 1;
     return;
   }
-  console.error(`command ${outcome.commandId} timed out on the server \u2014 resume:  pgai result ${outcome.commandId}`);
+  console.error(`command ${outcome.commandId} timed out on the server \u2014 resume:  pgai joe result ${outcome.commandId}`);
   process.exitCode = 1;
 }
 async function runJoeCli(command, sql, args, opts) {
@@ -39784,22 +39784,23 @@ async function runJoeCli(command, sql, args, opts) {
 function withJoeOptions(cmd) {
   return cmd.option("--project <id|alias>", "target project by numeric id OR alias/name").option("--session <id>", "run on a specific session's clone").option("--new-session", "start a fresh session/clone (null session)").option("--budget <seconds>", "one-shot poll budget in seconds (default 25)", (v) => parseInt(v, 10)).option("--debug", "enable debug output").option("--json", "output raw JSON");
 }
-withJoeOptions(program2.command("plan <sql>").description("plan a query (EXPLAIN, plan-only \u2014 no execution; the fast/safe default)")).action(async (sql, opts) => {
+var joe = program2.command("joe").description("Joe API v2 \u2014 plan/EXPLAIN/exec queries on ephemeral DBLab clones");
+withJoeOptions(joe.command("plan <sql>").description("plan a query (EXPLAIN, plan-only \u2014 no execution; the fast/safe default)")).action(async (sql, opts) => {
   await runJoeCli("plan", sql, null, opts);
 });
-withJoeOptions(program2.command("explain <sql>").description("EXPLAIN ANALYZE a query (EXECUTES on the hardened, ephemeral clone)")).action(async (sql, opts) => {
+withJoeOptions(joe.command("explain <sql>").description("EXPLAIN ANALYZE a query (EXECUTES on the hardened, ephemeral clone)")).action(async (sql, opts) => {
   await runJoeCli("explain", sql, null, opts);
 });
-withJoeOptions(program2.command("exec <sql>").description("run arbitrary DDL/DML on the clone (e.g. create index, analyze)")).action(async (sql, opts) => {
+withJoeOptions(joe.command("exec <sql>").description("run arbitrary DDL/DML on the clone (e.g. create index, analyze)")).action(async (sql, opts) => {
   await runJoeCli("exec", sql, null, opts);
 });
-withJoeOptions(program2.command("hypo <indexSql>").description("HypoPG hypothetical index + re-plan (no real index, no data change)").requiredOption("--query <sql>", "target query the hypothetical index is evaluated against")).action(async (indexSql, opts) => {
+withJoeOptions(joe.command("hypo <indexSql>").description("HypoPG hypothetical index + re-plan (no real index, no data change)").requiredOption("--query <sql>", "target query the hypothetical index is evaluated against")).action(async (indexSql, opts) => {
   await runJoeCli("hypo", indexSql, { query: opts.query }, opts);
 });
-withJoeOptions(program2.command("activity").description("running-activity snapshot (pg_stat_activity; query text redacted)")).action(async (opts) => {
+withJoeOptions(joe.command("activity").description("running-activity snapshot (pg_stat_activity; query text redacted)")).action(async (opts) => {
   await runJoeCli("activity", null, null, opts);
 });
-withJoeOptions(program2.command("terminate <pid>").description("pg_terminate_backend(pid) on the clone")).action(async (pid, opts) => {
+withJoeOptions(joe.command("terminate <pid>").description("pg_terminate_backend(pid) on the clone")).action(async (pid, opts) => {
   const pidNum = parseInt(pid, 10);
   if (Number.isNaN(pidNum)) {
     console.error("pid must be a number");
@@ -39808,10 +39809,10 @@ withJoeOptions(program2.command("terminate <pid>").description("pg_terminate_bac
   }
   await runJoeCli("terminate", null, { pid: pidNum }, opts);
 });
-withJoeOptions(program2.command("reset").description("reset/recreate the session's thin clone")).action(async (opts) => {
+withJoeOptions(joe.command("reset").description("reset/recreate the session's thin clone")).action(async (opts) => {
   await runJoeCli("reset", null, null, opts);
 });
-withJoeOptions(program2.command("describe <object>").description("\\d-family schema/relation/index metadata").option("--variant <variant>", "\\d-family variant (e.g. \\d+, \\di, \\dt)")).action(async (object4, opts) => {
+withJoeOptions(joe.command("describe <object>").description("\\d-family schema/relation/index metadata").option("--variant <variant>", "\\d-family variant (e.g. \\d+, \\di, \\dt)")).action(async (object4, opts) => {
   const args = { object: object4 };
   if (opts.variant)
     args.variant = opts.variant;
@@ -39861,7 +39862,8 @@ async function resolveDblabTarget(project, debug) {
   const instanceId = await resolveDblabInstanceId2({ apiKey, apiBaseUrl, project: ref, orgId, debug });
   return { apiKey, apiBaseUrl, orgId, instanceId };
 }
-var clone2 = program2.command("clone").description("DBLab thin-clone management (proxies the Platform DBLab API)");
+var dblab = program2.command("dblab").description("DBLab thin-clone / branch / snapshot management (proxies the Platform DBLab API)");
+var clone2 = dblab.command("clone").description("DBLab thin-clone management (proxies the Platform DBLab API)");
 clone2.command("create").description("create a thin clone of the project's database").requiredOption("--project <id|alias>", "project id or alias").option("--branch <branch>", "branch to clone from").option("--snapshot <id>", "snapshot id to clone from").option("--id <id>", "clone id (DBLab generates one when omitted)").option("--db-user <user>", "clone DB user").option("--db-password <password>", "clone DB password").option("--protected", "protect the clone from auto-deletion").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (opts) => {
   try {
     const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
@@ -39883,7 +39885,7 @@ clone2.command("create").description("create a thin clone of the project's datab
     process.exitCode = 1;
   }
 });
-program2.command("status <commandId>").description("show a Joe command's status (metadata only)").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (commandId, opts) => {
+joe.command("status <commandId>").description("show a Joe command's status (metadata only)").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (commandId, opts) => {
   try {
     const rootOpts = program2.opts();
     const cfg = readConfig();
@@ -39916,7 +39918,7 @@ clone2.command("list").description("list the project's thin clones").requiredOpt
     process.exitCode = 1;
   }
 });
-program2.command("result <commandId>").description("fetch a Joe command's result by id (resume a timed-out one-shot)").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (commandId, opts) => {
+joe.command("result <commandId>").description("fetch a Joe command's result by id (resume a timed-out one-shot)").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (commandId, opts) => {
   try {
     const rootOpts = program2.opts();
     const cfg = readConfig();
@@ -39988,7 +39990,7 @@ clone2.command("destroy <cloneId>").description("destroy a clone (requires joe:a
     process.exitCode = 1;
   }
 });
-var branch = program2.command("branch").description("DBLab branch management (proxies the Platform DBLab API)");
+var branch = dblab.command("branch").description("DBLab branch management (proxies the Platform DBLab API)");
 branch.command("list").description("list the project's branches").requiredOption("--project <id|alias>", "project id or alias").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (opts) => {
   try {
     const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);
@@ -40037,7 +40039,7 @@ branch.command("log <name>").description("show a branch's snapshot log").require
     process.exitCode = 1;
   }
 });
-var snapshot = program2.command("snapshot").description("DBLab snapshot management (proxies the Platform DBLab API)");
+var snapshot = dblab.command("snapshot").description("DBLab snapshot management (proxies the Platform DBLab API)");
 snapshot.command("list").description("list the project's snapshots").requiredOption("--project <id|alias>", "project id or alias").option("--branch <branch>", "filter by branch").option("--dataset <dataset>", "filter by dataset").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (opts) => {
   try {
     const { apiKey, apiBaseUrl, instanceId } = await resolveDblabTarget(opts.project, !!opts.debug);

package/lib/joe.ts

@@ -496,7 +496,7 @@ const defaultSleep = (ms: number): Promise<void> => new Promise((r) => setTimeou
 /**
  * Submit a command then client-side poll status/result within the one-shot budget.
  * On a terminal state returns the result; on budget expiry returns a resume handle
- * (`budgetExpired: true`) so the caller can `pgai result <command_id>` later.
+ * (`budgetExpired: true`) so the caller can `pgai joe result <command_id>` later.
  */
 export async function runCommand(params: RunCommandParams): Promise<RunCommandOutcome> {
   const {

package/lib/mcp-server.ts

@@ -284,7 +284,7 @@ async function runJoeTool(params: RunJoeToolParams): Promise<McpToolResponse> {
     session_id: outcome.sessionId,
     status: outcome.status,
     budget_expired: outcome.budgetExpired,
-    resume: outcome.budgetExpired ? `pgai result ${outcome.commandId}` : undefined,
+    resume: outcome.budgetExpired ? `pgai joe result ${outcome.commandId}` : undefined,
     result: outcome.result,
   };
   const isError = outcome.status === "error" || outcome.status === "timed_out";
@@ -648,7 +648,7 @@ export async function handleToolCall(
     }
 
     // ---- DBLab companion tools (SPEC §8) --------------------------------
-    // Each mirrors the CLI `pgai clone|branch|snapshot …` verb 1:1: resolve the
+    // Each mirrors the CLI `pgai dblab clone|branch|snapshot …` verb 1:1: resolve the
     // project's single DBLab instance, then proxy the existing Platform DBLab
     // API (v1.dblab_api_call). Destructive verbs are `joe:admin`-gated backend
     // side (a PT403 surfaces as an isError response via the outer catch).
@@ -1058,7 +1058,7 @@ export async function startMcpServer(rootOpts?: RootOptsLike, extra?: { debug?:
         },
         ...joeToolDefinitions(),
         // DBLab companion tools (SPEC §8) — proxy the existing Platform DBLab API
-        // (v1.dblab_api_call) the Console drives; mirror `pgai clone|branch|snapshot`.
+        // (v1.dblab_api_call) the Console drives; mirror `pgai dblab clone|branch|snapshot`.
         // `project` (id or alias) resolves the project's single DBLab instance.
         {
           name: "clone_create",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postgresai",
-  "version": "0.16.0-dev.5",
+  "version": "0.16.0-dev.6",
   "description": "postgres_ai CLI",
   "license": "Apache-2.0",
   "private": false,

package/test/dblab.cli.test.ts

@@ -93,17 +93,24 @@ async function startFakeApi(projects?: unknown[]) {
   };
 }
 
-describe("CLI DBLab companion command groups", () => {
-  test("top-level help lists clone, branch, and snapshot groups", () => {
+describe("CLI DBLab companion command groups (grouped under `pgai dblab …`)", () => {
+  test("top-level help lists the dblab group", () => {
     const r = runCli(["--help"], isolatedEnv());
     const out = `${r.stdout}\n${r.stderr}`;
+    expect(out).toContain("dblab");
+  });
+
+  test("dblab help exposes the clone, branch, and snapshot groups", () => {
+    const r = runCli(["dblab", "--help"], isolatedEnv());
+    expect(r.status).toBe(0);
+    const out = `${r.stdout}\n${r.stderr}`;
     expect(out).toContain("clone");
     expect(out).toContain("branch");
     expect(out).toContain("snapshot");
   });
 
   test("clone help exposes create/list/status/reset/destroy", () => {
-    const r = runCli(["clone", "--help"], isolatedEnv());
+    const r = runCli(["dblab", "clone", "--help"], isolatedEnv());
     expect(r.status).toBe(0);
     const out = `${r.stdout}\n${r.stderr}`;
     expect(out).toContain("create");
@@ -114,7 +121,7 @@ describe("CLI DBLab companion command groups", () => {
   });
 
   test("branch help exposes list/create/delete/log", () => {
-    const r = runCli(["branch", "--help"], isolatedEnv());
+    const r = runCli(["dblab", "branch", "--help"], isolatedEnv());
     expect(r.status).toBe(0);
     const out = `${r.stdout}\n${r.stderr}`;
     expect(out).toContain("list");
@@ -124,7 +131,7 @@ describe("CLI DBLab companion command groups", () => {
   });
 
   test("snapshot help exposes list/create/destroy", () => {
-    const r = runCli(["snapshot", "--help"], isolatedEnv());
+    const r = runCli(["dblab", "snapshot", "--help"], isolatedEnv());
     expect(r.status).toBe(0);
     const out = `${r.stdout}\n${r.stderr}`;
     expect(out).toContain("list");
@@ -133,13 +140,13 @@ describe("CLI DBLab companion command groups", () => {
   });
 
   test("clone create fails fast without an API key", () => {
-    const r = runCli(["clone", "create", "--project", "main-db"], isolatedEnv());
+    const r = runCli(["dblab", "clone", "create", "--project", "main-db"], isolatedEnv());
     expect(r.status).toBe(1);
     expect(`${r.stdout}\n${r.stderr}`).toContain("API key is required");
   });
 
   test("clone list without --project errors", () => {
-    const r = runCli(["clone", "list"], isolatedEnv({ PGAI_API_KEY: "test-key" }));
+    const r = runCli(["dblab", "clone", "list"], isolatedEnv({ PGAI_API_KEY: "test-key" }));
     expect(r.status).not.toBe(0);
     expect(`${r.stdout}\n${r.stderr}`.toLowerCase()).toContain("project");
   });
@@ -148,7 +155,7 @@ describe("CLI DBLab companion command groups", () => {
     const api = await startFakeApi();
     try {
       const r = await runCliAsync(
-        ["clone", "create", "--project", "main-db", "--json"],
+        ["dblab", "clone", "create", "--project", "main-db", "--json"],
         isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(0);
@@ -170,7 +177,7 @@ describe("CLI DBLab companion command groups", () => {
     const api = await startFakeApi();
     try {
       const r = await runCliAsync(
-        ["clone", "create", "--project", "main-db", "--branch", "feature-idx", "--snapshot", "s-9", "--protected", "--json"],
+        ["dblab", "clone", "create", "--project", "main-db", "--branch", "feature-idx", "--snapshot", "s-9", "--protected", "--json"],
         isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(0);
@@ -185,7 +192,7 @@ describe("CLI DBLab companion command groups", () => {
     const api = await startFakeApi();
     try {
       const r = await runCliAsync(
-        ["clone", "reset", "c-8f21", "--project", "main-db", "--json"],
+        ["dblab", "clone", "reset", "c-8f21", "--project", "main-db", "--json"],
         isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(0);
@@ -202,7 +209,7 @@ describe("CLI DBLab companion command groups", () => {
     const api = await startFakeApi();
     try {
       const r = await runCliAsync(
-        ["clone", "destroy", "c-8f21", "--project", "12", "--json"],
+        ["dblab", "clone", "destroy", "c-8f21", "--project", "12", "--json"],
         isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(0);
@@ -219,7 +226,7 @@ describe("CLI DBLab companion command groups", () => {
     const api = await startFakeApi();
     try {
       const r = await runCliAsync(
-        ["branch", "create", "feature-idx", "--project", "main-db", "--snapshot", "latest", "--json"],
+        ["dblab", "branch", "create", "feature-idx", "--project", "main-db", "--snapshot", "latest", "--json"],
         isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(0);
@@ -236,7 +243,7 @@ describe("CLI DBLab companion command groups", () => {
     const api = await startFakeApi();
     try {
       const r = await runCliAsync(
-        ["branch", "log", "feature-idx", "--project", "main-db", "--json"],
+        ["dblab", "branch", "log", "feature-idx", "--project", "main-db", "--json"],
         isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(0);
@@ -252,7 +259,7 @@ describe("CLI DBLab companion command groups", () => {
     const api = await startFakeApi();
     try {
       const r = await runCliAsync(
-        ["snapshot", "list", "--project", "main-db", "--json"],
+        ["dblab", "snapshot", "list", "--project", "main-db", "--json"],
         isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(0);
@@ -268,7 +275,7 @@ describe("CLI DBLab companion command groups", () => {
     const api = await startFakeApi();
     try {
       const r = await runCliAsync(
-        ["snapshot", "create", "--project", "main-db", "--clone", "c-8f21", "--message", "before idx", "--json"],
+        ["dblab", "snapshot", "create", "--project", "main-db", "--clone", "c-8f21", "--message", "before idx", "--json"],
         isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(0);
@@ -284,7 +291,7 @@ describe("CLI DBLab companion command groups", () => {
     const api = await startFakeApi();
     try {
       const r = await runCliAsync(
-        ["snapshot", "destroy", "s-1", "--project", "main-db", "--force", "--json"],
+        ["dblab", "snapshot", "destroy", "s-1", "--project", "main-db", "--force", "--json"],
         isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(0);
@@ -300,7 +307,7 @@ describe("CLI DBLab companion command groups", () => {
     const api = await startFakeApi();
     try {
       const r = await runCliAsync(
-        ["clone", "list", "--project", "does-not-exist"],
+        ["dblab", "clone", "list", "--project", "does-not-exist"],
         isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(1);
@@ -327,7 +334,7 @@ describe("CLI DBLab companion command groups", () => {
     try {
       const baseUrl = `http://${server.hostname}:${server.port}/api/general`;
       const r = await runCliAsync(
-        ["clone", "destroy", "c-1", "--project", "main-db"],
+        ["dblab", "clone", "destroy", "c-1", "--project", "main-db"],
         isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: baseUrl })
       );
       expect(r.status).toBe(1);

package/test/joe.cli.test.ts

@@ -126,11 +126,22 @@ function startFakeApi() {
   return { baseUrl, requests, stop: () => server.stop(true) };
 }
 
-describe("CLI Joe command surface", () => {
-  test("top-level help lists the Joe verbs and projects/result", () => {
+describe("CLI Joe command surface (grouped under `pgai joe …`)", () => {
+  test("top-level help lists the joe + dblab groups and top-level projects", () => {
     const r = runCli(["--help"], isolatedEnv());
     const out = `${r.stdout}\n${r.stderr}`;
-    for (const verb of ["plan", "explain", "exec", "hypo", "activity", "terminate", "reset", "describe", "projects", "result", "status"]) {
+    // Joe verbs are grouped under `joe`; DBLab verbs under `dblab`. `projects`
+    // stays top-level (org-level, not a Joe endpoint).
+    for (const group of ["joe", "dblab", "projects"]) {
+      expect(out).toContain(group);
+    }
+  });
+
+  test("pgai joe --help lists all the Joe verbs", () => {
+    const r = runCli(["joe", "--help"], isolatedEnv());
+    expect(r.status).toBe(0);
+    const out = `${r.stdout}\n${r.stderr}`;
+    for (const verb of ["plan", "explain", "exec", "hypo", "activity", "terminate", "reset", "describe", "result", "status"]) {
       expect(out).toContain(verb);
     }
   });
@@ -153,11 +164,11 @@ describe("CLI Joe command surface", () => {
     }
   });
 
-  test("pgai plan --project 12 submits command='plan' and prints the plan", async () => {
+  test("pgai joe plan --project 12 submits command='plan' and prints the plan", async () => {
     const api = startFakeApi();
     try {
       const r = await runCliAsync(
-        ["plan", "select * from users where email = 'x@acme.io'", "--project", "12"],
+        ["joe", "plan", "select * from users where email = 'x@acme.io'", "--project", "12"],
         isolatedEnv({ PGAI_API_KEY: "k", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(0);
@@ -174,11 +185,11 @@ describe("CLI Joe command surface", () => {
     }
   });
 
-  test("pgai plan --project main-db resolves the alias via projects_list", async () => {
+  test("pgai joe plan --project main-db resolves the alias via projects_list", async () => {
     const api = startFakeApi();
     try {
       const r = await runCliAsync(
-        ["plan", "select 1", "--project", "main-db"],
+        ["joe", "plan", "select 1", "--project", "main-db"],
         isolatedEnv({ PGAI_API_KEY: "k", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(0);
@@ -190,15 +201,15 @@ describe("CLI Joe command surface", () => {
     }
   });
 
-  test("optimize loop: plan then exec reuse the same session on one project", async () => {
+  test("optimize loop: joe plan then joe exec reuse the same session on one project", async () => {
     const api = startFakeApi();
     const env = isolatedEnv({ PGAI_API_KEY: "k", PGAI_API_BASE_URL: api.baseUrl });
     try {
       // First command starts a fresh session; the server hands back session 88.
-      const first = await runCliAsync(["plan", "select 1", "--project", "12", "--new-session"], env);
+      const first = await runCliAsync(["joe", "plan", "select 1", "--project", "12", "--new-session"], env);
       expect(first.status).toBe(0);
       // Second command auto-reuses the stored session (88) on the same project.
-      const second = await runCliAsync(["exec", "create index on users (email)", "--project", "12"], env);
+      const second = await runCliAsync(["joe", "exec", "create index on users (email)", "--project", "12"], env);
       expect(second.status).toBe(0);
       expect(second.stdout).toContain("CREATE INDEX");
 
@@ -215,21 +226,21 @@ describe("CLI Joe command surface", () => {
     }
   });
 
-  test("cold clone exceeds the budget -> resume handle (exit 0), then pgai result", async () => {
+  test("cold clone exceeds the budget -> resume handle (exit 0), then pgai joe result", async () => {
     const api = startFakeApi();
     const env = isolatedEnv({ PGAI_API_KEY: "k", PGAI_API_BASE_URL: api.baseUrl });
     try {
       // project 77 (COLD) stays `running`; --budget 0 forces immediate resume.
-      const r = await runCliAsync(["plan", "select 1", "--project", "77", "--budget", "0"], env);
+      const r = await runCliAsync(["joe", "plan", "select 1", "--project", "77", "--budget", "0"], env);
       expect(r.status).toBe(0);
       expect(r.stdout).toContain("resume:");
-      expect(r.stdout).toMatch(/pgai result \d+/);
+      expect(r.stdout).toMatch(/pgai joe result \d+/);
 
-      const match = r.stdout.match(/pgai result (\d+)/);
+      const match = r.stdout.match(/pgai joe result (\d+)/);
       const commandId = match ? match[1] : "";
       expect(commandId).not.toBe("");
 
-      const resumed = await runCliAsync(["result", commandId], env);
+      const resumed = await runCliAsync(["joe", "result", commandId], env);
       expect(resumed.status).toBe(0);
       expect(resumed.stdout).toContain("Seq Scan on users");
     } finally {
@@ -241,7 +252,7 @@ describe("CLI Joe command surface", () => {
     const api = startFakeApi();
     try {
       const r = await runCliAsync(
-        ["plan", "select 1", "--project", "999"],
+        ["joe", "plan", "select 1", "--project", "999"],
         isolatedEnv({ PGAI_API_KEY: "k", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(1);
@@ -251,11 +262,11 @@ describe("CLI Joe command surface", () => {
     }
   });
 
-  test("terminate requires a numeric pid and maps args.pid", async () => {
+  test("joe terminate requires a numeric pid and maps args.pid", async () => {
     const api = startFakeApi();
     try {
       const r = await runCliAsync(
-        ["terminate", "4711", "--project", "12"],
+        ["joe", "terminate", "4711", "--project", "12"],
         isolatedEnv({ PGAI_API_KEY: "k", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(0);
@@ -268,11 +279,11 @@ describe("CLI Joe command surface", () => {
     }
   });
 
-  test("describe maps args.object (and --variant)", async () => {
+  test("joe describe maps args.object (and --variant)", async () => {
     const api = startFakeApi();
     try {
       const r = await runCliAsync(
-        ["describe", "users", "--project", "12", "--variant", "\\d+"],
+        ["joe", "describe", "users", "--project", "12", "--variant", "\\d+"],
         isolatedEnv({ PGAI_API_KEY: "k", PGAI_API_BASE_URL: api.baseUrl })
       );
       expect(r.status).toBe(0);
@@ -285,13 +296,13 @@ describe("CLI Joe command surface", () => {
   });
 
   test("missing --project fails fast", () => {
-    const r = runCli(["plan", "select 1"], isolatedEnv({ PGAI_API_KEY: "k" }));
+    const r = runCli(["joe", "plan", "select 1"], isolatedEnv({ PGAI_API_KEY: "k" }));
     expect(r.status).toBe(1);
     expect(`${r.stdout}\n${r.stderr}`).toContain("Project is required");
   });
 
   test("missing API key fails fast", () => {
-    const r = runCli(["plan", "select 1", "--project", "12"], isolatedEnv());
+    const r = runCli(["joe", "plan", "select 1", "--project", "12"], isolatedEnv());
     expect(r.status).toBe(1);
     expect(`${r.stdout}\n${r.stderr}`).toContain("API key is required");
   });