kozou docs

kozou docs reads your PostgreSQL schema once — the CREATE TABLE, CREATE VIEW, and COMMENT ON text — and emits a single Markdown document describing it. Like every Kozou surface it is read-only and stateless: it queries the schema and writes Markdown, never the database.

It is the documentation form of the same Schema Context behind the Admin UI, MCP, and REST surfaces, so the generated docs never drift from what an agent or the API sees.

Synopsis

kozou docs [--output <path>] [--config <path>]

With no flags it writes Markdown to stdout. Redirect it to a file, or use --output:

kozou docs --output schema.md

What it emits

For the schemas configured in your kozou.config.yaml, the document includes:

• Every table — its columns (type, primary key, foreign keys, nullability, CHECK constraints) and the description and @ai / @policy notes from its COMMENT, including per-column notes.
• Every view — its columns, purpose, the tables it depends on, and its SQL definition, so a source-of-truth view reads as a first-class concept.
• A per-table Security section — when you point Kozou at a role (introspection.respectPrivileges), the role’s effective GRANTs; and, on by default, a row-level-security signal (whether RLS is enabled / forced / has a policy). Advisory only — enforcement stays in PostgreSQL. See Connect MCP for the same signals on the AI surface.
• An entity-relationship diagram — described next.

The entity-relationship diagram

Since v1.12, the document opens with an ## Entity-relationship diagram section containing a Mermaid erDiagram block. Because Mermaid is text, GitHub, kozou.org, and most Markdown viewers render it natively — Kozou carries no layout engine of its own.

It is meaning-laden, not a bare foreign-key graph:

• Tables and views are entities. A view — Kozou’s named business concept — is linked to the tables it is built on by a dotted “derives from” edge, so a source-of-truth view is visible as such.
• Columns are attributes carrying their type and PK / FK markers. (A type containing spaces, like timestamp with time zone, is folded to timestamp_with_time_zone to stay valid in Mermaid; the precise type stays in the table listing.)
• Foreign keys are crow’s-foot edges whose cardinality reflects the schema: a NOT NULL foreign key is many-to-one (||--o{), a nullable one is zero-or-one to many (|o--o{), and a UNIQUE foreign key is one-to-one (||--o|). Each edge is labelled with the foreign-key column.
• A legend plus an entity-level @ai / @policy notes block sits under the diagram, so the schema’s meaning is co-located with its structure.

The diagram is built entirely from the existing Schema Context — read-only, stateless, and with no new introspection queries.

A small schema renders like this:

erDiagram
  authors {
    uuid id PK
    timestamp_with_time_zone deleted_at
  }
  books {
    uuid id PK
    uuid author_id FK
  }
  authors ||--o{ books : "author_id"

Flags

Flag	Argument	Default	Description
--output	<path>	-	Output file (- for stdout).
--config	<path>	—	Path to kozou.config.yaml.

Example

Generate a checked-in schema document:

DATABASE_URL=postgres://kozou:kozou@localhost:5432/kozou \
  kozou docs --output docs/schema.md

The result is a single Markdown file — the diagram, then every table and view with its meaning — that renders on GitHub or any Markdown viewer. To shape what it says, write it in the database: see COMMENT conventions.