kozou docs

kozou docs は PostgreSQL スキーマを一度読み取り（CREATE TABLE・ CREATE VIEW・COMMENT ON テキスト）、それを記述する単一の Markdown ドキュメントを emit します。Kozou の他の面と同様に read-only・ステートレス で、スキーマを問い合わせて Markdown を書くだけ、データベースには書き込みません。

これは Admin UI・MCP・REST 面の背後にある同じ Schema Context のドキュメント形です。そのため生成された docs は、エージェントや API が見るものと乖離しません。

構文

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

フラグなしでは Markdown を stdout に書きます。ファイルにリダイレクトするか、 --output を使います。

kozou docs --output schema.md

何が出力されるか

kozou.config.yaml で設定したスキーマについて、ドキュメントには次が含まれます。

すべてのテーブル — 列（型・主キー・外部キー・NULL 許容性・CHECK 制約）と、COMMENT の説明・@ai / @policy ノート（列ごとのノートを含む）。
すべてのビュー — 列・目的・依存先テーブル・SQL 定義。source-of-truth なビューが第一級の概念として読めます。
テーブルごとの Security セクション — Kozou をあるロールに向けると (introspection.respectPrivileges)そのロールの実効 GRANT、そして既定で 行レベルセキュリティのシグナル（RLS が enabled / forced / ポリシー有りか）。advisory のみ — 施行は PostgreSQL に残ります。AI 面での同じシグナルは Connect MCP を参照してください。
ER 図 — 次で説明します。

ER 図

v1.12 以降、ドキュメントは冒頭に ## Entity-relationship diagram セクションを持ち、Mermaid の erDiagram ブロックを含みます。Mermaid はテキストなので、GitHub・kozou.org・多くの Markdown ビューアがネイティブにレンダーします — Kozou 自身はレイアウトエンジンを持ちません。

これは意味を載せた図であり、素の外部キーグラフではありません。

テーブルとビューの両方がエンティティ。 ビュー（Kozou の名前付き業務概念）は、その基礎となるテーブルへ点線の “derives from” エッジで結ばれ、 source-of-truth なビューがそれと分かります。
列は属性として型と PK / FK マーカーを携えます。（timestamp with time zone のように空白を含む型は、Mermaid で有効に保つため timestamp_with_time_zone に畳まれます。正確な型はテーブル一覧に残ります。）
外部キーは crow’s-foot エッジで、その多重度はスキーマを反映します。 NOT NULL の外部キーは多対一（||--o{）、nullable なものはゼロか一対多（|o--o{）、UNIQUE な外部キーは一対一（||--o|）。各エッジは外部キー列でラベル付けされます。
図の下に 凡例とエンティティ単位の @ai / @policy ノートブロックが並び、スキーマの意味が構造と同居します。

図は既存の Schema Context だけから構築されます — read-only・ステートレス・新しい introspection クエリなしです。

小さなスキーマは次のようにレンダーされます。

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

フラグ

フラグ	引数	既定	説明
`--output`	`<path>`	`-`	出力ファイル（`-` で stdout）。
`--config`	`<path>`	—	`kozou.config.yaml` のパス。

例

チェックインするスキーマドキュメントを生成します。

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

結果は単一の Markdown ファイル（図、続いて各テーブルとビューがその意味とともに）で、GitHub や任意の Markdown ビューアでレンダーされます。内容を形作るにはデータベースに書きます。COMMENT の規約を参照してください。