sqlprism 1.1.0__tar.gz → 1.2.0__tar.gz

{sqlprism-1.1.0 → sqlprism-1.2.0}/.github/workflows/docs.yml

@@ -37,10 +37,10 @@ jobs:
         run: uv run mkdocs build
 
       - name: Upload Pages artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v4
         with:
           path: site/
 
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

{sqlprism-1.1.0 → sqlprism-1.2.0}/CLAUDE.md

@@ -18,17 +18,20 @@ src/sqlprism/
   core/
     graph.py       — DuckDB storage layer (MVCC, repo_type tracking)
     indexer.py      — Orchestrates parsing + indexing; file-level reindex with repo-type dispatch
-    mcp_tools.py   — MCP server tools (19 tools, non-blocking reindex, per-repo debounce)
+    mcp_tools.py   — MCP server tools (24 tools, non-blocking reindex, per-repo debounce)
+    conventions.py — Convention inference engine (layers, naming, references, tags, overrides)
   languages/
     sql.py         — sqlglot-based SQL parser
     dbt.py         — dbt renderer (full project + selective render_models)
     sqlmesh.py     — sqlmesh renderer (full project + selective render_models)
     utils.py       — Shared venv/env utilities
   types.py         — Data classes (ParseResult, NodeResult, etc.)
-  cli.py           — Click CLI (serve, reindex, reindex-file, reindex-sqlmesh, reindex-dbt, status, init)
+  cli.py           — Click CLI (serve, reindex, reindex-file, reindex-sqlmesh, reindex-dbt, conventions, status, init)
 tests/
-  test_indexer.py  — Indexer + integration tests
-  test_renderers.py — dbt/sqlmesh renderer tests
+  test_indexer.py    — Indexer + integration tests
+  test_renderers.py  — dbt/sqlmesh renderer tests
+  test_conventions.py — Convention engine + placement + tags tests
+  test_sql_parser.py — SQL parser, lineage, and dialect tests
 ```
 
 ## Conventions

{sqlprism-1.1.0 → sqlprism-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlprism
-Version: 1.1.0
+Version: 1.2.0
 Summary: SQL codebase indexer with column-level lineage, impact analysis, and MCP server support
 Project-URL: Homepage, https://github.com/darkcofy/sqlprism
 Project-URL: Documentation, https://darkcofy.github.io/sqlprism/
@@ -23,7 +23,7 @@ Requires-Dist: duckdb>=1.5.0
 Requires-Dist: mcp[cli]>=1.0.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: pyyaml>=6.0
-Requires-Dist: sqlglot<30,>=28.0.0
+Requires-Dist: sqlglot[c]<31,>=30.0.0
 Description-Content-Type: text/markdown
 
 # SQLPrism
@@ -225,6 +225,9 @@ Full reference: [CLI guide](https://darkcofy.github.io/sqlprism/guide/cli/)
 | `sqlprism reindex-dbt` | Compile and index a [dbt](https://www.getdbt.com/) project. |
 | `sqlprism reindex-sqlmesh` | Render and index a [SQLMesh](https://sqlmesh.com/) project. |
 | `sqlprism serve` | Start the MCP server (stdio or HTTP). |
+| `sqlprism conventions init` | Generate `sqlprism.conventions.yml` from inferred conventions. |
+| `sqlprism conventions refresh` | Re-run convention inference after reindex. |
+| `sqlprism conventions diff` | Show what changed since last `--init`. |
 | `sqlprism status` | Show index status. |
 | `sqlprism query search` | Find entities by name pattern. |
 | `sqlprism query references` | Find inbound/outbound dependencies. |
@@ -236,7 +239,7 @@ Full reference: [CLI guide](https://darkcofy.github.io/sqlprism/guide/cli/)
 
 Full reference: [MCP tools guide](https://darkcofy.github.io/sqlprism/guide/mcp-tools/)
 
-When running as an MCP server (`sqlprism serve`), 19 tools are exposed:
+When running as an MCP server (`sqlprism serve`), 24 tools are exposed:
 
 | Tool | Description |
 |---|---|
@@ -258,6 +261,11 @@ When running as an MCP server (`sqlprism serve`), 19 tools are exposed:
 | `reindex_files` | Fast on-save reindex with per-repo debounce. |
 | `reindex_dbt` | Background dbt compile + index. |
 | `reindex_sqlmesh` | Background SQLMesh render + index. |
+| `get_conventions` | Inferred project conventions — naming, references, columns. |
+| `find_similar_models` | Find existing models similar to what you're building. |
+| `suggest_placement` | Recommend where to place a new model based on references. |
+| `search_by_tag` | Find models by semantic tag (business domain concept). |
+| `list_tags` | List all semantic tags with model counts and confidence. |
 | `index_status` | Index stats, cross-repo edges, and name collisions. |
 
 ## Architecture
@@ -274,8 +282,9 @@ src/sqlprism/
   core/
     graph.py            <- DuckDB storage layer (MVCC), queries, snippets, repo_type tracking
     indexer.py          <- Orchestrator: scan -> checksum -> parse -> store; file-level reindex with repo-type dispatch
-    mcp_tools.py        <- FastMCP tool definitions (19 tools, non-blocking reindex, per-repo debounce)
-  cli.py                <- Click CLI: serve, reindex, reindex-file, reindex-sqlmesh, reindex-dbt, status, init
+    mcp_tools.py        <- FastMCP tool definitions (24 tools, non-blocking reindex, per-repo debounce)
+    conventions.py      <- Convention inference engine: layers, naming, references, tags, overrides
+  cli.py                <- Click CLI: serve, reindex, reindex-file, reindex-sqlmesh, reindex-dbt, conventions, status, init
 ```
 
 The SQL parser extracts:
@@ -294,7 +303,7 @@ SQLPrism optionally integrates with [DuckPGQ](https://github.com/cwida/duckpgq)
 
 ```bash
 uv sync
-uv run pytest                          # run tests (416+ tests)
+uv run pytest                          # run tests (510+ tests)
 uv run pytest --cov=sqlprism           # run with coverage report
 uv run pytest --cov=sqlprism --cov-report=html:coverage_html  # HTML report
 ```

{sqlprism-1.1.0 → sqlprism-1.2.0}/README.md

@@ -197,6 +197,9 @@ Full reference: [CLI guide](https://darkcofy.github.io/sqlprism/guide/cli/)
 | `sqlprism reindex-dbt` | Compile and index a [dbt](https://www.getdbt.com/) project. |
 | `sqlprism reindex-sqlmesh` | Render and index a [SQLMesh](https://sqlmesh.com/) project. |
 | `sqlprism serve` | Start the MCP server (stdio or HTTP). |
+| `sqlprism conventions init` | Generate `sqlprism.conventions.yml` from inferred conventions. |
+| `sqlprism conventions refresh` | Re-run convention inference after reindex. |
+| `sqlprism conventions diff` | Show what changed since last `--init`. |
 | `sqlprism status` | Show index status. |
 | `sqlprism query search` | Find entities by name pattern. |
 | `sqlprism query references` | Find inbound/outbound dependencies. |
@@ -208,7 +211,7 @@ Full reference: [CLI guide](https://darkcofy.github.io/sqlprism/guide/cli/)
 
 Full reference: [MCP tools guide](https://darkcofy.github.io/sqlprism/guide/mcp-tools/)
 
-When running as an MCP server (`sqlprism serve`), 19 tools are exposed:
+When running as an MCP server (`sqlprism serve`), 24 tools are exposed:
 
 | Tool | Description |
 |---|---|
@@ -230,6 +233,11 @@ When running as an MCP server (`sqlprism serve`), 19 tools are exposed:
 | `reindex_files` | Fast on-save reindex with per-repo debounce. |
 | `reindex_dbt` | Background dbt compile + index. |
 | `reindex_sqlmesh` | Background SQLMesh render + index. |
+| `get_conventions` | Inferred project conventions — naming, references, columns. |
+| `find_similar_models` | Find existing models similar to what you're building. |
+| `suggest_placement` | Recommend where to place a new model based on references. |
+| `search_by_tag` | Find models by semantic tag (business domain concept). |
+| `list_tags` | List all semantic tags with model counts and confidence. |
 | `index_status` | Index stats, cross-repo edges, and name collisions. |
 
 ## Architecture
@@ -246,8 +254,9 @@ src/sqlprism/
   core/
     graph.py            <- DuckDB storage layer (MVCC), queries, snippets, repo_type tracking
     indexer.py          <- Orchestrator: scan -> checksum -> parse -> store; file-level reindex with repo-type dispatch
-    mcp_tools.py        <- FastMCP tool definitions (19 tools, non-blocking reindex, per-repo debounce)
-  cli.py                <- Click CLI: serve, reindex, reindex-file, reindex-sqlmesh, reindex-dbt, status, init
+    mcp_tools.py        <- FastMCP tool definitions (24 tools, non-blocking reindex, per-repo debounce)
+    conventions.py      <- Convention inference engine: layers, naming, references, tags, overrides
+  cli.py                <- Click CLI: serve, reindex, reindex-file, reindex-sqlmesh, reindex-dbt, conventions, status, init
 ```
 
 The SQL parser extracts:
@@ -266,7 +275,7 @@ SQLPrism optionally integrates with [DuckPGQ](https://github.com/cwida/duckpgq)
 
 ```bash
 uv sync
-uv run pytest                          # run tests (416+ tests)
+uv run pytest                          # run tests (510+ tests)
 uv run pytest --cov=sqlprism           # run with coverage report
 uv run pytest --cov=sqlprism --cov-report=html:coverage_html  # HTML report
 ```

sqlprism-1.2.0/docs/api/conventions.md

@@ -0,0 +1,23 @@
+# Convention Engine
+
+The convention inference engine detects project patterns from the indexed SQL graph — naming conventions, layer references, required columns, column style, and semantic tags.
+
+## ConventionEngine
+
+::: sqlprism.core.conventions.ConventionEngine
+
+## Data Classes
+
+::: sqlprism.core.conventions.Layer
+
+::: sqlprism.core.conventions.NamingPattern
+
+::: sqlprism.core.conventions.ReferenceRule
+
+::: sqlprism.core.conventions.RequiredColumn
+
+::: sqlprism.core.conventions.ColumnStyle
+
+::: sqlprism.core.conventions.TagAssignment
+
+::: sqlprism.core.conventions.Cluster

{sqlprism-1.1.0 → sqlprism-1.2.0}/docs/architecture/schema.md

@@ -2,7 +2,7 @@
 
 The index is stored in a single DuckDB file (default: `~/.sqlprism/graph.duckdb`). Current schema version: **1.0**.
 
-## Tables (6)
+## Tables (9)
 
 ### `repos`
 
@@ -99,6 +99,51 @@ End-to-end column lineage chains.
 
 A lineage chain traces one output column back to its source. Multiple chains (different `chain_index` values) exist when a column has multiple source paths (e.g. COALESCE of two columns).
 
+### `columns`
+
+Column definitions extracted from DDL or schema files.
+
+| Column | Type | Description |
+|---|---|---|
+| `column_id` | INTEGER PK | Auto-increment ID. |
+| `node_id` | INTEGER | FK to `nodes`. |
+| `column_name` | TEXT | Column name. |
+| `data_type` | TEXT or NULL | Column data type (e.g. `INTEGER`, `TEXT`). |
+| `position` | INTEGER | Column ordinal position in the table. |
+| `source` | TEXT | How the column was discovered: `definition`, `usage`, `lineage`. |
+
+### `conventions`
+
+Inferred or overridden project conventions per layer.
+
+| Column | Type | Description |
+|---|---|---|
+| `convention_id` | INTEGER PK | Auto-increment ID. |
+| `repo_id` | INTEGER | FK to `repos`. |
+| `layer` | TEXT | Layer name (e.g. `staging`, `marts`). |
+| `convention_type` | TEXT | `naming`, `references`, `required_columns`, or `column_style`. |
+| `payload` | JSON | Convention data (pattern, allowed_targets, etc.). |
+| `confidence` | FLOAT | Confidence score (0.0-1.0). |
+| `source` | TEXT | `inferred` or `override`. |
+| `model_count` | INTEGER | Number of models in this layer when inferred. |
+
+Unique constraint: `(repo_id, layer, convention_type)`.
+
+### `semantic_tags`
+
+Semantic tags assigned to models by clustering or explicit override.
+
+| Column | Type | Description |
+|---|---|---|
+| `tag_id` | INTEGER PK | Auto-increment ID. |
+| `repo_id` | INTEGER | FK to `repos`. |
+| `tag_name` | TEXT | Tag name (e.g. `customer`, `order`, `revenue`). |
+| `node_id` | INTEGER | FK to `nodes`. |
+| `confidence` | FLOAT | Confidence score (0.0-1.0). |
+| `source` | TEXT | `inferred`, `anchor`, or `explicit`. |
+
+Unique constraint: `(repo_id, tag_name, node_id)`.
+
 ## Indexes
 
 ```sql
@@ -117,6 +162,11 @@ CREATE INDEX idx_col_usage_type ON column_usage(usage_type);
 CREATE INDEX idx_lineage_output ON column_lineage(output_node, output_column);
 CREATE INDEX idx_lineage_hop ON column_lineage(hop_table, hop_column);
 CREATE INDEX idx_lineage_file ON column_lineage(file_id);
+CREATE INDEX idx_conventions_repo ON conventions(repo_id);
+CREATE INDEX idx_conventions_type ON conventions(convention_type);
+CREATE INDEX idx_tags_name ON semantic_tags(tag_name);
+CREATE INDEX idx_tags_node ON semantic_tags(node_id);
+CREATE INDEX idx_tags_repo ON semantic_tags(repo_id);
 ```
 
 ## Entity Relationship
@@ -130,4 +180,7 @@ repos 1──* files 1──* nodes
 
 files 1──* column_usage *──1 nodes
 files 1──* column_lineage
+nodes 1──* columns
+repos 1──* conventions
+repos 1──* semantic_tags *──1 nodes
 ```

{sqlprism-1.1.0 → sqlprism-1.2.0}/docs/guide/cli.md

@@ -34,7 +34,7 @@ sqlprism status [--config PATH] [--db PATH]
 
 ### `sqlprism serve`
 
-Starts the MCP server, exposing all 19 tools to any MCP client.
+Starts the MCP server, exposing all 24 tools to any MCP client.
 
 ```bash
 sqlprism serve [--config PATH] [--db PATH] [--transport stdio|streamable-http] [--port 8000]
@@ -130,6 +130,36 @@ sqlprism reindex-dbt \
 | `--profiles-dir` | No | Path to directory containing `profiles.yml`. Defaults to the project directory. |
 | `--dbt-command` | No | Base command to invoke dbt. `compile` is appended automatically. Default: `uv run dbt`. Use `dbt` if globally installed, or `uvx --with dbt-starrocks dbt` for ephemeral install. |
 
+## Convention Commands
+
+### `sqlprism conventions init`
+
+Generate a `sqlprism.conventions.yml` file from inferred conventions. Includes confidence scores as comments.
+
+```bash
+sqlprism conventions init [--config PATH] [--db PATH] [--force]
+```
+
+| Parameter | Description |
+|---|---|
+| `--force` | Overwrite existing conventions file. Without this flag, init refuses to overwrite. |
+
+### `sqlprism conventions refresh`
+
+Re-run convention inference after reindex. Preserves explicit overrides (source: 'override').
+
+```bash
+sqlprism conventions refresh [--config PATH] [--db PATH]
+```
+
+### `sqlprism conventions diff`
+
+Show what conventions changed since the last `init`. Compares the YAML file against current inferred conventions.
+
+```bash
+sqlprism conventions diff [--config PATH] [--db PATH]
+```
+
 ## Query Commands
 
 All query commands output JSON to stdout. They share common parameters:

sqlprism-1.2.0/docs/guide/conventions.md

@@ -0,0 +1,82 @@
+# Conventions
+
+The conventions engine automatically infers project patterns from the indexed SQL graph -- naming conventions, layer references, required columns, column naming style, and semantic tags. It runs after every reindex, giving AI agents (and developers) a machine-readable description of how the project is structured.
+
+## How It Works
+
+- Convention inference runs automatically after reindex.
+- Detects layers from directory structure (`models/staging/`, `models/marts/`, etc.).
+- Infers naming patterns per layer (e.g. `stg_{source}_{entity}`).
+- Infers reference rules (which layers reference which).
+- Detects required columns (columns appearing in >70% of models per layer).
+- Detects column naming style (`snake_case`, `camelCase`, etc.).
+- Assigns semantic tags via structural clustering (no ML, deterministic).
+
+## Confidence Scores
+
+All conventions have a confidence score (0.0--1.0):
+
+| Range | Meaning |
+|---|---|
+| **>0.9** | High confidence. Follow this convention. |
+| **0.7--0.9** | Moderate. Likely correct but worth verifying. |
+| **<0.7** | Low confidence. Consider an explicit override. |
+
+## Overrides
+
+You can override inferred conventions with a YAML file:
+
+```bash
+sqlprism conventions init      # generates sqlprism.conventions.yml
+# edit the file to add explicit overrides
+sqlprism conventions refresh   # re-runs inference, preserving overrides
+sqlprism conventions diff      # shows changes since last init
+```
+
+Overrides take precedence over inferred conventions (`source: 'override'` vs `source: 'inferred'`).
+
+## MCP Tools
+
+Five MCP tools expose conventions to AI agents:
+
+| Tool | Description |
+|---|---|
+| `get_conventions` | Naming rules, reference rules, required columns per layer. |
+| `find_similar_models` | Find existing models similar to what you're building. |
+| `suggest_placement` | Recommend where to place a new model based on references. |
+| `search_by_tag` | Find models by semantic tag (business domain concept). |
+| `list_tags` | List all semantic tags with model counts and confidence. |
+
+See [MCP Tools](mcp-tools.md) for parameter details.
+
+## Semantic Tags
+
+Tags are assigned by structural clustering -- models that share many upstream references get grouped and auto-labeled based on common name tokens. Tags represent business domain concepts (e.g. "customer", "order", "revenue").
+
+Tag sources:
+
+| Source | Description |
+|---|---|
+| **inferred** | Automatically assigned via clustering. |
+| **anchor** | Manually specified in the YAML override as cluster anchors. |
+| **explicit** | Manually assigned to specific models in the YAML override. |
+
+## Example Workflow
+
+```bash
+# 1. Index your project
+sqlprism reindex
+
+# 2. Generate conventions file
+sqlprism conventions init
+# -> creates sqlprism.conventions.yml with inferred conventions
+
+# 3. Review and adjust
+# Edit the YAML to fix any conventions the engine got wrong
+
+# 4. Re-run inference (preserves your overrides)
+sqlprism conventions refresh
+
+# 5. Check what changed
+sqlprism conventions diff
+```

{sqlprism-1.1.0 → sqlprism-1.2.0}/docs/guide/mcp-tools.md

@@ -1,6 +1,6 @@
 # MCP Tools
 
-When running as an MCP server (`sqlprism serve`), 19 tools are exposed. Any MCP client (Claude Code, Claude Desktop, Cursor, Continue.dev) can call these.
+When running as an MCP server (`sqlprism serve`), 24 tools are exposed. Any MCP client (Claude Code, Claude Desktop, Cursor, Continue.dev) can call these.
 
 ## Query Tools
 
@@ -237,6 +237,57 @@ Analyze the downstream impact of proposed column changes BEFORE modifying code.
 | `changes` | list | Yes | | List of column changes (remove_column, rename_column, add_column). |
 | `repo` | string | No | | Filter by repo name. |
 
+## Convention Tools
+
+### `get_conventions`
+
+Get naming conventions, reference rules, and required columns for a layer. Returns inferred conventions with confidence scores.
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `layer` | string | No | | Layer name (e.g. 'staging', 'marts'). Omit for all layers. |
+| `repo` | string | No | | Filter by repo name. |
+
+### `search_by_tag`
+
+Find models tagged with a business domain concept. Returns models ranked by confidence.
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `tag` | string | Yes | | Tag name to search for (e.g. 'customer', 'order'). |
+| `min_confidence` | float | No | | Minimum confidence threshold (0.0-1.0). |
+| `repo` | string | No | | Filter by repo name. |
+
+### `list_tags`
+
+List all semantic tags with model counts and average confidence. Provides the project's business domain vocabulary.
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `repo` | string | No | | Filter by repo name. |
+
+### `find_similar_models`
+
+Find existing models similar to what you're building. Compares reference overlap, column overlap, and layer placement.
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `references` | list[string] | No | | Tables this model will reference. |
+| `output_columns` | list[string] | No | | Columns this model will output. |
+| `model` | string | No | | Existing model name to find similar models to. |
+| `limit` | int | No | 5 | Max results (1-50). |
+| `repo` | string | No | | Filter by repo name. |
+
+### `suggest_placement`
+
+Recommend where to place a new model based on its references. Uses inferred layer flow rules and naming conventions.
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `references` | list[string] | Yes | | Tables this new model will reference. |
+| `name` | string | No | | Proposed model name (for naming validation). |
+| `repo` | string | No | | Filter by repo name. |
+
 ## DuckPGQ Tools
 
 The following tools require the [DuckPGQ](https://github.com/cwida/duckpgq) extension: `find_path`, `find_critical_models`, `find_subgraphs`. The extension is installed automatically on first use. Tools that don't require DuckPGQ (`detect_cycles`, `find_bottlenecks`, `check_impact`) use plain SQL and work everywhere.

{sqlprism-1.1.0 → sqlprism-1.2.0}/mkdocs.yml

@@ -59,6 +59,7 @@ nav:
   - User Guide:
     - CLI Reference: guide/cli.md
     - MCP Tools: guide/mcp-tools.md
+    - Conventions: guide/conventions.md
     - SQLMesh Integration: guide/sqlmesh.md
     - dbt Integration: guide/dbt.md
   - Architecture:
@@ -69,6 +70,7 @@ nav:
     - GraphDB (Storage): api/graph.md
     - Indexer (Orchestrator): api/indexer.md
     - SQL Parser: api/sql-parser.md
+    - Convention Engine: api/conventions.md
     - SQLMesh Renderer: api/sqlmesh.md
     - dbt Renderer: api/dbt.md
     - MCP Server: api/mcp-tools.md

{sqlprism-1.1.0 → sqlprism-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sqlprism"
-version = "1.1.0"
+version = "1.2.0"
 description = "SQL codebase indexer with column-level lineage, impact analysis, and MCP server support"
 license = "Apache-2.0"
 requires-python = ">=3.11"
@@ -26,7 +26,7 @@ classifiers = [
 dependencies = [
     "mcp[cli]>=1.0.0",
     "duckdb>=1.5.0",
-    "sqlglot>=28.0.0,<30",
+    "sqlglot[c]>=30.0.0,<31",
     "pydantic>=2.0.0",
     "click>=8.0.0",
     "pyyaml>=6.0",

{sqlprism-1.1.0 → sqlprism-1.2.0}/src/sqlprism/cli.py

@@ -241,7 +241,7 @@ def reindex_file(paths, config_path, db_path):
         for name, cfg in repo_configs.items():
             graph.upsert_repo(name, cfg["path"], repo_type=cfg["repo_type"])
 
-        resolved_paths = [str(Path(p).resolve()) for p in paths]
+        resolved_paths: list[str | Path] = [str(Path(p).resolve()) for p in paths]
         stats = indexer.reindex_files(paths=resolved_paths, repo_configs=repo_configs)
 
     # Print summary
@@ -614,6 +614,148 @@ def status(config_path: str, db_path: str | None):
     click.echo(json.dumps(info, indent=2, default=str))
 
 
+@cli.group()
+def conventions():
+    """Manage convention inference and overrides."""
+    pass
+
+
+@conventions.command("init")
+@click.option("--config", "config_path", type=click.Path(), default=None)
+@click.option("--db", "db_path", type=click.Path(), default=None)
+@click.option("--force", is_flag=True, help="Overwrite existing conventions file")
+def conventions_init(config_path: str, db_path: str | None, force: bool):
+    """Generate a sqlprism.conventions.yml with inferred conventions.
+
+    Runs inference and writes a YAML file with confidence scores as comments.
+    Review and adjust the file, then re-run reindex to apply overrides.
+    """
+    from sqlprism.core.conventions import ConventionEngine
+    from sqlprism.core.graph import GraphDB
+
+    config = _try_load_config(config_path)
+    effective_db_path = db_path or config.get("db_path", str(DEFAULT_DB_PATH))
+
+    if not Path(effective_db_path).exists():
+        click.echo("No index found. Run 'sqlprism reindex' first.")
+        sys.exit(1)
+
+    output_path = Path("sqlprism.conventions.yml")
+    if output_path.exists() and not force:
+        click.echo(
+            f"{output_path} already exists. Use --force to overwrite."
+        )
+        sys.exit(1)
+
+    graph = GraphDB(effective_db_path)
+    try:
+        # Find all repos and run inference for each
+        repos = graph._execute_read("SELECT repo_id FROM repos").fetchall()
+        if not repos:
+            click.echo("No repos indexed. Run 'sqlprism reindex' first.")
+            sys.exit(1)
+
+        repo_id = repos[0][0]
+        if len(repos) > 1:
+            click.echo(
+                f"Warning: {len(repos)} repos found; using first repo. "
+                "Use 'conventions refresh' to process all repos.",
+                err=True,
+            )
+        engine = ConventionEngine(graph, repo_id)
+        engine.run_inference()
+
+        yaml_content = engine.generate_yaml()
+        output_path.write_text(yaml_content)
+        click.echo(f"Wrote {output_path}")
+    finally:
+        graph.close()
+
+
+@conventions.command("refresh")
+@click.option("--config", "config_path", type=click.Path(), default=None)
+@click.option("--db", "db_path", type=click.Path(), default=None)
+def conventions_refresh(config_path: str, db_path: str | None):
+    """Re-run convention inference without writing YAML.
+
+    Updates the conventions and semantic_tags tables in the database.
+    Useful after reindex to see how conventions changed.
+    """
+    from sqlprism.core.conventions import ConventionEngine
+    from sqlprism.core.graph import GraphDB
+
+    config = _try_load_config(config_path)
+    effective_db_path = db_path or config.get("db_path", str(DEFAULT_DB_PATH))
+
+    if not Path(effective_db_path).exists():
+        click.echo("No index found. Run 'sqlprism reindex' first.")
+        sys.exit(1)
+
+    graph = GraphDB(effective_db_path)
+    try:
+        repos = graph._execute_read("SELECT repo_id FROM repos").fetchall()
+        if not repos:
+            click.echo("No repos indexed.")
+            sys.exit(1)
+
+        for (repo_id,) in repos:
+            engine = ConventionEngine(graph, repo_id)
+            result = engine.run_inference()
+            click.echo(
+                f"Repo {repo_id}: {result['layers_detected']} layers, "
+                f"{result['conventions_stored']} conventions stored"
+            )
+    finally:
+        graph.close()
+
+    click.echo("Done.")
+
+
+@conventions.command("diff")
+@click.option("--config", "config_path", type=click.Path(), default=None)
+@click.option("--db", "db_path", type=click.Path(), default=None)
+@click.option(
+    "--file",
+    "yaml_file",
+    type=click.Path(),
+    default="sqlprism.conventions.yml",
+    help="Conventions YAML file to compare against",
+)
+def conventions_diff(config_path: str, db_path: str | None, yaml_file: str):
+    """Show what changed since last --init.
+
+    Compares current conventions in the database against the YAML file.
+    """
+    from sqlprism.core.conventions import ConventionEngine
+    from sqlprism.core.graph import GraphDB
+
+    config = _try_load_config(config_path)
+    effective_db_path = db_path or config.get("db_path", str(DEFAULT_DB_PATH))
+
+    if not Path(effective_db_path).exists():
+        click.echo("No index found. Run 'sqlprism reindex' first.")
+        sys.exit(1)
+
+    graph = GraphDB(effective_db_path)
+    try:
+        repos = graph._execute_read("SELECT repo_id FROM repos").fetchall()
+        if not repos:
+            click.echo("No repos indexed.")
+            sys.exit(1)
+
+        repo_id = repos[0][0]
+        if len(repos) > 1:
+            click.echo(
+                f"Warning: {len(repos)} repos found; comparing first repo only.",
+                err=True,
+            )
+        engine = ConventionEngine(graph, repo_id)
+        diff_output = engine.get_diff(yaml_file)
+        click.echo(diff_output)
+    finally:
+        graph.close()
+
+
 @cli.command("init")
 @click.option(
     "--format",
@@ -705,6 +847,18 @@ def _build_repo_configs(config: dict) -> dict:
     return result
 
 
+def _try_load_config(path: str | None) -> dict:
+    """Try to load config, return empty dict if not found.
+
+    Unlike ``_cli_load_config``, does not raise on missing config.
+    Used by commands that work with just ``--db`` and no config.
+    """
+    try:
+        return load_config(path)
+    except FileNotFoundError:
+        return {}
+
+
 def _cli_load_config(path: str | None) -> dict:
     """CLI wrapper: converts FileNotFoundError to a friendly click error."""
     try: