postgresai 0.16.0-dev.1 → 0.16.0-dev.10

package/README.md

@@ -229,10 +229,67 @@ postgresai mon check                          # System readiness check
 postgresai mon shell <service>                # Open shell to monitoring service
 ```
 
+### Joe API v2 (`joe` group)
+
+Run database-optimization commands on the project's ephemeral DBLab clone via the
+platform Joe API v2. Every verb takes `--project <id|alias>` (a numeric project id,
+or the project's alias/name/label); use `pgai projects` to discover them.
+
+```bash
+pgai projects                                          # org-level discovery: which projects have Joe ready
+
+pgai joe plan "select * from users where email = $1" --project 12   # EXPLAIN, plan-only (never executes)
+pgai joe explain "select ..." --project main-db        # EXPLAIN ANALYZE (executes on the clone)
+pgai joe exec "create index on users (email)" --project 12          # arbitrary DDL/DML on the clone
+pgai joe hypo "create index on users (name)" --query "select ..." --project 12  # HypoPG what-if + re-plan
+pgai joe activity --project 12                         # pg_stat_activity snapshot (query text redacted)
+pgai joe describe users --project 12 [--variant "\d+"] # \d-family metadata
+pgai joe terminate <pid> --project 12                  # pg_terminate_backend on the clone
+pgai joe reset --project 12                            # reset the session's clone
+pgai joe status <commandId>                            # command status (metadata only)
+pgai joe result <commandId>                            # fetch/resume a command result
+pgai joe history <terms>                               # search prior analyses (M1b — not yet available)
+```
+
+Shared options: `--session <id>` / `--new-session` (session/clone threading — the
+session returned by a command is auto-reused per project), `--budget <seconds>`
+(one-shot poll budget, default 25; on expiry the command exits 0 and prints a
+resume handle: `pgai joe result <commandId>`), `--debug`, `--json`.
+
+Exit codes: 0 on success or budget expiry (resume handle); 1 on a server-side
+`error` or `timed_out`, a refused submit (e.g. missing scope, `ai_enabled=false`),
+or invalid arguments.
+
+### DBLab companion (`dblab` group)
+
+Manage the project's DBLab thin clones, branches, and snapshots — proxies the same
+Platform DBLab API the Console uses. Read/create verbs require the `joe:plan` token
+scope; destructive verbs (clone reset/destroy, branch delete, snapshot destroy)
+require `joe:admin` (enforced server-side).
+
+```bash
+pgai dblab clone create --project 12 --id my-clone --db-user u --db-password p \
+  [--branch <branch>] [--snapshot <id>] [--protected]
+pgai dblab clone list --project 12
+pgai dblab clone status <cloneId> --project 12
+pgai dblab clone reset <cloneId> --project 12 [--snapshot <id> | --latest]
+pgai dblab clone destroy <cloneId> --project 12
+
+pgai dblab branch list --project 12
+pgai dblab branch create <name> --project 12 [--snapshot <id>] [--base-branch <branch>]
+pgai dblab branch delete <name> --project 12
+pgai dblab branch log <name> --project 12
+
+pgai dblab snapshot list --project 12 [--branch <branch>] [--dataset <dataset>]
+pgai dblab snapshot create --project 12 --clone <cloneId> [--message <msg>]
+pgai dblab snapshot destroy <snapshotId> --project 12 [--force]
+```
+
 ### MCP server (`mcp` group)
 
 ```bash
 postgresai mcp start                 # Start MCP stdio server exposing tools
+postgresai mcp install [client]      # Install the MCP config for cursor/claude-code/windsurf/codex
 ```
 
 Cursor configuration example (Settings → MCP):
@@ -251,7 +308,9 @@ Cursor configuration example (Settings → MCP):
 }
 ```
 
-Tools exposed:
+Tools exposed (36 total — MCP tool names are FLAT; only the human CLI tree is grouped):
+
+Issues & files:
 - `list_issues`: returns the same JSON as `postgresai issues list`.
 - `view_issue`: view a single issue with its comments (args: `{ issue_id, debug? }`).
 - `create_issue`: create a new issue (args: `{ title, description?, org_id, attachments?, debug? }`).
@@ -261,6 +320,30 @@ Tools exposed:
 - `upload_file`: upload a local file and return the storage URL plus a ready-to-paste markdown link (args: `{ path, debug? }`).
 - `download_file`: download a file from storage (args: `{ url, output_path?, debug? }`).
 
+Action items:
+- `view_action_item`, `list_action_items`, `create_action_item`, `update_action_item`: manage an issue's action items.
+
+Checkup reports:
+- `list_reports`, `list_report_files`, `get_report_data`: browse checkup reports and fetch their json/md content.
+
+Joe API v2 (mirror `pgai joe <verb>`; every command tool takes `{ project_id, session_id?, new_session?, timeout_ms?, debug? }`
+plus its own arguments — `timeout_ms` is the one-shot poll budget; on expiry the tool returns `budget_expired: true`
+and a `resume` handle instead of blocking):
+- `plan_query`: EXPLAIN, plan-only — never executes (args: `{ sql, ... }`). Requires `joe:plan`.
+- `explain_query`: EXPLAIN ANALYZE — executes on the ephemeral DBLab clone (args: `{ sql, ... }`). Requires `joe:exec`.
+- `exec_sql`: arbitrary DDL/DML on the clone — can return real table rows into the agent's context (args: `{ sql, ... }`). Requires `joe:exec`.
+- `hypo_index`: HypoPG hypothetical index + re-plan (args: `{ sql, query, ... }`). Requires `joe:plan`.
+- `activity`: pg_stat_activity snapshot, query text redacted. Requires `joe:plan`.
+- `terminate_backend`: pg_terminate_backend on the clone (args: `{ pid, ... }`). Requires `joe:admin`.
+- `reset_clone`: reset the session's thin clone. Requires `joe:admin`.
+- `describe`: \d-family metadata introspection (args: `{ object, variant?, ... }`). Requires `joe:plan`.
+- `list_projects`: org-level discovery (mirrors `pgai projects`) — which projects are Joe-ready.
+
+DBLab companion (mirror `pgai dblab <group> <verb>`; every tool takes `{ project, org_id?, debug? }` plus its own arguments):
+- `clone_create`, `clone_list`, `clone_status`, `clone_reset`, `clone_destroy`
+- `branch_list`, `branch_create`, `branch_delete`, `branch_log`
+- `snapshot_list`, `snapshot_create`, `snapshot_destroy`
+
 #### `attachments` parameter (issue/comment tools)
 
 `create_issue`, `update_issue`, `post_issue_comment`, and `update_issue_comment` accept an