database-documentation

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: database-documentation
version: 0.0.1
license: MIT
description: >-
  Generate grounded-and-verified, engine-agnostic database documentation that reaches 100% parity with the
  real schema. Introspects the LIVE database as ground truth and cross-validates it against ORM models,
  migrations, generated types, seeds, and application queries, then proves completeness by diffing the docs
  back against the database. Produces ER diagrams (mermaid), per-table data dictionaries, and a
  machine-readable schema.json. Works with PostgreSQL, MySQL, SQL Server, and SQLite across any ORM (Prisma,
  TypeORM, Drizzle, Sequelize, Knex, Django, Rails) or raw SQL. Use when asked to document a database,
  produce an ERD or data dictionary, write db/schema docs, audit schema drift, or refresh existing DB docs.
compatibility: >-
  Best results need read access to the live database (via a DB CLI, docker exec, or a connected DB MCP
  server) and, on platforms that support it, parallel subagents. Degrades gracefully without them.
---

# database-documentation

Document a database so completely and accurately that the docs are **provably** the schema, not a
plausible guess at it. A half-correct schema doc is worse than none: people trust it and write broken code.

## The one principle: grounded AND verified

Every statement in the output must be:
- **grounded** — traceable to a concrete source, preferring the **live database** (introspection of the
  system catalog). ORM models, migrations, generated types, and seeds are *claims about* the database, not
  the database; the catalog is what actually runs.
- **verified** — confirmed by re-introspecting the live database and diffing it against the generated docs
  until the diff is empty or every remaining difference is explicitly justified. Never write "documentation
  is complete" — instead make the diff empty and show it.

A frontier model left to itself reads the ORM, writes confident prose, and ships an **incomplete and
partly hallucinated** schema (missed check-constraint enums, wrong `ON DELETE`, omitted legacy tables,
invented columns). This skill exists to defeat exactly that. Two mechanisms do it: (1) the live DB is the
oracle, and (2) judgment is never one agent's call — independent adversaries hunt for what one pass misses.

## Scope (v1): relational/SQL only

Targets PostgreSQL, MySQL, SQL Server, SQLite. If you detect a document store (MongoDB) or graph database,
**say so and stop on that store** — do not emit relational docs for it (silent mis-documentation is the
worst outcome). Note it as out of scope rather than guessing.

## Workflow

Run these phases in order. Each names its exit artifact. Keep all scratch (intermediate extractions, the
working CSM) in a single `.database-documentation/` scratch dir or your platform scratchpad — the **only durable
deliverables are the docs and `schema.json`**.

### Phase 0 — Discover (read-only)

1. **Fingerprint** the engine + version and the ORM(s): look for `schema.prisma`, `*.entity.ts` +
   datasource, `drizzle.config.*`, `knexfile.*` + `migrations/`, Django `models.py`, Rails `schema.rb`,
   raw SQL DDL. Find the engine + version from the datasource/provider, `docker-compose.yml` image tags,
   and connection URLs in `.env*`.
2. **Find the live-DB reachability path**, trying in this order and stopping at the first that works:
   a connected **DB MCP server** → **`docker compose exec` / `docker exec`** into the DB container (read
   creds from compose env) → a **local DB CLI** (`psql`/`mysql`/`sqlcmd`/`sqlite3`) against host:port from
   `.env`. **Prove it** with one trivial query (`SELECT 1`, list tables) before continuing. If the DB is
   down but a compose file defines it, offer to start it. **Never print credentials**: treat passwords/DSNs
   read from `.env`/compose as secrets — keep them only in the command you execute, and **redact them**
   (`password=***`) in anything you show or write to the docs.
3. **Inventory every other sur