From db257562d94aa46c0b893e30edc639f56e902836 Mon Sep 17 00:00:00 2001
From: Alex Shapalov <shapalov@gmail.com>
Date: Sun, 18 Oct 2026 18:07:39 -0700
Subject: [PATCH] =?UTF-8?q?feat:=20`pgbot=20sql=20explain`=20=E2=80=94=20a?=
 =?UTF-8?q?=20query=20plan,=20read=20in=20plain=20English?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a `sql` command group with `explain`: the plan-only form of EXPLAIN for
one SELECT (GENERIC_PLAN on PG16+), run inside a READ ONLY transaction and
never executed, rendered as a tree with a plain-English gloss per node, the
planner's estimates, and a deterministic "What stands out" list (large seq
scans, nested loops repeating a scan, sorts an index could avoid, filters
applied after an index lookup). `--json` prints the raw plan; `--ai` appends
a model's prose reading behind a disclosure prompt that names what is sent.

The new internal/plan package (Prepare/Fetch/Parse/Gloss/Observe) is shared
with the MCP explain_plan tool, which now also returns the observations.
Cobra command matching is case-insensitive so `pgbot SQL EXPLAIN` works.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 CHANGELOG.md                            |  20 ++
 README.md                               |  64 ++++-
 cmd/pgbot/explain.go                    |  17 +-
 cmd/pgbot/main.go                       |   6 +
 cmd/pgbot/mcp_tools.go                  |  51 ++--
 cmd/pgbot/sql.go                        | 202 ++++++++++++++++
 cmd/pgbot/sql_test.go                   |  63 +++++
 internal/ai/plan.go                     |  46 ++++
 internal/ai/plan_test.go                |  25 ++
 internal/plan/fetch.go                  |  43 ++++
 internal/plan/fetch_integration_test.go |  84 +++++++
 internal/plan/observe.go                |  89 +++++++
 internal/plan/plan.go                   | 243 +++++++++++++++++++
 internal/plan/plan_test.go              | 297 ++++++++++++++++++++++++
 internal/render/plan.go                 | 110 +++++++++
 internal/render/plan_test.go            |  99 ++++++++
 16 files changed, 1423 insertions(+), 36 deletions(-)
 create mode 100644 cmd/pgbot/sql.go
 create mode 100644 cmd/pgbot/sql_test.go
 create mode 100644 internal/ai/plan.go
 create mode 100644 internal/ai/plan_test.go
 create mode 100644 internal/plan/fetch.go
 create mode 100644 internal/plan/fetch_integration_test.go
 create mode 100644 internal/plan/observe.go
 create mode 100644 internal/plan/plan.go
 create mode 100644 internal/plan/plan_test.go
 create mode 100644 internal/render/plan.go
 create mode 100644 internal/render/plan_test.go

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0077b5f..62f4edf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,26 @@ separately by `model.SchemaVersion` (currently 1.5.0).
 
 ## [Unreleased]
 
+### Added
+- **`pgbot sql explain "<SELECT …>"` — a query plan, read in plain English.**
+  Runs the plan-only form of EXPLAIN for one SELECT (`GENERIC_PLAN` on
+  PostgreSQL 16+, so `$1` placeholders need no values) inside a `READ ONLY`
+  transaction — the query is never executed — and renders the plan as a tree
+  with a one-line plain-English gloss per node, the planner's cost and row
+  estimates, and a **What stands out** list: sequential scans expected to return
+  many rows, nested loops that repeat a scan per outer row, sorts an index could
+  avoid, filters applied after an index lookup. All of it is deterministic and
+  offline. `--json` prints the raw `EXPLAIN (FORMAT JSON)`; `--ai` appends a
+  model's prose reading of the same rendered plan behind a disclosure prompt
+  that names what is sent (your SQL text and its plan, which unlike findings can
+  carry literal values). The query is the last argument or stdin; the connection
+  is the first argument or `$DATABASE_URL`. Only a single plain SELECT is
+  accepted (exit 64 otherwise). Command names are now matched
+  case-insensitively, so `pgbot SQL EXPLAIN …` reads like the statement it wraps.
+- The MCP `explain_plan` tool now shares the same guarded path and returns the
+  same deterministic `observations` alongside the raw plan, plus `generic_plan`
+  when GENERIC_PLAN was used.
+
 ### Changed
 - **PostgreSQL driver: pgx → [pgGo](https://github.com/pgrundev/pggo).** pgbot
   now talks to PostgreSQL through pgGo, a dependency-free wire-protocol client
diff --git a/README.md b/README.md
index 57b5484..3f39509 100644
--- a/README.md
+++ b/README.md
@@ -250,6 +250,7 @@ Every command takes the connection the same way — an argument, `$DATABASE_URL`
 | `activity` | live sessions right now — PIDs, ages, waits, and what each is running |
 | `report` | the full inspection as one self-contained HTML page (`pgbot report > report.html`) |
 | `advise` | planner-validated missing-index suggestions (needs hypopg) |
+| `sql explain "<SELECT …>"` | one query's plan, read in plain English — plan-only EXPLAIN, never executed (`--ai` for a prose reading) |
 | `ask "…"` · `explain` | a plain-language AI reading of the same deterministic findings |
 | `explain-finding <id>` | the catalogue page for a finding, offline |
 | `mcp` | serve the findings to an AI agent over MCP |
@@ -603,6 +604,9 @@ pgbot tables  <connection-string>   # largest tables + row counts + seq-vs-index
 pgbot vacuum <connection-string>    # autovacuum health per table — dead tuples + whether it's due
 pgbot tune <connection-string>      # config-tuning recommendations from the workload
 pgbot explain <connection-string>   # inspect, then have an AI explain the findings
+pgbot sql explain "SELECT …"        # one query's plan as a tree + plain English ($DATABASE_URL)
+  --json                 the raw EXPLAIN (FORMAT JSON) instead
+  --ai                   append a model's prose reading of the plan
 pgbot ask "why is it slow?"         # AI answer grounded on the findings ($DATABASE_URL)
   --yes                  skip the data-disclosure confirmation prompt
 pgbot mcp                           # run as an MCP server over stdio (for AI agents)
@@ -624,7 +628,8 @@ on stdio, so an AI agent can call pgbot as a read-only tool. It exposes
   your repo; it says what to search for. Also `pgbot indexes --correlate [--json]`.
 - `record_index_verdict` — store what the repo search found, so a later run over a
   longer window carries strengthening evidence (no DB connection needed)
-- `explain_plan` — the planner's plan for a SELECT (plain EXPLAIN, never executed)
+- `explain_plan` — the planner's plan for a SELECT (plain EXPLAIN, never executed),
+  with the same deterministic `observations` that `pgbot sql explain` prints
 - `schema_of` — a table's columns/indexes/constraints + row estimate, **no data**
 - `compare_to_baseline` — the `diff`, with its interval-honesty and reset caveats
 - `why` — the causal chains from stored history (symptom ← mechanism ←
@@ -697,6 +702,63 @@ The plugin drives the `pgbot` binary, so install that first (`curl -fsSL
 https://pgbot.dev/install | sh`); set `DATABASE_URL` or pass a connection string
 per call, then ask *"is my Postgres healthy?"*
 
+### `sql explain` — read a query plan in plain English
+
+```sh
+pgbot sql explain "SELECT c.name, count(*) FROM orders o JOIN customers c ON c.id = o.customer_id
+                   WHERE o.status = $1 GROUP BY c.name ORDER BY 2 DESC"
+cat slow.sql | pgbot sql explain            # the query on stdin
+pgbot sql explain "$DATABASE_URL" "SELECT …" # connection first, then the query
+```
+
+`pgbot sql explain` runs the **plan-only** form of EXPLAIN for one SELECT —
+inside a `READ ONLY` transaction, the query is planned and never executed — and
+renders the plan the way you'd want a colleague to read it to you:
+
+```
+Query plan  ·  estimates only — the query was planned, not executed
+  SELECT c.name, count(*) FROM orders o JOIN customers c ON c.id = o.customer_id …
+
+Sort  cost=562.48..567.48  rows≈2.0K
+    sorts about 2.0K rows by (count(*)) DESC
+  └─ Aggregate (hashed)  cost=432.82..452.82  rows≈2.0K
+         groups by c.name using a hash table; expects about 2.0K rows
+       └─ Hash Join (inner)  cost=135.96..399.49  rows≈6.7K
+              inner join: builds a hash table from one side and probes it with the other
+              Hash Cond: (o.customer_id = c.id)
+            ├─ Bitmap Heap Scan on orders (as o)  cost=79.96..325.96  rows≈6.7K
+            │      fetches the pages of orders marked in a bitmap by the index scan below
+            │      Filter: (amount > '0'::numeric)
+            │    └─ Bitmap Index Scan using orders_status_idx  cost=0.00..78.29  rows≈6.7K
+            │           Index Cond: (status = $1)
+            └─ Hash  cost=31.00..31.00  rows≈2.0K
+                 └─ Seq Scan on customers (as c)  cost=0.00..31.00  rows≈2.0K
+                        reads every row of customers, planner expects about 2.0K rows
+
+What stands out
+  · The scan via orders_status_idx on orders applies (amount > '0'::numeric) after the
+    index lookup, so some rows are fetched and then discarded. …
+
+Costs and row counts are the planner's estimates, not measurements.
+Planned as a generic plan: parameter values ($1, …) were unknown …
+```
+
+Each node gets one plain-English line; **What stands out** lists the shapes
+worth a look — a sequential scan the planner expects to return many rows, a
+nested loop that repeats a scan per outer row, a sort an index could avoid, a
+filter applied after an index lookup — all derived from the planner's estimates,
+offline, with no model involved. `pgbot SQL EXPLAIN …` works too (command names
+are case-insensitive).
+
+- On PostgreSQL 16+ the plan is generic (`EXPLAIN (GENERIC_PLAN)`), so `$1`-style
+  placeholders need no values; older servers plan queries with literal values.
+- Only a **single plain SELECT** is accepted — no writes, no `WITH`, no multiple
+  statements (exit 64 otherwise). pgbot never uses the executing form of EXPLAIN.
+- `--json` prints the raw `EXPLAIN (FORMAT JSON)` output.
+- `--ai` appends a model's prose reading of the same rendered plan, behind the
+  disclosure prompt below. Unlike the findings, **your SQL text can carry literal
+  values**, so the prompt names exactly what is sent: the query and its plan.
+
 ### `explain` — optional AI layer
 
 `pgbot explain` runs the exact same read-only inspection, prints the
diff --git a/cmd/pgbot/explain.go b/cmd/pgbot/explain.go
index b44ce56..3a18ebd 100644
--- a/cmd/pgbot/explain.go
+++ b/cmd/pgbot/explain.go
@@ -136,18 +136,25 @@ func runExplain(cmd *cobra.Command, args []string, f inspectFlags, yes bool) err
 // confirmDisclosure identifies the remote destination before data is sent.
 // Local endpoints do not send findings off the machine and need no confirmation.
 func confirmDisclosure(cmdName string, llm ai.LanguageModel, yes bool) bool {
+	return confirmDisclosureOf(cmdName, "the PII-free findings (same as `inspect --json`)", llm, yes)
+}
+
+// confirmDisclosureOf is confirmDisclosure with the payload named: `sql explain
+// --ai` sends the user's SQL text and its plan, which — unlike the findings —
+// can carry literal values, so the prompt must say exactly that.
+func confirmDisclosureOf(cmdName, payload string, llm ai.LanguageModel, yes bool) bool {
 	if ai.Local(llm.Endpoint()) {
-		fmt.Fprintf(os.Stderr, "%s: using a local model at %s (%s) — the findings do not leave this machine.\n",
-			cmdName, ai.Host(llm.Endpoint()), llm.Model())
+		fmt.Fprintf(os.Stderr, "%s: using a local model at %s (%s) — %s does not leave this machine.\n",
+			cmdName, ai.Host(llm.Endpoint()), llm.Model(), payload)
 		return true
 	}
-	fmt.Fprintf(os.Stderr, "%s: this sends the PII-free findings (same as `inspect --json`) to %s at %s (model %s).\n",
-		cmdName, llm.Provider(), ai.Host(llm.Endpoint()), llm.Model())
+	fmt.Fprintf(os.Stderr, "%s: this sends %s to %s at %s (model %s).\n",
+		cmdName, payload, llm.Provider(), ai.Host(llm.Endpoint()), llm.Model())
 	if strings.HasPrefix(strings.ToLower(llm.Endpoint()), "http://") {
 		// Not local (that returned above), and not TLS: the API key and the
 		// findings cross the network in the clear. Say so; it is usually a LAN
 		// address copied from a "local model" recipe.
-		fmt.Fprintf(os.Stderr, "%s: WARNING — %s is plain http, so the key and the findings travel unencrypted.\n",
+		fmt.Fprintf(os.Stderr, "%s: WARNING — %s is plain http, so the key and the payload travel unencrypted.\n",
 			cmdName, ai.Host(llm.Endpoint()))
 	}
 	if yes || !isInteractive() {
diff --git a/cmd/pgbot/main.go b/cmd/pgbot/main.go
index 0b8d92e..e9ebaf6 100644
--- a/cmd/pgbot/main.go
+++ b/cmd/pgbot/main.go
@@ -29,6 +29,11 @@ func main() {
 	// way out rather than per-Target (--all-databases and `mcp` open many).
 	defer conn.CloseSSHTunnel()
 
+	// `pgbot SQL EXPLAIN ...` reads like the statement it wraps; cobra matches
+	// command names case-insensitively when this is set, so no two spellings need
+	// separate commands. No two pgbot commands differ only by case.
+	cobra.EnableCaseInsensitive = true
+
 	root := &cobra.Command{
 		Use:           "pgbot",
 		Short:         "In-database observability for PostgreSQL",
@@ -59,6 +64,7 @@ func main() {
 	root.AddCommand(newERDCmd())
 	root.AddCommand(newActivityCmd())
 	root.AddCommand(newReportCmd())
+	root.AddCommand(newSQLCmd())
 
 	// --ssh-tunnel is global: every command that takes a connection can need it,
 	// and it changes only HOW the DSN is reached, never what is inspected.
diff --git a/cmd/pgbot/mcp_tools.go b/cmd/pgbot/mcp_tools.go
index 8662943..f708fb0 100644
--- a/cmd/pgbot/mcp_tools.go
+++ b/cmd/pgbot/mcp_tools.go
@@ -8,8 +8,8 @@ import (
 	"time"
 
 	"github.com/pgrundev/pgbot/docs"
-	"github.com/pgrundev/pgbot/internal/advisor"
 	"github.com/pgrundev/pgbot/internal/conn"
+	"github.com/pgrundev/pgbot/internal/plan"
 	"github.com/pgrundev/pgbot/internal/store"
 	"github.com/pgrundev/pggo"
 )
@@ -22,8 +22,9 @@ import (
 // — a third-party client can still reword or drop it on its side.
 
 // explainPlanTool runs a PLAIN EXPLAIN (the plan-only form) of an agent-supplied query
-// through the same guard as the advisor: SanitizeSelect (single plain SELECT, no
-// semicolons) plus a READ ONLY transaction. The query is planned, never executed.
+// through plan.Fetch — the same guarded path as `pgbot sql explain`: SanitizeSelect
+// (single plain SELECT, no semicolons) plus a READ ONLY transaction. The query is
+// planned, never executed.
 func explainPlanTool(ctx context.Context, args json.RawMessage) (string, error) {
 	var a struct {
 		ConnectionString string `json:"connection_string"`
@@ -33,9 +34,8 @@ func explainPlanTool(ctx context.Context, args json.RawMessage) (string, error)
 	if strings.TrimSpace(a.Query) == "" {
 		return "", fmt.Errorf("query is required")
 	}
-	clean := advisor.SanitizeSelect(a.Query)
-	if clean == "" {
-		return "", fmt.Errorf("only a single plain SELECT can be explained — no writes, no multiple statements, no utility statements")
+	if _, err := plan.Prepare(a.Query, 160000); err != nil {
+		return "", err
 	}
 	dsn, err := dsnFromArgs(args)
 	if err != nil {
@@ -49,35 +49,26 @@ func explainPlanTool(ctx context.Context, args json.RawMessage) (string, error)
 	}
 	defer target.Close()
 
-	// GENERIC_PLAN (PG16+) plans a query with $N placeholders without values;
-	// below 16, plain EXPLAIN works for a query with literal values and errors
-	// clearly on one with placeholders.
-	stmt := "EXPLAIN (FORMAT JSON) " + clean
-	if target.Caps.VersionNum >= 160000 {
-		stmt = "EXPLAIN (GENERIC_PLAN, FORMAT JSON) " + clean
-	}
-	var planJSON []byte
-	err = target.ReadOnlyTx(ctx, func(tx *pggo.Tx) error {
-		res, e := tx.Conn().SimpleQuery(ctx, stmt)
-		if e != nil {
-			return e
-		}
-		for _, r := range res {
-			if len(r.Rows) > 0 && len(r.Rows[0]) > 0 {
-				planJSON = r.Rows[0][0]
-				return nil
-			}
-		}
-		return fmt.Errorf("no plan returned")
-	})
+	planJSON, generic, err := plan.Fetch(ctx, target, a.Query)
 	if err != nil {
-		return "", fmt.Errorf("explain: %s", conn.RedactConnString(err.Error()))
+		return "", err
 	}
-	return marshal(map[string]any{
+	out := map[string]any{
 		"plan":      json.RawMessage(planJSON),
 		"exactness": "estimate",
 		"note":      "plain EXPLAIN — the query was planned, NOT executed. Costs and row counts are the planner's ESTIMATES, not measurements; state them as such.",
-	})
+	}
+	if root, perr := plan.Parse(planJSON); perr == nil {
+		var obs []map[string]string
+		for _, o := range plan.Observe(root) {
+			obs = append(obs, map[string]string{"level": o.Level, "text": o.Text})
+		}
+		out["observations"] = obs
+	}
+	if generic {
+		out["generic_plan"] = true
+	}
+	return marshal(out)
 }
 
 // compareToBaselineTool is `pgbot diff` as a tool: it reads the local baseline
diff --git a/cmd/pgbot/sql.go b/cmd/pgbot/sql.go
new file mode 100644
index 0000000..06bfa98
--- /dev/null
+++ b/cmd/pgbot/sql.go
@@ -0,0 +1,202 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/pgrundev/pgbot/internal/ai"
+	"github.com/pgrundev/pgbot/internal/conn"
+	"github.com/pgrundev/pgbot/internal/plan"
+	"github.com/pgrundev/pgbot/internal/render"
+	"github.com/spf13/cobra"
+)
+
+// newSQLCmd groups the statement-level tools. `pgbot sql explain` is the first:
+// the planner's plan for one SELECT, read back in plain English. Cobra matches
+// command names case-insensitively (see main), so `pgbot SQL EXPLAIN` works too.
+func newSQLCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "sql",
+		Short: "Statement-level tools: explain a query's plan in plain language",
+		Long: "Tools that take one SQL statement rather than inspecting the whole database.\n" +
+			"Everything here is read-only: a statement is planned, never executed.",
+	}
+	cmd.AddCommand(newSQLExplainCmd())
+	return cmd
+}
+
+type sqlExplainFlags struct {
+	jsonOut bool
+	useAI   bool
+	yes     bool
+	noColor bool
+}
+
+func newSQLExplainCmd() *cobra.Command {
+	var f sqlExplainFlags
+	cmd := &cobra.Command{
+		Use:   `explain [connection-string] "<SELECT …>"`,
+		Short: "Show a SELECT's query plan and read it in plain English",
+		Long: "Runs the plan-only form of EXPLAIN for one SELECT — the query is planned inside a\n" +
+			"READ ONLY transaction and never executed — and renders the plan as a tree with a\n" +
+			"plain-English line per node, what stands out (sequential scans on large tables,\n" +
+			"nested loops that repeat a scan, sorts an index could avoid), and the caveat that\n" +
+			"every number is the planner's estimate.\n\n" +
+			"On PostgreSQL 16+ the plan is generic (EXPLAIN GENERIC_PLAN), so $1-style\n" +
+			"placeholders need no values. Only a single plain SELECT is accepted: no writes,\n" +
+			"no WITH, no multiple statements.\n\n" +
+			"The query is the last argument, or stdin when piped. The connection is the first\n" +
+			"argument, else $DATABASE_URL / $PGBOT_DATABASE_URL / $PGSERVICE.\n\n" +
+			"--ai adds a model's prose explanation of the rendered plan. Unlike pgbot's\n" +
+			"findings, your SQL text can contain literal values, so the disclosure prompt\n" +
+			"names exactly what is sent: the query and its plan.",
+		Example: "  pgbot sql explain \"SELECT * FROM orders WHERE customer_id = $1\"\n" +
+			"  pgbot sql explain \"$DATABASE_URL\" \"SELECT count(*) FROM events WHERE kind = 'click'\"\n" +
+			"  cat slow.sql | pgbot sql explain --ai",
+		Args: cobra.MaximumNArgs(2),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return runSQLExplain(cmd, args, f)
+		},
+	}
+	fl := cmd.Flags()
+	fl.BoolVar(&f.jsonOut, "json", false, "print the raw EXPLAIN (FORMAT JSON) output instead of the reading")
+	fl.BoolVar(&f.useAI, "ai", false, "append a model's plain-language explanation (needs an AI key in the environment)")
+	fl.BoolVar(&f.yes, "yes", false, "skip the data-disclosure confirmation prompt (--ai)")
+	fl.BoolVar(&f.noColor, "no-color", false, "disable ANSI color")
+	return cmd
+}
+
+// resolveSQLExplainInput works out the connection string and the query from the
+// positional arguments, the environment and (when piped) stdin:
+//
+//	explain "<sql>"              → query, connection from env
+//	explain <conn> "<sql>"       → both explicit
+//	explain < file.sql           → query from stdin, connection from env
+//	explain <conn> < file.sql    → connection explicit, query from stdin
+func resolveSQLExplainInput(args []string, stdin io.Reader, stdinIsTerminal bool) (connString, query string, err error) {
+	switch len(args) {
+	case 2:
+		connString, query = args[0], args[1]
+	case 1:
+		if looksLikeConnString(args[0]) {
+			connString = args[0]
+		} else {
+			query = args[0]
+		}
+	}
+	if query == "" {
+		if stdinIsTerminal {
+			return "", "", usageErrf("no query given — pass a SELECT as the last argument or pipe it on stdin")
+		}
+		b, rerr := io.ReadAll(stdin)
+		if rerr != nil {
+			return "", "", fmt.Errorf("read stdin: %w", rerr)
+		}
+		query = strings.TrimSpace(string(b))
+		if query == "" {
+			return "", "", usageErrf("no query given — stdin was empty")
+		}
+	}
+	connString = firstNonEmpty(connString, os.Getenv("DATABASE_URL"), os.Getenv("PGBOT_DATABASE_URL"), pgServiceFallback())
+	if connString == "" {
+		return "", "", fmt.Errorf("no connection string (pass one before the query or set $DATABASE_URL)")
+	}
+	return connString, query, nil
+}
+
+// looksLikeConnString tells a connection string from a SQL statement: a
+// postgres:// URL, or a libpq keyword string (host=…, dbname=…, service=…).
+func looksLikeConnString(s string) bool {
+	s = strings.TrimSpace(s)
+	low := strings.ToLower(s)
+	if strings.HasPrefix(low, "postgres://") || strings.HasPrefix(low, "postgresql://") {
+		return true
+	}
+	for _, kw := range []string{"host=", "dbname=", "service=", "user=", "port=", "hostaddr="} {
+		if strings.HasPrefix(low, kw) {
+			return true
+		}
+	}
+	return false
+}
+
+func runSQLExplain(cmd *cobra.Command, args []string, f sqlExplainFlags) error {
+	connString, query, err := resolveSQLExplainInput(args, os.Stdin, isInteractive())
+	if err != nil {
+		return err
+	}
+	// Refuse anything but one plain SELECT before connecting; a bad statement is
+	// a usage error (exit 64), not an execution failure.
+	if _, err := plan.Prepare(query, 160000); err != nil {
+		if errors.Is(err, plan.ErrNotSelect) {
+			return usageErrf("%s", err.Error())
+		}
+		return err
+	}
+
+	// --ai: resolve the model and get consent BEFORE connecting, so a missing key
+	// fails fast and the user knows exactly what leaves the machine.
+	var llm ai.LanguageModel
+	if f.useAI {
+		llm, err = ai.Resolve()
+		if err != nil {
+			return err
+		}
+		if !confirmDisclosureOf("pgbot sql explain", "your SQL text and its query plan", llm, f.yes) {
+			return fmt.Errorf("aborted")
+		}
+	}
+
+	ctx, cancel := context.WithTimeout(cmd.Context(), 30*time.Second)
+	defer cancel()
+	target, err := conn.Connect(ctx, connString)
+	if err != nil {
+		return fmt.Errorf("connect: %s", conn.RedactConnString(err.Error()))
+	}
+	defer target.Close()
+	if target.Pooler.Detected {
+		fmt.Fprintln(os.Stderr, target.Pooler.Note())
+	}
+
+	planJSON, generic, err := plan.Fetch(ctx, target, query)
+	if err != nil {
+		return err
+	}
+	if f.jsonOut {
+		var pretty bytes.Buffer
+		if json.Indent(&pretty, planJSON, "", "  ") != nil {
+			pretty.Write(planJSON)
+		}
+		fmt.Println(pretty.String())
+		return nil
+	}
+	root, err := plan.Parse(planJSON)
+	if err != nil {
+		return err
+	}
+
+	color := useColor(f.noColor)
+	// The generic-plan caveat matters only when there were parameters for the
+	// planner not to know.
+	in := render.PlanInput{Query: query, Root: root, Observations: plan.Observe(root), Generic: generic && plan.HasPlaceholders(query), Color: color}
+	render.Plan(os.Stdout, in)
+
+	if llm != nil {
+		// The model reads the same text the user just saw, uncolored.
+		var plain bytes.Buffer
+		in.Color = false
+		render.Plan(&plain, in)
+		aiCtx, aiCancel := context.WithTimeout(cmd.Context(), 3*time.Minute)
+		defer aiCancel()
+		text, aiErr := ai.ExplainPlan(aiCtx, llm, query, plain.String())
+		printAISection(color, llm.Model(), text, aiErr)
+	}
+	return nil
+}
diff --git a/cmd/pgbot/sql_test.go b/cmd/pgbot/sql_test.go
new file mode 100644
index 0000000..893af43
--- /dev/null
+++ b/cmd/pgbot/sql_test.go
@@ -0,0 +1,63 @@
+package main
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestResolveSQLExplainInput(t *testing.T) {
+	t.Setenv("DATABASE_URL", "")
+	t.Setenv("PGBOT_DATABASE_URL", "")
+	t.Setenv("PGSERVICE", "")
+
+	// One argument that looks like SQL is the query; connection comes from env.
+	t.Setenv("DATABASE_URL", "postgres://env/db")
+	conn, q, err := resolveSQLExplainInput([]string{"SELECT 1"}, strings.NewReader(""), true)
+	if err != nil || conn != "postgres://env/db" || q != "SELECT 1" {
+		t.Errorf("one arg: conn=%q q=%q err=%v", conn, q, err)
+	}
+
+	// Two arguments: connection string first, then the query.
+	conn, q, err = resolveSQLExplainInput([]string{"postgres://arg/db", "select * from t"}, strings.NewReader(""), true)
+	if err != nil || conn != "postgres://arg/db" || q != "select * from t" {
+		t.Errorf("two args: conn=%q q=%q err=%v", conn, q, err)
+	}
+
+	// No argument and piped stdin: the query is read from stdin.
+	conn, q, err = resolveSQLExplainInput(nil, strings.NewReader("SELECT 2\n"), false)
+	if err != nil || conn != "postgres://env/db" || q != "SELECT 2" {
+		t.Errorf("stdin: conn=%q q=%q err=%v", conn, q, err)
+	}
+
+	// A single connection-string argument with piped stdin: query from stdin.
+	conn, q, err = resolveSQLExplainInput([]string{"postgres://arg/db"}, strings.NewReader("SELECT 3"), false)
+	if err != nil || conn != "postgres://arg/db" || q != "SELECT 3" {
+		t.Errorf("conn+stdin: conn=%q q=%q err=%v", conn, q, err)
+	}
+
+	// No argument and an interactive terminal: nothing to explain.
+	if _, _, err = resolveSQLExplainInput(nil, strings.NewReader(""), true); err == nil {
+		t.Error("no query on a TTY should be an error")
+	}
+
+	// No connection anywhere.
+	t.Setenv("DATABASE_URL", "")
+	if _, _, err = resolveSQLExplainInput([]string{"SELECT 1"}, strings.NewReader(""), true); err == nil || !strings.Contains(err.Error(), "connection") {
+		t.Errorf("missing connection should error, got %v", err)
+	}
+}
+
+func TestLooksLikeConnString(t *testing.T) {
+	yes := []string{"postgres://u@h/db", "postgresql://h/db", "host=localhost dbname=x", "service=prod", "dbname=x"}
+	no := []string{"SELECT 1", "select * from t where url = 'postgres://x'", "  SELECT host FROM t", ""}
+	for _, s := range yes {
+		if !looksLikeConnString(s) {
+			t.Errorf("%q should look like a connection string", s)
+		}
+	}
+	for _, s := range no {
+		if looksLikeConnString(s) {
+			t.Errorf("%q should not look like a connection string", s)
+		}
+	}
+}
diff --git a/internal/ai/plan.go b/internal/ai/plan.go
new file mode 100644
index 0000000..adce337
--- /dev/null
+++ b/internal/ai/plan.go
@@ -0,0 +1,46 @@
+package ai
+
+import "context"
+
+// planSystemPrompt constrains the model to reading a query plan pgbot already
+// rendered. The plan is the planner's estimate — pgbot never executes the
+// inspected query — and the model must keep saying so.
+const planSystemPrompt = `You are a senior PostgreSQL expert explaining a query plan to a developer who is not a DBA.
+A tool called pgbot ran the plan-only form of EXPLAIN — the query was NOT executed — and rendered the
+plan below with a plain-English gloss per node and a list of what stands out. Explain it; do not
+invent nodes, tables, indexes, or numbers that are not in it.
+
+Write PLAIN TEXT — no markdown (no #, no *, no bullet characters, no bold, no tables, no code fences).
+Shape:
+
+  <two to four sentences walking the plan from the leaves up: what is read, how it is joined,
+   what is sorted or grouped, in the order PostgreSQL does it>
+
+  Most expensive part:
+  <one line naming the node that dominates the cost and why>
+
+  Next step:
+  <at most two lines of concrete, safe suggestions — an index to consider, a rewrite — or
+   "nothing needed" when the plan is already cheap>
+
+Rules you must follow:
+- Every number is a planner estimate. Say "expects" or "estimates", never "reads" or "took".
+- Never recommend executing the query to diagnose it, in any form: no timing runs, no running it
+  against production. Suggest only non-executing steps.
+- A generic plan does not know parameter values; say so if a suggestion depends on selectivity.
+- Be brief: short lines, a blank line between blocks.`
+
+// BuildPlanPrompt returns the (system, user) prompt for a rendered plan. The
+// rendered text is pgbot's deterministic output; the query is included so the
+// model can relate plan nodes to the SQL.
+func BuildPlanPrompt(query, rendered string) (system, user string) {
+	user = "The query:\n\n" + query + "\n\npgbot's rendering of its plan (estimates only, nothing executed):\n\n" + rendered +
+		"\n\nExplain the plan per your rules."
+	return planSystemPrompt, user
+}
+
+// ExplainPlan asks the model to explain a rendered plan.
+func ExplainPlan(ctx context.Context, m LanguageModel, query, rendered string) (string, error) {
+	system, user := BuildPlanPrompt(query, rendered)
+	return generate(ctx, m, system, user)
+}
diff --git a/internal/ai/plan_test.go b/internal/ai/plan_test.go
new file mode 100644
index 0000000..5d1acd2
--- /dev/null
+++ b/internal/ai/plan_test.go
@@ -0,0 +1,25 @@
+package ai
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestBuildPlanPrompt_groundsTheModelOnTheRenderedPlan(t *testing.T) {
+	system, user := BuildPlanPrompt("SELECT * FROM orders WHERE status = $1", "Seq Scan on orders\n  reads every row of orders, planner expects about 1.2M rows")
+	for _, want := range []string{"SELECT * FROM orders WHERE status = $1", "Seq Scan on orders", "1.2M"} {
+		if !strings.Contains(user, want) {
+			t.Errorf("user prompt lacks %q:\n%s", want, user)
+		}
+	}
+	// The model must treat numbers as estimates and never ask the user to run the query.
+	low := strings.ToLower(system)
+	for _, want := range []string{"estimate", "not executed", "never"} {
+		if !strings.Contains(low, want) {
+			t.Errorf("system prompt lacks %q:\n%s", want, system)
+		}
+	}
+	if !strings.Contains(low, "no markdown") {
+		t.Errorf("system prompt should demand plain text")
+	}
+}
diff --git a/internal/plan/fetch.go b/internal/plan/fetch.go
new file mode 100644
index 0000000..b011645
--- /dev/null
+++ b/internal/plan/fetch.go
@@ -0,0 +1,43 @@
+package plan
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/pgrundev/pgbot/internal/conn"
+	"github.com/pgrundev/pggo"
+)
+
+// ErrNotSelect is returned (wrapped) when the query is not a single plain SELECT.
+var ErrNotSelect = errors.New("only a single plain SELECT can be explained — no writes, no WITH, no multiple statements, no utility statements")
+
+// Fetch runs the plan-only EXPLAIN for query on target and returns the raw
+// FORMAT JSON output. generic reports whether GENERIC_PLAN was used (PG16+),
+// which the caller should say, since those estimates assume unknown parameter
+// values. The query is planned inside a READ ONLY transaction and never
+// executed; Prepare has already refused anything but one plain SELECT.
+func Fetch(ctx context.Context, target *conn.Target, query string) (planJSON []byte, generic bool, err error) {
+	stmt, err := Prepare(query, target.Caps.VersionNum)
+	if err != nil {
+		return nil, false, err
+	}
+	generic = target.Caps.VersionNum >= 160000
+	err = target.ReadOnlyTx(ctx, func(tx *pggo.Tx) error {
+		res, e := tx.Conn().SimpleQuery(ctx, stmt)
+		if e != nil {
+			return e
+		}
+		for _, r := range res {
+			if len(r.Rows) > 0 && len(r.Rows[0]) > 0 {
+				planJSON = r.Rows[0][0]
+				return nil
+			}
+		}
+		return fmt.Errorf("no plan returned")
+	})
+	if err != nil {
+		return nil, generic, fmt.Errorf("explain: %s", conn.RedactConnString(err.Error()))
+	}
+	return planJSON, generic, nil
+}
diff --git a/internal/plan/fetch_integration_test.go b/internal/plan/fetch_integration_test.go
new file mode 100644
index 0000000..6784147
--- /dev/null
+++ b/internal/plan/fetch_integration_test.go
@@ -0,0 +1,84 @@
+package plan
+
+import (
+	"context"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/pgrundev/pgbot/internal/conn"
+)
+
+// Runs only when PGBOT_TEST_DSN points at a live PostgreSQL (CI's docker matrix).
+func testTarget(t *testing.T) (*conn.Target, context.Context) {
+	t.Helper()
+	dsn := os.Getenv("PGBOT_TEST_DSN")
+	if dsn == "" {
+		t.Skip("set PGBOT_TEST_DSN to run integration tests")
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+	t.Cleanup(cancel)
+	target, err := conn.Connect(ctx, dsn)
+	if err != nil {
+		t.Fatalf("connect: %v", err)
+	}
+	t.Cleanup(target.Close)
+	return target, ctx
+}
+
+func TestIntegration_fetchReturnsAParseablePlan(t *testing.T) {
+	target, ctx := testTarget(t)
+	js, generic, err := Fetch(ctx, target, "SELECT relname FROM pg_class WHERE relkind = 'r' ORDER BY relname")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if generic != (target.Caps.VersionNum >= 160000) {
+		t.Errorf("generic = %v on PG %d", generic, target.Caps.VersionNum)
+	}
+	root, err := Parse(js)
+	if err != nil {
+		t.Fatalf("Parse: %v\n%s", err, js)
+	}
+	if root.NodeType == "" || root.TotalCost <= 0 {
+		t.Errorf("root = %+v", root)
+	}
+	if root.Gloss() == "" {
+		t.Error("empty gloss")
+	}
+}
+
+func TestIntegration_placeholdersPlanGenericallyOn16Plus(t *testing.T) {
+	target, ctx := testTarget(t)
+	if target.Caps.VersionNum < 160000 {
+		t.Skip("GENERIC_PLAN needs PostgreSQL 16+")
+	}
+	js, _, err := Fetch(ctx, target, "SELECT * FROM pg_class WHERE oid = $1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := Parse(js); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// The query must be planned, not run: a pg_sleep(30) that executed would blow
+// the deadline; planned, it returns at once.
+func TestIntegration_queryIsNeverExecuted(t *testing.T) {
+	target, ctx := testTarget(t)
+	start := time.Now()
+	if _, _, err := Fetch(ctx, target, "SELECT pg_sleep(30)"); err != nil {
+		t.Fatal(err)
+	}
+	if d := time.Since(start); d > 5*time.Second {
+		t.Fatalf("EXPLAIN took %s — the query ran", d)
+	}
+}
+
+func TestIntegration_writesAreRefusedBeforeReachingTheServer(t *testing.T) {
+	target, ctx := testTarget(t)
+	for _, q := range []string{"DELETE FROM pg_class", "SELECT 1; DELETE FROM pg_class", "WITH d AS (DELETE FROM pg_class RETURNING 1) SELECT * FROM d"} {
+		if _, _, err := Fetch(ctx, target, q); err == nil {
+			t.Errorf("%q accepted", q)
+		}
+	}
+}
diff --git a/internal/plan/observe.go b/internal/plan/observe.go
new file mode 100644
index 0000000..84c9621
--- /dev/null
+++ b/internal/plan/observe.go
@@ -0,0 +1,89 @@
+package plan
+
+import (
+	"fmt"
+	"strings"
+)
+
+// Observation levels. Warn is "the planner expects this to be expensive"; Info
+// is "worth knowing, probably fine".
+const (
+	LevelWarn = "warn"
+	LevelInfo = "info"
+)
+
+// Observation is one deterministic remark about the plan's shape, derived from
+// the planner's estimates only.
+type Observation struct {
+	Level string
+	Text  string
+}
+
+// Thresholds on planner row estimates. They are deliberately coarse: the point
+// is to flag the shapes that are expensive at scale, not to grade every node.
+const (
+	bigScanRows  = 10_000 // a sequential scan expected to return this many rows is worth a look
+	bigOuterRows = 1_000  // a nested loop repeating its inner side this many times is worth a look
+	bigSortRows  = 10_000
+)
+
+// Observe walks the tree and returns the observations, warnings first, in the
+// order the nodes appear.
+func Observe(root *Node) []Observation {
+	var warn, info []Observation
+	add := func(o Observation) {
+		if o.Level == LevelWarn {
+			warn = append(warn, o)
+		} else {
+			info = append(info, o)
+		}
+	}
+	walk(root, func(n *Node) {
+		switch n.NodeType {
+		case "Seq Scan":
+			if n.PlanRows >= bigScanRows {
+				text := fmt.Sprintf("Seq Scan on %s reads the whole table; the planner expects about %s rows back.", n.target(), HumanRows(n.PlanRows))
+				if n.Filter != "" {
+					text += fmt.Sprintf(" Rows are filtered by %s after being read — if that filter is selective, an index on its columns could let the planner skip most of the table.", n.Filter)
+				}
+				add(Observation{LevelWarn, text})
+			}
+		case "Nested Loop":
+			if len(n.Plans) == 2 {
+				outer, inner := &n.Plans[0], &n.Plans[1]
+				if outer.PlanRows >= bigOuterRows && isScan(inner) {
+					add(Observation{LevelWarn, fmt.Sprintf("Nested Loop repeats a %s on %s once per outer row — about %s times. An index on the join column of %s, or a hash join, would avoid that.",
+						inner.NodeType, inner.target(), HumanRows(outer.PlanRows), inner.target())})
+				}
+			}
+		case "Index Scan", "Index Only Scan", "Bitmap Heap Scan":
+			if n.Filter != "" {
+				idx := n.IndexName
+				if idx == "" && len(n.Plans) > 0 {
+					idx = n.Plans[0].IndexName
+				}
+				add(Observation{LevelInfo, fmt.Sprintf("The scan via %s on %s applies %s after the index lookup, so some rows are fetched and then discarded. Adding those columns to the index would skip them.", idx, n.target(), n.Filter)})
+			}
+		case "Sort":
+			if n.PlanRows >= bigSortRows {
+				add(Observation{LevelInfo, fmt.Sprintf("Sort of about %s rows by %s. An index ordered the same way would let the planner read rows pre-sorted and skip this step.", HumanRows(n.PlanRows), strings.Join(n.SortKey, ", "))})
+			}
+		}
+	})
+	return append(warn, info...)
+}
+
+func isScan(n *Node) bool {
+	switch n.NodeType {
+	case "Seq Scan", "Index Scan", "Index Only Scan", "Bitmap Heap Scan", "Tid Scan", "Foreign Scan":
+		return true
+	}
+	return false
+}
+
+func walk(n *Node, fn func(*Node)) {
+	fn(n)
+	for i := range n.Plans {
+		walk(&n.Plans[i], fn)
+	}
+}
diff --git a/internal/plan/plan.go b/internal/plan/plan.go
new file mode 100644
index 0000000..6e79c53
--- /dev/null
+++ b/internal/plan/plan.go
@@ -0,0 +1,243 @@
+// Package plan turns EXPLAIN (FORMAT JSON) output into something a developer who
+// is not a DBA can read: a parsed node tree, a one-line plain-English gloss per
+// node, and a short list of deterministic observations about the plan's shape.
+//
+// Everything here works on the planner's ESTIMATES. pgbot only ever runs the
+// plan-only form of EXPLAIN — the inspected query is never executed — so no
+// number in this package is a measurement, and callers must say so.
+package plan
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	"github.com/pgrundev/pgbot/internal/advisor"
+)
+
+// Node is one EXPLAIN (FORMAT JSON) plan node — the fields we read, with the
+// JSON names PostgreSQL emits.
+type Node struct {
+	NodeType           string   `json:"Node Type"`
+	Strategy           string   `json:"Strategy"`            // Aggregate: Plain | Sorted | Hashed | Mixed
+	ParentRelationship string   `json:"Parent Relationship"` // Outer | Inner | Member | InitPlan | SubPlan
+	JoinType           string   `json:"Join Type"`           // Inner | Left | Right | Full | Semi | Anti
+	RelationName       string   `json:"Relation Name"`
+	Schema             string   `json:"Schema"`
+	Alias              string   `json:"Alias"`
+	IndexName          string   `json:"Index Name"`
+	ScanDirection      string   `json:"Scan Direction"`
+	CTEName            string   `json:"CTE Name"`
+	SubplanName        string   `json:"Subplan Name"`
+	Filter             string   `json:"Filter"`
+	IndexCond          string   `json:"Index Cond"`
+	RecheckCond        string   `json:"Recheck Cond"`
+	HashCond           string   `json:"Hash Cond"`
+	MergeCond          string   `json:"Merge Cond"`
+	JoinFilter         string   `json:"Join Filter"`
+	SortKey            []string `json:"Sort Key"`
+	PresortedKey       []string `json:"Presorted Key"`
+	GroupKey           []string `json:"Group Key"`
+	StartupCost        float64  `json:"Startup Cost"`
+	TotalCost          float64  `json:"Total Cost"`
+	PlanRows           float64  `json:"Plan Rows"`
+	PlanWidth          int      `json:"Plan Width"`
+	ParallelAware      bool     `json:"Parallel Aware"`
+	WorkersPlanned     int      `json:"Workers Planned"`
+	Plans              []Node   `json:"Plans"`
+}
+
+type explainRoot struct {
+	Plan Node `json:"Plan"`
+}
+
+// Parse decodes EXPLAIN (FORMAT JSON) output (a one-element array) into the
+// root node.
+func Parse(js []byte) (*Node, error) {
+	var roots []explainRoot
+	if err := json.Unmarshal(js, &roots); err != nil {
+		return nil, fmt.Errorf("plan JSON: %w", err)
+	}
+	if len(roots) == 0 {
+		return nil, fmt.Errorf("empty EXPLAIN output")
+	}
+	if roots[0].Plan.NodeType == "" {
+		return nil, fmt.Errorf("EXPLAIN output has no plan node")
+	}
+	return &roots[0].Plan, nil
+}
+
+// Prepare validates a user-supplied query and builds the plan-only EXPLAIN
+// statement for it. The same SELECT-only sanitizer guards `advise` and the MCP
+// explain_plan tool: a single plain SELECT, no CTE (a WITH can hide a writable
+// CTE), no interior semicolon. versionNum is the server's integer version
+// (e.g. 160000): from 16 on, GENERIC_PLAN plans a query with $N placeholders
+// without values; below that, plain EXPLAIN works for literal queries and errors
+// clearly on placeholders.
+func Prepare(query string, versionNum int) (string, error) {
+	clean := advisor.SanitizeSelect(query)
+	if clean == "" {
+		return "", ErrNotSelect
+	}
+	if versionNum >= 160000 {
+		return "EXPLAIN (GENERIC_PLAN, FORMAT JSON) " + clean, nil
+	}
+	return "EXPLAIN (FORMAT JSON) " + clean, nil
+}
+
+// HumanRows formats a planner row estimate: 999 → "999", 12345 → "12.3K",
+// 1200000 → "1.2M".
+func HumanRows(f float64) string {
+	switch {
+	case f >= 1e9:
+		return fmt.Sprintf("%.1fB", f/1e9)
+	case f >= 1e6:
+		return fmt.Sprintf("%.1fM", f/1e6)
+	case f >= 1e3:
+		return fmt.Sprintf("%.1fK", f/1e3)
+	default:
+		return fmt.Sprintf("%.0f", f)
+	}
+}
+
+// rows is "about N rows" with the singular handled.
+func rows(f float64) string {
+	if f == 1 {
+		return "1 row"
+	}
+	return "about " + HumanRows(f) + " rows"
+}
+
+// target names what a scan reads: "orders" or "orders (as o)".
+func (n *Node) target() string {
+	name := n.RelationName
+	if name == "" {
+		name = n.Alias
+	}
+	if n.Alias != "" && n.Alias != n.RelationName && n.RelationName != "" {
+		return name + " (as " + n.Alias + ")"
+	}
+	return name
+}
+
+// Gloss is the node in one plain-English sentence with its row estimate.
+func (n *Node) Gloss() string {
+	r := rows(n.PlanRows)
+	jt := strings.ToLower(n.JoinType)
+	if jt == "" {
+		jt = "inner"
+	}
+	switch n.NodeType {
+	case "Seq Scan":
+		return fmt.Sprintf("reads every row of %s, planner expects %s", n.target(), r)
+	case "Index Scan":
+		return fmt.Sprintf("walks index %s to find rows in %s, then fetches each row from the table; expects %s", n.IndexName, n.target(), r)
+	case "Index Only Scan":
+		return fmt.Sprintf("answers from index %s alone, without visiting the table %s; expects %s", n.IndexName, n.target(), r)
+	case "Bitmap Heap Scan":
+		return fmt.Sprintf("fetches the pages of %s marked in a bitmap by the index scan below; expects %s", n.target(), r)
+	case "Bitmap Index Scan":
+		return fmt.Sprintf("scans index %s and builds a bitmap of matching pages; expects %s", n.IndexName, r)
+	case "BitmapAnd", "BitmapOr":
+		return fmt.Sprintf("combines the bitmaps below (%s)", strings.TrimPrefix(n.NodeType, "Bitmap"))
+	case "Tid Scan":
+		return fmt.Sprintf("fetches rows of %s by physical location; expects %s", n.target(), r)
+	case "Nested Loop":
+		return fmt.Sprintf("%s join: for each row from the outer side, looks up matches on the inner side; expects %s", jt, r)
+	case "Hash Join":
+		return fmt.Sprintf("%s join: builds a hash table from one side and probes it with the other; expects %s", jt, r)
+	case "Merge Join":
+		return fmt.Sprintf("%s join: walks two sorted inputs in step; expects %s", jt, r)
+	case "Hash":
+		return fmt.Sprintf("builds an in-memory hash table from %s", r)
+	case "Sort":
+		return fmt.Sprintf("sorts %s by %s", r, strings.Join(n.SortKey, ", "))
+	case "Incremental Sort":
+		return fmt.Sprintf("sorts %s by %s, reusing input already ordered by %s", r, strings.Join(n.SortKey, ", "), strings.Join(n.PresortedKey, ", "))
+	case "Aggregate":
+		switch n.Strategy {
+		case "Hashed":
+			return fmt.Sprintf("groups by %s using a hash table; expects %s", strings.Join(n.GroupKey, ", "), r)
+		case "Sorted":
+			return fmt.Sprintf("groups by %s over sorted input; expects %s", strings.Join(n.GroupKey, ", "), r)
+		case "Mixed":
+			return fmt.Sprintf("groups by %s, hash and sorted combined; expects %s", strings.Join(n.GroupKey, ", "), r)
+		default:
+			return "computes a single aggregate result over all input rows"
+		}
+	case "Group":
+		return fmt.Sprintf("groups sorted input by %s; expects %s", strings.Join(n.GroupKey, ", "), r)
+	case "WindowAgg":
+		return fmt.Sprintf("evaluates window functions over %s", r)
+	case "Limit":
+		return fmt.Sprintf("stops after %s", r)
+	case "Unique":
+		return fmt.Sprintf("drops adjacent duplicate rows; expects %s", r)
+	case "Gather":
+		return fmt.Sprintf("collects rows from %d parallel workers; expects %s", n.WorkersPlanned, r)
+	case "Gather Merge":
+		return fmt.Sprintf("collects rows from %d parallel workers, preserving sort order; expects %s", n.WorkersPlanned, r)
+	case "Materialize":
+		return fmt.Sprintf("holds %s in memory so they can be re-read", r)
+	case "Memoize":
+		return fmt.Sprintf("caches inner-side lookups by key so repeated keys are not rescanned; expects %s", r)
+	case "Append":
+		return fmt.Sprintf("concatenates the results below (UNION ALL or partitions); expects %s", r)
+	case "Merge Append":
+		return fmt.Sprintf("concatenates the sorted results below, preserving order; expects %s", r)
+	case "Recursive Union":
+		return fmt.Sprintf("iterates a recursive WITH query; expects %s", r)
+	case "WorkTable Scan":
+		return fmt.Sprintf("reads the previous iteration of recursive query %s; expects %s", n.CTEName, r)
+	case "CTE Scan":
+		return fmt.Sprintf("reads the WITH query %s; expects %s", firstNonEmpty(n.CTEName, n.Alias), r)
+	case "Subquery Scan":
+		return fmt.Sprintf("reads the subquery %s; expects %s", n.Alias, r)
+	case "Function Scan":
+		return fmt.Sprintf("calls the function %s and reads its result; expects %s", n.Alias, r)
+	case "Values Scan":
+		return fmt.Sprintf("reads a literal VALUES list; expects %s", r)
+	case "Result":
+		return "returns a constant or a single computed row"
+	case "SetOp":
+		return fmt.Sprintf("applies a set operation (INTERSECT/EXCEPT); expects %s", r)
+	case "ProjectSet":
+		return fmt.Sprintf("expands set-returning functions in the select list; expects %s", r)
+	case "LockRows":
+		return fmt.Sprintf("locks the selected rows (FOR UPDATE/SHARE); expects %s", r)
+	case "Foreign Scan":
+		return fmt.Sprintf("reads %s from a foreign server; expects %s", n.target(), r)
+	default:
+		return fmt.Sprintf("%s; expects %s", n.NodeType, r)
+	}
+}
+
+func firstNonEmpty(vals ...string) string {
+	for _, v := range vals {
+		if v != "" {
+			return v
+		}
+	}
+	return ""
+}
+
+// HasPlaceholders reports whether the query uses $N parameter placeholders
+// outside string literals — the case where a GENERIC_PLAN's "parameter values
+// unknown" caveat applies.
+func HasPlaceholders(q string) bool {
+	inLiteral := false
+	for i := 0; i < len(q); i++ {
+		c := q[i]
+		if c == '\'' {
+			inLiteral = !inLiteral
+			continue
+		}
+		if inLiteral || c != '$' {
+			continue
+		}
+		if i+1 < len(q) && q[i+1] >= '0' && q[i+1] <= '9' {
+			return true
+		}
+	}
+	return false
+}
diff --git a/internal/plan/plan_test.go b/internal/plan/plan_test.go
new file mode 100644
index 0000000..8ea8425
--- /dev/null
+++ b/internal/plan/plan_test.go
@@ -0,0 +1,297 @@
+package plan
+
+import (
+	"strings"
+	"testing"
+)
+
+// fixtureJoin is EXPLAIN (GENERIC_PLAN, FORMAT JSON) for
+//
+//	SELECT c.name, count(*) FROM orders o JOIN customers c ON c.id = o.customer_id
+//	WHERE o.status = $1 GROUP BY c.name ORDER BY 2 DESC
+//
+// shaped the way PostgreSQL 16 emits it: a Sort over a HashAggregate over a
+// Nested Loop whose inner side is a Seq Scan.
+const fixtureJoin = `[
+  {
+    "Plan": {
+      "Node Type": "Sort",
+      "Parallel Aware": false,
+      "Startup Cost": 25000.10,
+      "Total Cost": 25010.20,
+      "Plan Rows": 200,
+      "Plan Width": 40,
+      "Sort Key": ["(count(*)) DESC"],
+      "Plans": [
+        {
+          "Node Type": "Aggregate",
+          "Strategy": "Hashed",
+          "Partial Mode": "Simple",
+          "Parent Relationship": "Outer",
+          "Parallel Aware": false,
+          "Startup Cost": 24000.00,
+          "Total Cost": 24002.00,
+          "Plan Rows": 200,
+          "Plan Width": 40,
+          "Group Key": ["c.name"],
+          "Plans": [
+            {
+              "Node Type": "Nested Loop",
+              "Parent Relationship": "Outer",
+              "Parallel Aware": false,
+              "Join Type": "Inner",
+              "Startup Cost": 0.00,
+              "Total Cost": 23000.00,
+              "Plan Rows": 1500000,
+              "Plan Width": 32,
+              "Inner Unique": true,
+              "Join Filter": "(c.id = o.customer_id)",
+              "Plans": [
+                {
+                  "Node Type": "Index Scan",
+                  "Parent Relationship": "Outer",
+                  "Parallel Aware": false,
+                  "Scan Direction": "Forward",
+                  "Index Name": "orders_status_idx",
+                  "Relation Name": "orders",
+                  "Schema": "public",
+                  "Alias": "o",
+                  "Startup Cost": 0.43,
+                  "Total Cost": 9000.00,
+                  "Plan Rows": 1500000,
+                  "Plan Width": 8,
+                  "Index Cond": "(status = $1)",
+                  "Filter": "(amount > '0'::numeric)"
+                },
+                {
+                  "Node Type": "Seq Scan",
+                  "Parent Relationship": "Inner",
+                  "Parallel Aware": false,
+                  "Relation Name": "customers",
+                  "Schema": "public",
+                  "Alias": "c",
+                  "Startup Cost": 0.00,
+                  "Total Cost": 12.00,
+                  "Plan Rows": 1,
+                  "Plan Width": 36
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  }
+]`
+
+func mustParse(t *testing.T, js string) *Node {
+	t.Helper()
+	n, err := Parse([]byte(js))
+	if err != nil {
+		t.Fatalf("Parse: %v", err)
+	}
+	return n
+}
+
+func TestParse_readsTheTree(t *testing.T) {
+	root := mustParse(t, fixtureJoin)
+	if root.NodeType != "Sort" {
+		t.Fatalf("root = %q, want Sort", root.NodeType)
+	}
+	if got := root.SortKey; len(got) != 1 || got[0] != "(count(*)) DESC" {
+		t.Errorf("sort key = %v", got)
+	}
+	agg := root.Plans[0]
+	if agg.NodeType != "Aggregate" || agg.Strategy != "Hashed" {
+		t.Errorf("agg = %q/%q", agg.NodeType, agg.Strategy)
+	}
+	join := agg.Plans[0]
+	if join.NodeType != "Nested Loop" || join.JoinType != "Inner" || join.PlanRows != 1500000 {
+		t.Errorf("join = %+v", join)
+	}
+	if len(join.Plans) != 2 {
+		t.Fatalf("join children = %d, want 2", len(join.Plans))
+	}
+	outer, inner := join.Plans[0], join.Plans[1]
+	if outer.NodeType != "Index Scan" || outer.IndexName != "orders_status_idx" || outer.IndexCond != "(status = $1)" || outer.Filter == "" {
+		t.Errorf("outer = %+v", outer)
+	}
+	if inner.NodeType != "Seq Scan" || inner.RelationName != "customers" || inner.Alias != "c" || inner.TotalCost != 12 {
+		t.Errorf("inner = %+v", inner)
+	}
+}
+
+func TestParse_rejectsEmptyAndGarbage(t *testing.T) {
+	for _, js := range []string{``, `[]`, `{}`, `not json`} {
+		if _, err := Parse([]byte(js)); err == nil {
+			t.Errorf("Parse(%q) = nil error, want failure", js)
+		}
+	}
+}
+
+func TestGloss_speaksPlainEnglishPerNodeType(t *testing.T) {
+	cases := []struct {
+		node Node
+		want []string // substrings that must appear
+	}{
+		{Node{NodeType: "Seq Scan", RelationName: "orders", PlanRows: 1200000}, []string{"orders", "every row", "1.2M"}},
+		{Node{NodeType: "Index Scan", RelationName: "orders", IndexName: "orders_pkey", PlanRows: 1}, []string{"orders_pkey", "orders", "1 row"}},
+		{Node{NodeType: "Index Only Scan", RelationName: "t", IndexName: "t_idx", PlanRows: 50}, []string{"t_idx", "without", "table"}},
+		{Node{NodeType: "Bitmap Heap Scan", RelationName: "t", PlanRows: 500}, []string{"t", "bitmap"}},
+		{Node{NodeType: "Bitmap Index Scan", IndexName: "t_idx", PlanRows: 500}, []string{"t_idx", "bitmap"}},
+		{Node{NodeType: "Nested Loop", JoinType: "Inner", PlanRows: 10}, []string{"inner join", "each", "outer"}},
+		{Node{NodeType: "Hash Join", JoinType: "Left", PlanRows: 10}, []string{"left join", "hash"}},
+		{Node{NodeType: "Merge Join", JoinType: "Inner", PlanRows: 10}, []string{"inner join", "sorted"}},
+		{Node{NodeType: "Hash", PlanRows: 10}, []string{"hash table"}},
+		{Node{NodeType: "Sort", SortKey: []string{"created_at DESC"}, PlanRows: 10}, []string{"sort", "created_at DESC"}},
+		{Node{NodeType: "Incremental Sort", SortKey: []string{"a", "b"}, PlanRows: 10}, []string{"sort", "already"}},
+		{Node{NodeType: "Aggregate", Strategy: "Hashed", GroupKey: []string{"c.name"}, PlanRows: 10}, []string{"group", "c.name", "hash"}},
+		{Node{NodeType: "Aggregate", Strategy: "Sorted", GroupKey: []string{"x"}, PlanRows: 10}, []string{"group", "sorted"}},
+		{Node{NodeType: "Aggregate", Strategy: "Plain", PlanRows: 1}, []string{"single"}},
+		{Node{NodeType: "Limit", PlanRows: 10}, []string{"stop", "10 rows"}},
+		{Node{NodeType: "Gather", WorkersPlanned: 2, PlanRows: 10}, []string{"2 parallel workers"}},
+		{Node{NodeType: "Gather Merge", WorkersPlanned: 3, PlanRows: 10}, []string{"3 parallel workers", "order"}},
+		{Node{NodeType: "Materialize", PlanRows: 10}, []string{"memory", "re-read"}},
+		{Node{NodeType: "Memoize", PlanRows: 10}, []string{"cache"}},
+		{Node{NodeType: "Append", PlanRows: 10}, []string{"concatenat"}},
+		{Node{NodeType: "Unique", PlanRows: 10}, []string{"duplicate"}},
+		{Node{NodeType: "CTE Scan", Alias: "recent", PlanRows: 10}, []string{"recent", "WITH"}},
+		{Node{NodeType: "Subquery Scan", Alias: "sub", PlanRows: 10}, []string{"subquery"}},
+		{Node{NodeType: "Function Scan", Alias: "generate_series", PlanRows: 10}, []string{"function", "generate_series"}},
+		{Node{NodeType: "Values Scan", PlanRows: 3}, []string{"VALUES"}},
+		{Node{NodeType: "WindowAgg", PlanRows: 3}, []string{"window function"}},
+		{Node{NodeType: "Result", PlanRows: 1}, []string{"constant"}},
+		{Node{NodeType: "Frobnicate Scan", PlanRows: 1}, []string{"Frobnicate Scan"}}, // unknown: name it, don't crash
+	}
+	for _, c := range cases {
+		got := strings.ToLower(c.node.Gloss())
+		for _, w := range c.want {
+			if !strings.Contains(got, strings.ToLower(w)) {
+				t.Errorf("%s gloss %q lacks %q", c.node.NodeType, c.node.Gloss(), w)
+			}
+		}
+	}
+}
+
+func TestHumanRows(t *testing.T) {
+	cases := map[float64]string{0: "0", 1: "1", 999: "999", 1000: "1.0K", 12345: "12.3K", 1200000: "1.2M", 3400000000: "3.4B"}
+	for in, want := range cases {
+		if got := HumanRows(in); got != want {
+			t.Errorf("HumanRows(%v) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func findObs(obs []Observation, sub string) *Observation {
+	for i := range obs {
+		if strings.Contains(strings.ToLower(obs[i].Text), strings.ToLower(sub)) {
+			return &obs[i]
+		}
+	}
+	return nil
+}
+
+func TestObserve_nestedLoopRepeatingInnerScan(t *testing.T) {
+	obs := Observe(mustParse(t, fixtureJoin))
+	o := findObs(obs, "nested loop")
+	if o == nil {
+		t.Fatalf("no nested-loop observation in %+v", obs)
+	}
+	if o.Level != LevelWarn {
+		t.Errorf("level = %q, want warn", o.Level)
+	}
+	for _, w := range []string{"customers", "1.5M"} {
+		if !strings.Contains(o.Text, w) {
+			t.Errorf("observation %q lacks %q", o.Text, w)
+		}
+	}
+}
+
+func TestObserve_indexScanWithPostFilter(t *testing.T) {
+	obs := Observe(mustParse(t, fixtureJoin))
+	o := findObs(obs, "orders_status_idx")
+	if o == nil {
+		t.Fatalf("no post-filter observation in %+v", obs)
+	}
+	if o.Level != LevelInfo || !strings.Contains(o.Text, "amount > '0'::numeric") {
+		t.Errorf("observation = %+v", *o)
+	}
+}
+
+func TestObserve_largeSeqScanWarns_smallOneDoesNot(t *testing.T) {
+	big := &Node{NodeType: "Seq Scan", RelationName: "events", PlanRows: 2500000, Filter: "(kind = $1)"}
+	obs := Observe(big)
+	o := findObs(obs, "events")
+	if o == nil || o.Level != LevelWarn || !strings.Contains(o.Text, "2.5M") || !strings.Contains(o.Text, "kind = $1") {
+		t.Fatalf("big seq scan: %+v", obs)
+	}
+	small := &Node{NodeType: "Seq Scan", RelationName: "countries", PlanRows: 240}
+	if o := findObs(Observe(small), "countries"); o != nil && o.Level == LevelWarn {
+		t.Errorf("small seq scan should not warn: %+v", *o)
+	}
+}
+
+func TestObserve_sortOfManyRows(t *testing.T) {
+	root := &Node{NodeType: "Sort", SortKey: []string{"created_at DESC"}, PlanRows: 400000,
+		Plans: []Node{{NodeType: "Seq Scan", RelationName: "events", PlanRows: 400000}}}
+	o := findObs(Observe(root), "sort")
+	if o == nil || o.Level != LevelInfo || !strings.Contains(o.Text, "created_at DESC") || !strings.Contains(o.Text, "400.0K") {
+		t.Fatalf("sort observation: %+v", Observe(root))
+	}
+}
+
+func TestObserve_quietPlanHasNoObservations(t *testing.T) {
+	root := &Node{NodeType: "Index Scan", RelationName: "users", IndexName: "users_pkey", IndexCond: "(id = $1)", PlanRows: 1}
+	if obs := Observe(root); len(obs) != 0 {
+		t.Errorf("want no observations, got %+v", obs)
+	}
+}
+
+func TestPrepare_buildsPlanOnlyExplain(t *testing.T) {
+	stmt, err := Prepare("SELECT * FROM t WHERE id = $1;", 160000)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if stmt != "EXPLAIN (GENERIC_PLAN, FORMAT JSON) SELECT * FROM t WHERE id = $1" {
+		t.Errorf("pg16 stmt = %q", stmt)
+	}
+	stmt, err = Prepare("select 1", 150000)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if stmt != "EXPLAIN (FORMAT JSON) select 1" {
+		t.Errorf("pg15 stmt = %q", stmt)
+	}
+}
+
+func TestPrepare_refusesAnythingButOneSelect(t *testing.T) {
+	for _, q := range []string{
+		"",
+		"UPDATE t SET a = 1",
+		"DELETE FROM t",
+		"WITH x AS (DELETE FROM t RETURNING *) SELECT * FROM x",
+		"SELECT 1; DROP TABLE t",
+		"SELECT 1; SELECT 2",
+		"EXPLAIN SELECT 1",
+		"selection",
+	} {
+		if _, err := Prepare(q, 160000); err == nil {
+			t.Errorf("Prepare(%q) accepted, want refusal", q)
+		}
+	}
+}
+
+func TestHasPlaceholders(t *testing.T) {
+	yes := []string{"SELECT * FROM t WHERE id = $1", "select $2, $10 from t", "SELECT * FROM t WHERE a=$1AND b=2"}
+	no := []string{"SELECT 1", "SELECT '$1' FROM t", "SELECT '$' || 'x'", "SELECT * FROM t WHERE price > 5$"}
+	for _, q := range yes {
+		if !HasPlaceholders(q) {
+			t.Errorf("HasPlaceholders(%q) = false", q)
+		}
+	}
+	for _, q := range no {
+		if HasPlaceholders(q) {
+			t.Errorf("HasPlaceholders(%q) = true", q)
+		}
+	}
+}
diff --git a/internal/render/plan.go b/internal/render/plan.go
new file mode 100644
index 0000000..f4c17c9
--- /dev/null
+++ b/internal/render/plan.go
@@ -0,0 +1,110 @@
+package render
+
+import (
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/pgrundev/pgbot/internal/plan"
+)
+
+// PlanInput is what `pgbot sql explain` renders: the query, its parsed plan,
+// the deterministic observations, and whether the plan is a GENERIC_PLAN (PG16+,
+// parameter values unknown to the planner).
+type PlanInput struct {
+	Query        string
+	Root         *plan.Node
+	Observations []plan.Observation
+	Generic      bool
+	Color        bool
+}
+
+// Plan writes the human reading of an EXPLAIN plan: an honesty header (nothing
+// was executed), the query, the plan tree with a plain-English gloss per node,
+// what stands out, and the estimate caveat. Everything is derived from the
+// planner's estimates; the text says so where it matters.
+func Plan(w io.Writer, in PlanInput) {
+	st := styler{on: in.Color}
+	fmt.Fprintln(w, st.head("Query plan")+st.dim("  ·  estimates only — the query was planned, not executed"))
+	for _, line := range strings.Split(strings.TrimSpace(in.Query), "\n") {
+		fmt.Fprintln(w, st.dim("  "+line))
+	}
+	fmt.Fprintln(w)
+	if in.Root != nil {
+		writePlanNode(w, st, in.Root, "", true, true)
+	}
+	fmt.Fprintln(w)
+	fmt.Fprintln(w, st.head("What stands out"))
+	if len(in.Observations) == 0 {
+		fmt.Fprintln(w, "  "+st.good("Nothing stands out:")+" the planner expects this query to be cheap.")
+	}
+	for _, o := range in.Observations {
+		mark := st.info("·")
+		if o.Level == plan.LevelWarn {
+			mark = st.warn("!")
+		}
+		fmt.Fprintln(w, "  "+mark+" "+o.Text)
+	}
+	fmt.Fprintln(w)
+	fmt.Fprintln(w, st.dim("Costs and row counts are the planner's estimates, not measurements."))
+	if in.Generic {
+		fmt.Fprintln(w, st.dim("Planned as a generic plan: parameter values ($1, …) were unknown, so the estimates assume typical values."))
+	}
+}
+
+// writePlanNode draws one node and its subtree. prefix is the indentation the
+// parent established; last says whether this is the parent's final child, which
+// decides the branch glyph and whether a vertical rule continues below.
+func writePlanNode(w io.Writer, st styler, n *plan.Node, prefix string, last, root bool) {
+	connector, childPrefix := "", "  "
+	if !root {
+		if last {
+			connector, childPrefix = prefix+"└─ ", prefix+"     "
+		} else {
+			connector, childPrefix = prefix+"├─ ", prefix+"│    "
+		}
+	}
+	fmt.Fprintln(w, connector+st.head(planLabel(n))+st.dim(fmt.Sprintf("  cost=%.2f..%.2f  rows≈%s", n.StartupCost, n.TotalCost, plan.HumanRows(n.PlanRows))))
+	fmt.Fprintln(w, childPrefix+"  "+n.Gloss())
+	for _, c := range []struct{ k, v string }{
+		{"Index Cond", n.IndexCond}, {"Recheck Cond", n.RecheckCond}, {"Hash Cond", n.HashCond},
+		{"Merge Cond", n.MergeCond}, {"Join Filter", n.JoinFilter}, {"Filter", n.Filter},
+	} {
+		if c.v != "" {
+			fmt.Fprintln(w, childPrefix+"  "+st.dim(c.k+": "+c.v))
+		}
+	}
+	for i := range n.Plans {
+		writePlanNode(w, st, &n.Plans[i], childPrefix, i == len(n.Plans)-1, false)
+	}
+}
+
+// planLabel is the node's one-line name: "Seq Scan on orders (as o)",
+// "Index Only Scan on customers using customers_pkey (as c)", "Hash Join (inner)".
+func planLabel(n *plan.Node) string {
+	b := strings.Builder{}
+	b.WriteString(n.NodeType)
+	if n.Strategy != "" && n.NodeType == "Aggregate" {
+		b.WriteString(" (" + strings.ToLower(n.Strategy) + ")")
+	}
+	if n.JoinType != "" {
+		b.WriteString(" (" + strings.ToLower(n.JoinType) + ")")
+	}
+	if n.RelationName != "" {
+		b.WriteString(" on " + n.RelationName)
+	}
+	if n.IndexName != "" {
+		b.WriteString(" using " + n.IndexName)
+	}
+	if n.Alias != "" && n.Alias != n.RelationName {
+		if n.RelationName == "" {
+			b.WriteString(" " + n.Alias)
+		} else {
+			b.WriteString(" (as " + n.Alias + ")")
+		}
+	}
+	if n.ParallelAware {
+		b.WriteString(" [parallel]")
+	}
+	return b.String()
+}
diff --git a/internal/render/plan_test.go b/internal/render/plan_test.go
new file mode 100644
index 0000000..8299a1e
--- /dev/null
+++ b/internal/render/plan_test.go
@@ -0,0 +1,99 @@
+package render
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+
+	"github.com/pgrundev/pgbot/internal/plan"
+)
+
+func planFixture() *plan.Node {
+	return &plan.Node{
+		NodeType: "Hash Join", JoinType: "Inner", HashCond: "(o.customer_id = c.id)", StartupCost: 10.5, TotalCost: 2500.75, PlanRows: 120000,
+		Plans: []plan.Node{
+			{NodeType: "Seq Scan", RelationName: "orders", Alias: "o", Filter: "(status = $1)", TotalCost: 2000, PlanRows: 120000},
+			{NodeType: "Hash", TotalCost: 5, PlanRows: 200, Plans: []plan.Node{
+				{NodeType: "Index Only Scan", RelationName: "customers", Alias: "c", IndexName: "customers_pkey", TotalCost: 4, PlanRows: 200},
+			}},
+		},
+	}
+}
+
+func TestPlan_rendersTreeGlossAndObservations(t *testing.T) {
+	var buf bytes.Buffer
+	root := planFixture()
+	Plan(&buf, PlanInput{
+		Query:        "SELECT * FROM orders o JOIN customers c ON c.id = o.customer_id WHERE o.status = $1",
+		Root:         root,
+		Observations: plan.Observe(root),
+		Generic:      true,
+		Color:        false,
+	})
+	out := buf.String()
+
+	// The honesty header: estimates only, nothing was executed.
+	if !strings.Contains(out, "planned, not executed") {
+		t.Errorf("missing not-executed header:\n%s", out)
+	}
+	// The query itself is echoed so the output stands alone.
+	if !strings.Contains(out, "WHERE o.status = $1") {
+		t.Errorf("query not echoed:\n%s", out)
+	}
+	// Tree: parent before children, children indented deeper than the parent.
+	iJoin := strings.Index(out, "Hash Join")
+	iSeq := strings.Index(out, "Seq Scan on orders")
+	iIdx := strings.Index(out, "Index Only Scan on customers using customers_pkey")
+	if iJoin < 0 || iSeq < 0 || iIdx < 0 || !(iJoin < iSeq && iSeq < iIdx) {
+		t.Fatalf("tree order wrong (%d %d %d):\n%s", iJoin, iSeq, iIdx, out)
+	}
+	if indentOf(out, "Seq Scan on orders") <= indentOf(out, "Hash Join") {
+		t.Errorf("Seq Scan should be indented deeper than Hash Join:\n%s", out)
+	}
+	if indentOf(out, "Index Only Scan on customers") <= indentOf(out, "Hash  ") && indentOf(out, "Index Only Scan on customers") <= indentOf(out, "Seq Scan on orders") {
+		t.Errorf("Index Only Scan should be indented deeper than Hash:\n%s", out)
+	}
+	// Estimates on the node line, gloss and conditions beneath it.
+	for _, want := range []string{
+		"rows≈120.0K", "cost=10.50..2500.75",
+		"reads every row of orders (as o)",
+		"Filter: (status = $1)",
+		"Hash Cond: (o.customer_id = c.id)",
+	} {
+		if !strings.Contains(out, want) {
+			t.Errorf("missing %q:\n%s", want, out)
+		}
+	}
+	// Observations section with the seq-scan warning.
+	if !strings.Contains(out, "What stands out") || !strings.Contains(out, "Seq Scan on orders (as o) reads the whole table") {
+		t.Errorf("observations missing:\n%s", out)
+	}
+	// Generic-plan caveat.
+	if !strings.Contains(out, "generic") {
+		t.Errorf("generic plan caveat missing:\n%s", out)
+	}
+}
+
+func TestPlan_quietPlanSaysSo(t *testing.T) {
+	var buf bytes.Buffer
+	root := &plan.Node{NodeType: "Index Scan", RelationName: "users", IndexName: "users_pkey", IndexCond: "(id = $1)", PlanRows: 1, TotalCost: 8.3}
+	Plan(&buf, PlanInput{Query: "SELECT * FROM users WHERE id = $1", Root: root, Observations: nil})
+	out := buf.String()
+	if !strings.Contains(out, "Nothing stands out") {
+		t.Errorf("quiet plan should say nothing stands out:\n%s", out)
+	}
+	if strings.Contains(out, "generic") {
+		t.Errorf("non-generic plan must not carry the generic caveat:\n%s", out)
+	}
+}
+
+// indentOf returns the column at which marker's line starts printing non-space
+// (tree glyphs count as indentation).
+func indentOf(out, marker string) int {
+	for _, line := range strings.Split(out, "\n") {
+		if i := strings.Index(line, marker); i >= 0 {
+			return i
+		}
+	}
+	return -1
+}