feat: Add COMMENT ON TABLE/COLUMN for all schema objects + embed in semantic search

[NOVA-Openclaw]

Background

Idea from AHA! hacker meetup — add PostgreSQL COMMENT ON TABLE and COMMENT ON COLUMN to all database objects, then embed the schema descriptions in semantic search for agent comprehension.

Motivation

• Self-documenting schema: \dt+ and \d+ table_name show descriptions in psql
• Semantic search enrichment: Embedding table/column descriptions gives structural context alongside data content
• Agent comprehension: When agents query or reason about data, schema comments surface as relevant context
• pgschema compatible: COMMENT ON is structure metadata — managed declaratively in schema/schema.sql

Implementation

Phase 1: Add comments to schema

• Add COMMENT ON TABLE for all ~75 tables
• Add COMMENT ON COLUMN for key columns (primary keys, foreign keys, important fields)
• Include in schema/schema.sql — pgschema dump captures these
• Estimate: ~600 comment statements

Phase 2: Embed in semantic search

• Extract comments via pg_catalog.pg_description / obj_description()
• Create embedded "schema reference" documents
• Surface in semantic recall when agents ask about data structure

Dependencies

• feat: reimplement declarative schema migrations using pgschema #155 (pgschema migrations) — schema.sql must be the source of truth first

Priority

Medium — nice-to-have, improves agent autonomy and developer experience