dlin-cli 0.2.1rc1__tar.gz → 0.2.2__tar.gz

{dlin_cli-0.2.1rc1 → dlin_cli-0.2.2}/Cargo.lock

@@ -230,7 +230,7 @@ checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
 
 [[package]]
 name = "dlin"
-version = "0.2.1-rc.1"
+version = "0.2.2"
 dependencies = [
  "anyhow",
  "clap",
@@ -239,6 +239,7 @@ dependencies = [
  "path-slash",
  "polyglot-sql",
  "regex",
+ "serde",
  "serde-saphyr",
  "serde_json",
  "tempfile",
@@ -246,7 +247,7 @@ dependencies = [
 
 [[package]]
 name = "dlin-core"
-version = "0.2.1-rc.1"
+version = "0.2.2"
 dependencies = [
  "anyhow",
  "clap",
@@ -397,9 +398,9 @@ dependencies = [
 
 [[package]]
 name = "granit-parser"
-version = "0.0.2"
+version = "0.0.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b7e736dfe3881c53a7dce0685eb18202d0d9fe6911782f9870946eb9ee89d778"
+checksum = "f50ba32164f9e098d5da618776a32afbb32270adcbe3d3d006107dae11e37c91"
 dependencies = [
  "arraydeque",
  "smallvec",
@@ -596,9 +597,9 @@ checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
 
 [[package]]
 name = "polyglot-sql"
-version = "0.4.2"
+version = "0.4.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3e264f8907f3a2050232cd06503afb637525038ddd388a2c9e03424e336cd9c8"
+checksum = "b0d5ea9283f03d3b6c32a230e60e7c6bc854e5bec83c399c75cad02bf46e9622"
 dependencies = [
  "serde",
  "serde_json",
@@ -749,9 +750,9 @@ dependencies = [
 
 [[package]]
 name = "serde-saphyr"
-version = "0.0.26"
+version = "0.0.27"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dcc7fe48e34d02a97bc8e6253b8b91e5a47fe2c47eaacb5149cefbb69922eaf0"
+checksum = "5897b4c3faadadd35fdb6689f015641f3bc481d5adaaac56231ea15aeb243db3"
 dependencies = [
  "ahash",
  "annotate-snippets",

{dlin_cli-0.2.1rc1 → dlin_cli-0.2.2}/Cargo.toml

@@ -3,7 +3,7 @@ members = ["crates/*"]
 resolver = "3"
 
 [workspace.package]
-version = "0.2.1-rc.1"
+version = "0.2.2"
 edition = "2024"
 license = "MIT"
 repository = "https://github.com/eitsupi/dlin"
@@ -13,7 +13,7 @@ homepage = "https://github.com/eitsupi/dlin"
 petgraph = { version = "0.8", features = ["serde-1"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
-serde-saphyr = "0.0.26"
+serde-saphyr = "0.0.27"
 regex = "1"
 walkdir = "2"
 colored = "3"
@@ -23,7 +23,7 @@ indexmap = "2"
 minijinja = "2"
 rayon = "1"
 globset = "0.4"
-polyglot-sql = { version = "0.4.2", default-features = false, features = ["all-dialects", "semantic"] }
+polyglot-sql = { version = "0.4.4", default-features = false, features = ["all-dialects", "semantic"] }
 path-slash = "0.2.1"
 clap = { version = "4", features = ["derive", "env"] }
 libc = "0.2"
@@ -34,7 +34,7 @@ insta = "1"
 serial_test = "3.4.0"
 
 # internal
-dlin-core = { version = "0.2.1-rc.1", path = "crates/dlin-core" }
+dlin-core = { version = "0.2.2", path = "crates/dlin-core" }
 
 [workspace.lints.rust]
 unexpected_cfgs = { level = "warn", check-cfg = ['cfg(tarpaulin_include)'] }

{dlin_cli-0.2.1rc1 → dlin_cli-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dlin-cli
-Version: 0.2.1rc1
+Version: 0.2.2
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -26,11 +26,11 @@ Project-URL: Repository, https://github.com/eitsupi/dlin
 [![PyPI](https://img.shields.io/pypi/v/dlin-cli)](https://pypi.org/project/dlin-cli/)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/eitsupi/dlin)
 
-dbt model lineage CLI that parses SQL files directly. No `dbt compile`, no Python, no `manifest.json` (for model-level lineage).
+dbt model lineage CLI. Parses SQL files directly or reads a compiled `manifest.json`. No Python required.
 
-Builds a dependency graph from `ref()` and `source()` calls in SQL. Designed for AI agents and CI pipelines.
+Works for developers navigating live SQL files, analysts exploring a shared manifest, AI agents via CLI prompt or MCP server, and CI pipelines.
 
-Experimental column-level lineage (`dlin column upstream` / `dlin column downstream`) is also available. It requires `dbt compile` and `manifest.json`.
+Column-level lineage (`dlin column upstream` / `dlin column downstream`) is also available. It requires `manifest.json`.
 
 ## Motivation
 
@@ -90,10 +90,41 @@ dlin list -o json --json-fields unique_id,file_path
 git diff --name-only main | dlin graph -o json
 ```
 
+## Source modes
+
+dlin supports two source modes for model-level commands.
+
+**SQL parse mode (default)** is for developers working with a live dbt project. dlin reads `ref()` and `source()` calls directly from SQL files without running `dbt compile`. It works immediately as you edit models, with no compilation step needed.
+
+**Manifest mode** (`--source manifest`) is for analysts or agents who have access only to a compiled `manifest.json`. A developer runs `dbt compile` once and distributes the result; anyone with that file can then explore the full project structure with dlin without needing SQL files or a Python environment.
+
+```sh
+# SQL parse mode: reads SQL files directly (default)
+dlin graph orders
+
+# Manifest mode: reads manifest.json only
+dlin graph orders --source manifest
+dlin summary --source manifest
+```
+
+For model-name inputs, `manifest.json` is the only file needed in manifest mode. File-path inputs (e.g. `models/foo.sql`) fall back to standard dbt directory layout when `dbt_project.yml` is absent, which may not match projects with custom path configuration. (`check-manifest` always requires a full project.)
+
+### Limitations of SQL parse mode
+
+- `var()` resolves from `dbt_project.yml` only (`--vars` CLI overrides not supported)
+- Runtime context (`target.type`, `env_var()`) is not evaluated
+- Conditional Jinja branches use default values; non-default paths may be missed
+- Generic test IDs are dlin-specific (e.g. `test.not_null.orders.order_id`) and do not match dbt's naming; use manifest mode when exact test IDs matter
+
+When these limitations matter, use `--source manifest`.
+
 ## AI agent integration
 
-No MCP server or tool configuration needed.
-Just install dlin and add the following to your `AGENTS.md`, `CLAUDE.md`, or system prompt:
+### CLI approach
+
+Recommended for developers with access to a live dbt project. Works with SQL parse mode (no `dbt compile` needed) as well as manifest mode.
+
+Install dlin and add the following to your `AGENTS.md`, `CLAUDE.md`, or system prompt:
 
 ````md
 ## dbt project structure analysis
@@ -112,16 +143,32 @@ git diff --name-only main | dlin graph -q              # Lineage of changed file
 For full option reference: `dlin --help`, `dlin graph --help`, etc.
 ````
 
-The key line is **"Do NOT grep/cat/find through SQL files"** — without it, agents default to familiar tools. `dlin --help` is designed for tool discovery, so the prompt can stay minimal.
+The key line is **"Do NOT grep/cat/find through SQL files"**. Without it, agents default to familiar tools. `dlin --help` is designed for tool discovery, so the prompt can stay minimal.
+
+### MCP server (experimental)
+
+For analysts and agents who work from a distributed `manifest.json` without access to the full project. Runs in manifest mode only.
+
+`dlin mcp` exposes a stdio MCP server that AI assistants supporting MCP can connect to directly.
+
+```sh
+dlin mcp --dialect bigquery path/to/manifest.json
+```
+
+Available MCP tools: project summary, model search, lineage, impact analysis, and column-level lineage.
+
+Pass `--dialect` to match your project's SQL dialect for accurate column lineage. Requires a compiled `manifest.json` (`dbt compile`).
 
 ## Features
 
-- **No dependencies for model lineage**: single binary, no Python, no `manifest.json`
+- **SQL parse mode**: single binary, no Python, no `manifest.json` needed for model-level lineage
+- **Manifest mode**: works from `manifest.json` alone; useful for analysts or agents without a full project checkout
+- **MCP server** (experimental): `dlin mcp` serves lineage data via stdio MCP for direct AI assistant integration
 - **Recursive upstream / downstream**: `-u N` / `-d N` to control traversal depth
 - **Impact analysis with severity**: `dlin impact` scores downstream nodes and flags exposure reachability
 - **Composable**: stdin accepts model names or file paths; pipe with `jq`, `dlin list`, `git diff`, etc.
 - **Agent-friendly**: `--error-format json` emits structured `{"level","what","why","hint"}` on stderr; `--help` is designed for tool discovery
-- **Column-level lineage** (experimental): traces columns across models with transformation classification; requires `dbt compile` and `manifest.json`
+- **Column-level lineage** (experimental): traces columns across models with transformation classification; requires `manifest.json`
 
 ## Mermaid diagrams
 
@@ -132,11 +179,11 @@ dlin outputs Mermaid flowcharts that render natively on GitHub, GitLab, Notion,
 Automatically remove intermediate nodes to see just the endpoints (nodes with no predecessors or no successors); everything in between becomes transitive "(via N)" edges:
 
 ```sh
-# Collapse intermediate models — only endpoints remain
+# Collapse intermediate models; only endpoints remain
 dlin graph --collapse -o mermaid
 
 # Focal mode: keep only sources, exposures, and specified focus models
-# (ignores BFS window pseudo-endpoints — ideal with -u/-d limits)
+# (ignores BFS window pseudo-endpoints; works best with -u/-d limits)
 dlin graph orders --collapse=focal -u 3 -o mermaid
 ```
 
@@ -218,7 +265,7 @@ flowchart LR
 
 ### Column names in nodes with `--show-columns`
 
-Add `--show-columns` to include column names inside Mermaid node labels — useful for understanding what each model produces at a glance:
+Add `--show-columns` to include column names inside Mermaid node labels, useful for understanding what each model produces at a glance:
 
 ```sh
 dlin graph orders -u 1 -d 0 --show-columns --node-type model,source -o mermaid
@@ -343,7 +390,7 @@ flowchart LR
   n1_0 -->|"aggregation"|n0_5
 ```
 
-`customer_id`, `email`, etc. pass through `stg_customers` unchanged from `raw.customers` (all `direct`). `lifetime_value` and `order_count` are aggregated at the `customers` model — the final edge to `customers` is labeled `aggregation`, while all upstream hops carry their actual transformation type (here `direct`, since staging and mart models pass columns through unchanged).
+`customer_id`, `email`, etc. pass through `stg_customers` unchanged from `raw.customers` (all `direct`). `lifetime_value` and `order_count` are aggregated at the `customers` model. The final edge to `customers` is labeled `aggregation`, while all upstream hops carry their actual transformation type (here `direct`, since staging and mart models pass columns through unchanged).
 
 Transformation types shown on edges: `direct`, `aggregation`, `expression`, `cast`, `conditional`, `unknown`.
 
@@ -420,25 +467,6 @@ dlin graph -s tag:finance,path:marts  # selector expressions (union)
 dlin graph --node-type model,source   # filter by node type
 ```
 
-## Data sources
-
-dlin aims to work without `dbt compile` (except for column-level lineage, which always requires `manifest.json`). By default it parses SQL files directly, but it can also leverage a pre-compiled `manifest.json` for additional accuracy when one is available.
-
-**SQL parsing (default)**: extracts `ref()` and `source()` from SQL via regex + Jinja template evaluation. No Python or dbt needed. Generic tests (`not_null`, `unique`, `relationships`, etc.) are inferred from YAML schema declarations.
-
-**Manifest mode** (`--source manifest`): reads a pre-compiled `manifest.json` for full accuracy with complex Jinja logic.
-
-For graph, list, impact, summary, and column commands, manifest mode requires only `manifest.json`; SQL files are not needed. When inputs are model names (not file paths), `dbt_project.yml` is also not needed; file-path inputs (e.g. `models/foo.sql`) fall back to standard dbt directory layout when `dbt_project.yml` is absent, which may not match projects with custom path configuration. A developer can run `dbt compile` once and distribute the resulting `manifest.json` to analysts or AI agents who then query it with dlin without access to the full project. (`check-manifest` always requires a full project.)
-
-### Limitations of SQL parse mode
-
-- `var()` resolves from `dbt_project.yml` only (`--vars` CLI overrides not supported)
-- Runtime context (`target.type`, `env_var()`) is not evaluated
-- Conditional Jinja branches use default values; non-default paths may be missed
-- Generic test IDs are dlin-specific (e.g. `test.not_null.orders.order_id`) and do not match dbt's naming; use manifest mode when exact test IDs matter
-
-When these limitations matter, use `--source manifest`.
-
 ## Credits
 
 Hard fork of [dbt-lineage-viewer](https://github.com/sipemu/dbt-lineage-viewer) by Simon Muller (MIT license). The original focused on TUI-based exploration; dlin removes the TUI and targets non-interactive use: scripting, CI, and AI agents.

{dlin_cli-0.2.1rc1/crates/dlin → dlin_cli-0.2.2}/README.md

@@ -4,11 +4,11 @@
 [![PyPI](https://img.shields.io/pypi/v/dlin-cli)](https://pypi.org/project/dlin-cli/)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/eitsupi/dlin)
 
-dbt model lineage CLI that parses SQL files directly. No `dbt compile`, no Python, no `manifest.json` (for model-level lineage).
+dbt model lineage CLI. Parses SQL files directly or reads a compiled `manifest.json`. No Python required.
 
-Builds a dependency graph from `ref()` and `source()` calls in SQL. Designed for AI agents and CI pipelines.
+Works for developers navigating live SQL files, analysts exploring a shared manifest, AI agents via CLI prompt or MCP server, and CI pipelines.
 
-Experimental column-level lineage (`dlin column upstream` / `dlin column downstream`) is also available. It requires `dbt compile` and `manifest.json`.
+Column-level lineage (`dlin column upstream` / `dlin column downstream`) is also available. It requires `manifest.json`.
 
 ## Motivation
 
@@ -68,10 +68,41 @@ dlin list -o json --json-fields unique_id,file_path
 git diff --name-only main | dlin graph -o json
 ```
 
+## Source modes
+
+dlin supports two source modes for model-level commands.
+
+**SQL parse mode (default)** is for developers working with a live dbt project. dlin reads `ref()` and `source()` calls directly from SQL files without running `dbt compile`. It works immediately as you edit models, with no compilation step needed.
+
+**Manifest mode** (`--source manifest`) is for analysts or agents who have access only to a compiled `manifest.json`. A developer runs `dbt compile` once and distributes the result; anyone with that file can then explore the full project structure with dlin without needing SQL files or a Python environment.
+
+```sh
+# SQL parse mode: reads SQL files directly (default)
+dlin graph orders
+
+# Manifest mode: reads manifest.json only
+dlin graph orders --source manifest
+dlin summary --source manifest
+```
+
+For model-name inputs, `manifest.json` is the only file needed in manifest mode. File-path inputs (e.g. `models/foo.sql`) fall back to standard dbt directory layout when `dbt_project.yml` is absent, which may not match projects with custom path configuration. (`check-manifest` always requires a full project.)
+
+### Limitations of SQL parse mode
+
+- `var()` resolves from `dbt_project.yml` only (`--vars` CLI overrides not supported)
+- Runtime context (`target.type`, `env_var()`) is not evaluated
+- Conditional Jinja branches use default values; non-default paths may be missed
+- Generic test IDs are dlin-specific (e.g. `test.not_null.orders.order_id`) and do not match dbt's naming; use manifest mode when exact test IDs matter
+
+When these limitations matter, use `--source manifest`.
+
 ## AI agent integration
 
-No MCP server or tool configuration needed.
-Just install dlin and add the following to your `AGENTS.md`, `CLAUDE.md`, or system prompt:
+### CLI approach
+
+Recommended for developers with access to a live dbt project. Works with SQL parse mode (no `dbt compile` needed) as well as manifest mode.
+
+Install dlin and add the following to your `AGENTS.md`, `CLAUDE.md`, or system prompt:
 
 ````md
 ## dbt project structure analysis
@@ -90,16 +121,32 @@ git diff --name-only main | dlin graph -q              # Lineage of changed file
 For full option reference: `dlin --help`, `dlin graph --help`, etc.
 ````
 
-The key line is **"Do NOT grep/cat/find through SQL files"** — without it, agents default to familiar tools. `dlin --help` is designed for tool discovery, so the prompt can stay minimal.
+The key line is **"Do NOT grep/cat/find through SQL files"**. Without it, agents default to familiar tools. `dlin --help` is designed for tool discovery, so the prompt can stay minimal.
+
+### MCP server (experimental)
+
+For analysts and agents who work from a distributed `manifest.json` without access to the full project. Runs in manifest mode only.
+
+`dlin mcp` exposes a stdio MCP server that AI assistants supporting MCP can connect to directly.
+
+```sh
+dlin mcp --dialect bigquery path/to/manifest.json
+```
+
+Available MCP tools: project summary, model search, lineage, impact analysis, and column-level lineage.
+
+Pass `--dialect` to match your project's SQL dialect for accurate column lineage. Requires a compiled `manifest.json` (`dbt compile`).
 
 ## Features
 
-- **No dependencies for model lineage**: single binary, no Python, no `manifest.json`
+- **SQL parse mode**: single binary, no Python, no `manifest.json` needed for model-level lineage
+- **Manifest mode**: works from `manifest.json` alone; useful for analysts or agents without a full project checkout
+- **MCP server** (experimental): `dlin mcp` serves lineage data via stdio MCP for direct AI assistant integration
 - **Recursive upstream / downstream**: `-u N` / `-d N` to control traversal depth
 - **Impact analysis with severity**: `dlin impact` scores downstream nodes and flags exposure reachability
 - **Composable**: stdin accepts model names or file paths; pipe with `jq`, `dlin list`, `git diff`, etc.
 - **Agent-friendly**: `--error-format json` emits structured `{"level","what","why","hint"}` on stderr; `--help` is designed for tool discovery
-- **Column-level lineage** (experimental): traces columns across models with transformation classification; requires `dbt compile` and `manifest.json`
+- **Column-level lineage** (experimental): traces columns across models with transformation classification; requires `manifest.json`
 
 ## Mermaid diagrams
 
@@ -110,11 +157,11 @@ dlin outputs Mermaid flowcharts that render natively on GitHub, GitLab, Notion,
 Automatically remove intermediate nodes to see just the endpoints (nodes with no predecessors or no successors); everything in between becomes transitive "(via N)" edges:
 
 ```sh
-# Collapse intermediate models — only endpoints remain
+# Collapse intermediate models; only endpoints remain
 dlin graph --collapse -o mermaid
 
 # Focal mode: keep only sources, exposures, and specified focus models
-# (ignores BFS window pseudo-endpoints — ideal with -u/-d limits)
+# (ignores BFS window pseudo-endpoints; works best with -u/-d limits)
 dlin graph orders --collapse=focal -u 3 -o mermaid
 ```
 
@@ -196,7 +243,7 @@ flowchart LR
 
 ### Column names in nodes with `--show-columns`
 
-Add `--show-columns` to include column names inside Mermaid node labels — useful for understanding what each model produces at a glance:
+Add `--show-columns` to include column names inside Mermaid node labels, useful for understanding what each model produces at a glance:
 
 ```sh
 dlin graph orders -u 1 -d 0 --show-columns --node-type model,source -o mermaid
@@ -321,7 +368,7 @@ flowchart LR
   n1_0 -->|"aggregation"|n0_5
 ```
 
-`customer_id`, `email`, etc. pass through `stg_customers` unchanged from `raw.customers` (all `direct`). `lifetime_value` and `order_count` are aggregated at the `customers` model — the final edge to `customers` is labeled `aggregation`, while all upstream hops carry their actual transformation type (here `direct`, since staging and mart models pass columns through unchanged).
+`customer_id`, `email`, etc. pass through `stg_customers` unchanged from `raw.customers` (all `direct`). `lifetime_value` and `order_count` are aggregated at the `customers` model. The final edge to `customers` is labeled `aggregation`, while all upstream hops carry their actual transformation type (here `direct`, since staging and mart models pass columns through unchanged).
 
 Transformation types shown on edges: `direct`, `aggregation`, `expression`, `cast`, `conditional`, `unknown`.
 
@@ -398,25 +445,6 @@ dlin graph -s tag:finance,path:marts  # selector expressions (union)
 dlin graph --node-type model,source   # filter by node type
 ```
 
-## Data sources
-
-dlin aims to work without `dbt compile` (except for column-level lineage, which always requires `manifest.json`). By default it parses SQL files directly, but it can also leverage a pre-compiled `manifest.json` for additional accuracy when one is available.
-
-**SQL parsing (default)**: extracts `ref()` and `source()` from SQL via regex + Jinja template evaluation. No Python or dbt needed. Generic tests (`not_null`, `unique`, `relationships`, etc.) are inferred from YAML schema declarations.
-
-**Manifest mode** (`--source manifest`): reads a pre-compiled `manifest.json` for full accuracy with complex Jinja logic.
-
-For graph, list, impact, summary, and column commands, manifest mode requires only `manifest.json`; SQL files are not needed. When inputs are model names (not file paths), `dbt_project.yml` is also not needed; file-path inputs (e.g. `models/foo.sql`) fall back to standard dbt directory layout when `dbt_project.yml` is absent, which may not match projects with custom path configuration. A developer can run `dbt compile` once and distribute the resulting `manifest.json` to analysts or AI agents who then query it with dlin without access to the full project. (`check-manifest` always requires a full project.)
-
-### Limitations of SQL parse mode
-
-- `var()` resolves from `dbt_project.yml` only (`--vars` CLI overrides not supported)
-- Runtime context (`target.type`, `env_var()`) is not evaluated
-- Conditional Jinja branches use default values; non-default paths may be missed
-- Generic test IDs are dlin-specific (e.g. `test.not_null.orders.order_id`) and do not match dbt's naming; use manifest mode when exact test IDs matter
-
-When these limitations matter, use `--source manifest`.
-
 ## Credits
 
 Hard fork of [dbt-lineage-viewer](https://github.com/sipemu/dbt-lineage-viewer) by Simon Muller (MIT license). The original focused on TUI-based exploration; dlin removes the TUI and targets non-interactive use: scripting, CI, and AI agents.

{dlin_cli-0.2.1rc1 → dlin_cli-0.2.2}/crates/dlin/Cargo.toml

@@ -20,6 +20,7 @@ clap = { workspace = true }
 anyhow = { workspace = true }
 regex = { workspace = true }
 serde_json = { workspace = true }
+serde = { workspace = true }
 path-slash = { workspace = true }
 polyglot-sql = { workspace = true }
 

{dlin_cli-0.2.1rc1/crates/dlin-core → dlin_cli-0.2.2/crates/dlin}/README.md

@@ -4,11 +4,11 @@
 [![PyPI](https://img.shields.io/pypi/v/dlin-cli)](https://pypi.org/project/dlin-cli/)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/eitsupi/dlin)
 
-dbt model lineage CLI that parses SQL files directly. No `dbt compile`, no Python, no `manifest.json` (for model-level lineage).
+dbt model lineage CLI. Parses SQL files directly or reads a compiled `manifest.json`. No Python required.
 
-Builds a dependency graph from `ref()` and `source()` calls in SQL. Designed for AI agents and CI pipelines.
+Works for developers navigating live SQL files, analysts exploring a shared manifest, AI agents via CLI prompt or MCP server, and CI pipelines.
 
-Experimental column-level lineage (`dlin column upstream` / `dlin column downstream`) is also available. It requires `dbt compile` and `manifest.json`.
+Column-level lineage (`dlin column upstream` / `dlin column downstream`) is also available. It requires `manifest.json`.
 
 ## Motivation
 
@@ -68,10 +68,41 @@ dlin list -o json --json-fields unique_id,file_path
 git diff --name-only main | dlin graph -o json
 ```
 
+## Source modes
+
+dlin supports two source modes for model-level commands.
+
+**SQL parse mode (default)** is for developers working with a live dbt project. dlin reads `ref()` and `source()` calls directly from SQL files without running `dbt compile`. It works immediately as you edit models, with no compilation step needed.
+
+**Manifest mode** (`--source manifest`) is for analysts or agents who have access only to a compiled `manifest.json`. A developer runs `dbt compile` once and distributes the result; anyone with that file can then explore the full project structure with dlin without needing SQL files or a Python environment.
+
+```sh
+# SQL parse mode: reads SQL files directly (default)
+dlin graph orders
+
+# Manifest mode: reads manifest.json only
+dlin graph orders --source manifest
+dlin summary --source manifest
+```
+
+For model-name inputs, `manifest.json` is the only file needed in manifest mode. File-path inputs (e.g. `models/foo.sql`) fall back to standard dbt directory layout when `dbt_project.yml` is absent, which may not match projects with custom path configuration. (`check-manifest` always requires a full project.)
+
+### Limitations of SQL parse mode
+
+- `var()` resolves from `dbt_project.yml` only (`--vars` CLI overrides not supported)
+- Runtime context (`target.type`, `env_var()`) is not evaluated
+- Conditional Jinja branches use default values; non-default paths may be missed
+- Generic test IDs are dlin-specific (e.g. `test.not_null.orders.order_id`) and do not match dbt's naming; use manifest mode when exact test IDs matter
+
+When these limitations matter, use `--source manifest`.
+
 ## AI agent integration
 
-No MCP server or tool configuration needed.
-Just install dlin and add the following to your `AGENTS.md`, `CLAUDE.md`, or system prompt:
+### CLI approach
+
+Recommended for developers with access to a live dbt project. Works with SQL parse mode (no `dbt compile` needed) as well as manifest mode.
+
+Install dlin and add the following to your `AGENTS.md`, `CLAUDE.md`, or system prompt:
 
 ````md
 ## dbt project structure analysis
@@ -90,16 +121,32 @@ git diff --name-only main | dlin graph -q              # Lineage of changed file
 For full option reference: `dlin --help`, `dlin graph --help`, etc.
 ````
 
-The key line is **"Do NOT grep/cat/find through SQL files"** — without it, agents default to familiar tools. `dlin --help` is designed for tool discovery, so the prompt can stay minimal.
+The key line is **"Do NOT grep/cat/find through SQL files"**. Without it, agents default to familiar tools. `dlin --help` is designed for tool discovery, so the prompt can stay minimal.
+
+### MCP server (experimental)
+
+For analysts and agents who work from a distributed `manifest.json` without access to the full project. Runs in manifest mode only.
+
+`dlin mcp` exposes a stdio MCP server that AI assistants supporting MCP can connect to directly.
+
+```sh
+dlin mcp --dialect bigquery path/to/manifest.json
+```
+
+Available MCP tools: project summary, model search, lineage, impact analysis, and column-level lineage.
+
+Pass `--dialect` to match your project's SQL dialect for accurate column lineage. Requires a compiled `manifest.json` (`dbt compile`).
 
 ## Features
 
-- **No dependencies for model lineage**: single binary, no Python, no `manifest.json`
+- **SQL parse mode**: single binary, no Python, no `manifest.json` needed for model-level lineage
+- **Manifest mode**: works from `manifest.json` alone; useful for analysts or agents without a full project checkout
+- **MCP server** (experimental): `dlin mcp` serves lineage data via stdio MCP for direct AI assistant integration
 - **Recursive upstream / downstream**: `-u N` / `-d N` to control traversal depth
 - **Impact analysis with severity**: `dlin impact` scores downstream nodes and flags exposure reachability
 - **Composable**: stdin accepts model names or file paths; pipe with `jq`, `dlin list`, `git diff`, etc.
 - **Agent-friendly**: `--error-format json` emits structured `{"level","what","why","hint"}` on stderr; `--help` is designed for tool discovery
-- **Column-level lineage** (experimental): traces columns across models with transformation classification; requires `dbt compile` and `manifest.json`
+- **Column-level lineage** (experimental): traces columns across models with transformation classification; requires `manifest.json`
 
 ## Mermaid diagrams
 
@@ -110,11 +157,11 @@ dlin outputs Mermaid flowcharts that render natively on GitHub, GitLab, Notion,
 Automatically remove intermediate nodes to see just the endpoints (nodes with no predecessors or no successors); everything in between becomes transitive "(via N)" edges:
 
 ```sh
-# Collapse intermediate models — only endpoints remain
+# Collapse intermediate models; only endpoints remain
 dlin graph --collapse -o mermaid
 
 # Focal mode: keep only sources, exposures, and specified focus models
-# (ignores BFS window pseudo-endpoints — ideal with -u/-d limits)
+# (ignores BFS window pseudo-endpoints; works best with -u/-d limits)
 dlin graph orders --collapse=focal -u 3 -o mermaid
 ```
 
@@ -196,7 +243,7 @@ flowchart LR
 
 ### Column names in nodes with `--show-columns`
 
-Add `--show-columns` to include column names inside Mermaid node labels — useful for understanding what each model produces at a glance:
+Add `--show-columns` to include column names inside Mermaid node labels, useful for understanding what each model produces at a glance:
 
 ```sh
 dlin graph orders -u 1 -d 0 --show-columns --node-type model,source -o mermaid
@@ -321,7 +368,7 @@ flowchart LR
   n1_0 -->|"aggregation"|n0_5
 ```
 
-`customer_id`, `email`, etc. pass through `stg_customers` unchanged from `raw.customers` (all `direct`). `lifetime_value` and `order_count` are aggregated at the `customers` model — the final edge to `customers` is labeled `aggregation`, while all upstream hops carry their actual transformation type (here `direct`, since staging and mart models pass columns through unchanged).
+`customer_id`, `email`, etc. pass through `stg_customers` unchanged from `raw.customers` (all `direct`). `lifetime_value` and `order_count` are aggregated at the `customers` model. The final edge to `customers` is labeled `aggregation`, while all upstream hops carry their actual transformation type (here `direct`, since staging and mart models pass columns through unchanged).
 
 Transformation types shown on edges: `direct`, `aggregation`, `expression`, `cast`, `conditional`, `unknown`.
 
@@ -398,25 +445,6 @@ dlin graph -s tag:finance,path:marts  # selector expressions (union)
 dlin graph --node-type model,source   # filter by node type
 ```
 
-## Data sources
-
-dlin aims to work without `dbt compile` (except for column-level lineage, which always requires `manifest.json`). By default it parses SQL files directly, but it can also leverage a pre-compiled `manifest.json` for additional accuracy when one is available.
-
-**SQL parsing (default)**: extracts `ref()` and `source()` from SQL via regex + Jinja template evaluation. No Python or dbt needed. Generic tests (`not_null`, `unique`, `relationships`, etc.) are inferred from YAML schema declarations.
-
-**Manifest mode** (`--source manifest`): reads a pre-compiled `manifest.json` for full accuracy with complex Jinja logic.
-
-For graph, list, impact, summary, and column commands, manifest mode requires only `manifest.json`; SQL files are not needed. When inputs are model names (not file paths), `dbt_project.yml` is also not needed; file-path inputs (e.g. `models/foo.sql`) fall back to standard dbt directory layout when `dbt_project.yml` is absent, which may not match projects with custom path configuration. A developer can run `dbt compile` once and distribute the resulting `manifest.json` to analysts or AI agents who then query it with dlin without access to the full project. (`check-manifest` always requires a full project.)
-
-### Limitations of SQL parse mode
-
-- `var()` resolves from `dbt_project.yml` only (`--vars` CLI overrides not supported)
-- Runtime context (`target.type`, `env_var()`) is not evaluated
-- Conditional Jinja branches use default values; non-default paths may be missed
-- Generic test IDs are dlin-specific (e.g. `test.not_null.orders.order_id`) and do not match dbt's naming; use manifest mode when exact test IDs matter
-
-When these limitations matter, use `--source manifest`.
-
 ## Credits
 
 Hard fork of [dbt-lineage-viewer](https://github.com/sipemu/dbt-lineage-viewer) by Simon Muller (MIT license). The original focused on TUI-based exploration; dlin removes the TUI and targets non-interactive use: scripting, CI, and AI agents.