feat: pgcrate brief — whole database in one dense screen (PGC-100)

schemas/brief.schema.json

@@ -0,0 +1,144 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "pgcrate.brief",
+  "title": "pgcrate brief output",
+  "description": "Whole-database orientation: target, schemas/tables/estimated rows, relationships, migrations, extensions, and at-a-glance health flags. Catalog-only, never count(*).",
+  "allOf": [
+    { "$ref": "envelope.schema.json" }
+  ],
+  "properties": {
+    "schema_id": { "const": "pgcrate.brief" },
+    "data": { "$ref": "#/$defs/briefData" }
+  },
+  "$defs": {
+    "briefData": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["target", "server", "schemas", "relationships", "extensions", "health"],
+      "properties": {
+        "target": { "$ref": "#/$defs/targetInfo" },
+        "server": { "$ref": "#/$defs/serverInfo" },
+        "schemas": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/schemaBrief" },
+          "description": "Non-system schemas and the tables they hold"
+        },
+        "relationships": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/relationshipBrief" },
+          "description": "Foreign-key edges collapsed to child -> {parents}"
+        },
+        "migrations": {
+          "$ref": "#/$defs/migrationsBrief",
+          "description": "Migration state; omitted entirely when no migrations directory resolves"
+        },
+        "extensions": {
+          "type": "array",
+          "items": {
+            "type": "array",
+            "prefixItems": [
+              { "type": "string", "description": "extension name" },
+              { "type": "string", "description": "installed version" }
+            ],
+            "items": false,
+            "minItems": 2,
+            "maxItems": 2
+          },
+          "description": "Installed extensions as [name, version] pairs, sorted by name"
+        },
+        "health": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/healthFlag" },
+          "description": "At-a-glance health flags. Displayed, not scored — severity stays healthy."
+        }
+      }
+    },
+    "targetInfo": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["host", "port", "database", "user", "readonly"],
+      "properties": {
+        "host": { "type": "string", "description": "Host (redacted by default)" },
+        "port": { "type": "integer", "minimum": 1, "maximum": 65535 },
+        "database": { "type": "string" },
+        "user": { "type": "string" },
+        "readonly": { "type": "boolean" }
+      }
+    },
+    "serverInfo": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version", "version_num", "version_major", "in_recovery"],
+      "properties": {
+        "version": { "type": "string" },
+        "version_num": { "type": "integer" },
+        "version_major": { "type": "integer" },
+        "in_recovery": { "type": "boolean" },
+        "data_directory": { "type": "string", "description": "Only with --no-redact" }
+      }
+    },
+    "schemaBrief": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "tables"],
+      "properties": {
+        "name": { "type": "string" },
+        "tables": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/tableBrief" }
+        }
+      }
+    },
+    "tableBrief": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema", "name", "est_rows", "size", "size_bytes"],
+      "properties": {
+        "schema": { "type": "string" },
+        "name": { "type": "string" },
+        "est_rows": {
+          "type": ["integer", "null"],
+          "description": "Estimated live rows from reltuples; null when never analyzed (reltuples is -1)"
+        },
+        "size": { "type": "string", "description": "Total relation size, pg_size_pretty form" },
+        "size_bytes": { "type": "integer", "description": "Total relation size in bytes" }
+      }
+    },
+    "relationshipBrief": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["child", "parents"],
+      "properties": {
+        "child": { "type": "string", "description": "schema.table that holds the FK" },
+        "parents": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Referenced schema.table(s)"
+        }
+      }
+    },
+    "migrationsBrief": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["applied", "pending"],
+      "properties": {
+        "applied": { "type": "integer", "minimum": 0 },
+        "pending": { "type": "integer", "minimum": 0 },
+        "pending_versions": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Pending versions, listed only when pending <= 5"
+        }
+      }
+    },
+    "healthFlag": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "detail"],
+      "properties": {
+        "kind": { "type": "string", "description": "e.g. sequence, xid" },
+        "detail": { "type": "string" }
+      }
+    }
+  }
+}

skill/SKILL.md

@@ -45,6 +45,7 @@ exhaustive reference; this skill is the *when/why*, that flag is the *what*.
 ## Session start — orient before you act
 
 ```bash
+pgcrate brief            # whole DB in one screen: schemas → tables → est. rows, FKs, migrations, hazards
 pgcrate context          # connection, server version, extensions, privileges, read/write mode
 pgcrate capabilities     # what you're actually allowed to do here
 pgcrate inspect table <schema.name>   # columns, indexes, constraints, stats
@@ -53,9 +54,20 @@ pgcrate inspect roles            # roles/users; add --describe <name> for one
 pgcrate inspect extensions       # installed extensions (--available for the rest)
 ```
 
-Run `context` first on an unfamiliar database — it tells you the PG version,
-whether you're on a replica, and whether you even have permission for the
-diagnostics below. (A one-shot `brief` summary command is coming; not available yet.)
+**Run `brief` first on an unfamiliar database.** It's the one command that
+orients you in a single shot: which instance you're on (db/host/port/user/mode —
+check this before you touch anything; the worst mistake is the right query on the
+wrong instance), every non-system schema with its tables and *estimated* row
+counts (`reltuples`, never `count(*)` — so it's sub-second and never scans), the
+foreign-key graph in compact `child → parents` form, migration state (applied N /
+pending M) when a `pgcrate.toml` resolves, installed extensions + server version,
+and any cheap at-a-glance hazards (sequence exhaustion, XID age). It's catalog-only
+and read-only; health flags are *shown, not scored* (it always exits `0` — for a
+scored health pass use `dba triage`). `--json` gives the full, uncapped structure
+(`schema_id: pgcrate.brief`); human output caps long schemas to the largest tables.
+
+`context` drills into the connection/server/privilege detail when you need it
+(e.g. confirming you have permission for the diagnostics below).
 
 ## Querying
 
@@ -217,6 +229,7 @@ Every `fix` supports `--dry-run` (preview) and `--verify` (re-check after). Run
 
 | Goal | Command |
 |------|---------|
+| Orient on an unfamiliar DB (run first) | `pgcrate brief` |
 | Connection + server + privileges | `pgcrate context` |
 | What I'm allowed to do | `pgcrate capabilities` |
 | Describe a table | `pgcrate inspect table <name>` |