datalex-cli 0.1.1__tar.gz

datalex_cli-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 duckcode.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

datalex_cli-0.1.1/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: datalex-cli
+Version: 0.1.1
+Summary: Git-native data modeling for dbt users
+Author-email: DuckCode AI Labs <hello@duckcode.ai>
+License: MIT
+Project-URL: Homepage, https://duckcode.ai
+Project-URL: Repository, https://github.com/duckcode-ai/DataLex
+Project-URL: Issues, https://github.com/duckcode-ai/DataLex/issues
+Keywords: dbt,data-modeling,yaml,git-native,erd,data-warehouse
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: jsonschema>=4.0
+Provides-Extra: duckdb
+Requires-Dist: duckdb>=0.9; extra == "duckdb"
+Provides-Extra: postgres
+Requires-Dist: psycopg2-binary; extra == "postgres"
+Provides-Extra: mysql
+Requires-Dist: mysql-connector-python; extra == "mysql"
+Provides-Extra: snowflake
+Requires-Dist: snowflake-connector-python; extra == "snowflake"
+Provides-Extra: bigquery
+Requires-Dist: google-cloud-bigquery; extra == "bigquery"
+Provides-Extra: databricks
+Requires-Dist: databricks-sql-connector; extra == "databricks"
+Provides-Extra: sqlserver
+Requires-Dist: pyodbc; extra == "sqlserver"
+Provides-Extra: redshift
+Requires-Dist: redshift-connector; extra == "redshift"
+Provides-Extra: all
+Requires-Dist: duckdb>=0.9; extra == "all"
+Requires-Dist: psycopg2-binary; extra == "all"
+Requires-Dist: mysql-connector-python; extra == "all"
+Requires-Dist: snowflake-connector-python; extra == "all"
+Requires-Dist: google-cloud-bigquery; extra == "all"
+Requires-Dist: databricks-sql-connector; extra == "all"
+Requires-Dist: pyodbc; extra == "all"
+Requires-Dist: redshift-connector; extra == "all"
+Dynamic: license-file
+
+<div align="center">
+  <a href="https://duckcode.ai/" target="_blank" rel="noopener noreferrer">
+    <img src="Assets/DataLex.png" alt="DataLex by DuckCode AI Labs" width="220" />
+  </a>
+
+# DataLex
+
+**Git-native data modeling for dbt users.**
+
+Point us at your dbt project and warehouse — we produce versioned, reviewable YAML
+with contracts, lineage, ERDs, and clean round-trip back to dbt.
+
+<p align="center">
+  <a href="https://github.com/duckcode-ai/DataLex/blob/main/LICENSE">
+    <img src="https://img.shields.io/github/license/duckcode-ai/DataLex?style=for-the-badge&color=22c55e" alt="MIT License" />
+  </a>
+  <a href="https://discord.gg/Dnm6bUvk">
+    <img src="https://img.shields.io/badge/Discord-Join%20Community-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord Community" />
+  </a>
+  <a href="https://github.com/duckcode-ai/DataLex/stargazers">
+    <img src="https://img.shields.io/github/stars/duckcode-ai/DataLex?style=for-the-badge&color=f59e0b" alt="GitHub Stars" />
+  </a>
+</p>
+</div>
+
+<p align="center">
+  <img src="Assets/Overview.png" alt="DataLex Visual Studio — file tree, YAML editor, and React Flow ERD on the same entity" width="100%" />
+</p>
+
+## 60-second demo
+
+```bash
+git clone https://github.com/duckcode-ai/DataLex.git
+cd DataLex
+pip install -e '.[duckdb]'
+
+# 1. Build a local DuckDB warehouse (no external credentials)
+python examples/jaffle_shop_demo/setup.py
+
+# 2. Sync the dbt project into DataLex YAML
+./datalex datalex dbt sync examples/jaffle_shop_demo \
+    --out-root examples/jaffle_shop_demo/datalex-out
+
+# 3. Emit dbt-parseable YAML back, with contracts enforced
+./datalex datalex dbt emit examples/jaffle_shop_demo/datalex-out \
+    --out-dir examples/jaffle_shop_demo/dbt-out
+```
+
+Open `examples/jaffle_shop_demo/datalex-out/sources/jaffle_shop_raw.yaml` —
+every column has its warehouse type, descriptions from the manifest, and a
+`meta.datalex.dbt.unique_id` stamp so re-running the sync never clobbers
+anything you've hand-authored.
+
+## What it does
+
+DataLex treats your data models as code. On top of a stricter YAML
+substrate (the **DataLex** layout — one file per entity, `kind:`-dispatched,
+streaming-safe for 10K+ entities), it gives you:
+
+- **`datalex datalex dbt sync <project>`** — reads `target/manifest.json` + your
+  `profiles.yml`, introspects live column types, and merges them into
+  DataLex YAML. Idempotent: user-authored `description:`, `tags:`,
+  `sensitivity:`, and `tests:` survive re-sync.
+- **`datalex datalex dbt emit`** — writes `sources.yml` and `schema.yml` with
+  `contract.enforced: true` and `data_type:` on every column. `dbt parse`
+  succeeds out of the box.
+- **`datalex datalex emit ddl --dialect ...`** — Postgres, Snowflake, BigQuery,
+  Databricks, MySQL, SQL Server, Redshift. Same source, all dialects.
+- **`datalex datalex diff`** — semantic diff with explicit rename tracking
+  (`previous_name:`), breaking-change gate for CI.
+- **Cross-repo package imports** — pin `acme/warehouse-core@1.4.0` in
+  `imports:`, lockfile + content hash drift detection, Git-or-path
+  resolution, on-disk parse cache for large projects.
+- **Visual studio** — React Flow UI for editing entities, relationships,
+  and metadata; same YAML files as the CLI.
+
+## Supported warehouses
+
+| Warehouse | `dbt sync` introspection | Forward DDL | Reverse engineering |
+|---|:---:|:---:|:---:|
+| DuckDB | ✓ | — | — |
+| PostgreSQL | ✓ | ✓ | ✓ |
+| Snowflake | (fallback) | ✓ | ✓ |
+| BigQuery | (fallback) | ✓ | ✓ |
+| Databricks | (fallback) | ✓ | ✓ |
+| MySQL | (fallback) | ✓ | ✓ |
+| SQL Server / Azure SQL | (fallback) | ✓ | ✓ |
+| Redshift | (fallback) | ✓ | ✓ |
+
+"Fallback" = uses the existing full-schema connector (slower than the
+per-table path but already works today; a narrow introspection path ships
+per-dialect over time).
+
+## Install
+
+```bash
+git clone https://github.com/duckcode-ai/DataLex.git
+cd DataLex
+
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .              # puts `datalex` on PATH
+pip install -e '.[duckdb]'    # add warehouse drivers you need
+
+# optional — only needed for the Visual Studio
+npm --prefix packages/api-server install
+npm --prefix packages/web-app install
+```
+
+Available extras: `duckdb`, `postgres`, `mysql`, `snowflake`,
+`bigquery`, `databricks`, `sqlserver`, `redshift`, or `all`.
+
+Prereqs: Python 3.9+, Git. Node.js 18+ if you want the UI.
+
+## Project layout
+
+```text
+DataLex/
+  packages/
+    core_engine/           # Python: loader, dialects, dbt integration, packages
+      src/datalex_core/
+        _schemas/datalex/  # JSON Schema per `kind:` — bundled with the package
+    cli/                   # `datalex` entry point
+    api-server/            # Node.js API (UI backend)
+    web-app/               # React Flow studio
+  examples/
+    jaffle_shop_demo/      # zero-setup dbt-sync demo (DuckDB)
+  model-examples/          # sample projects and scenario walkthroughs
+  docs/                    # architecture, specs, runbooks
+  tests/                   # unittest suite (core engine + datalex)
+```
+
+## Visual Studio (optional)
+
+If you want the UI on top of your DataLex project, run the two dev servers:
+
+```bash
+# Terminal 1
+npm --prefix packages/api-server run dev
+# Terminal 2
+npm --prefix packages/web-app run dev
+```
+
+Then open `http://localhost:5173`. The UI reads and writes the same YAML
+files the CLI does — no database, no hosted service.
+
+## CI / GitOps
+
+DataLex is designed to live in your repo next to your dbt project.
+A typical CI step:
+
+```bash
+./datalex datalex validate datalex/
+./datalex datalex diff datalex-main/ datalex/ --exit-on-breaking
+./datalex datalex dbt emit datalex/ --out-dir dbt/
+dbt parse
+```
+
+## Documentation
+
+- **[Tutorial: dbt sync in 5 minutes](docs/tutorial-dbt-sync.md)** — the
+  full jaffle_shop walkthrough with explanations.
+- **[DataLex layout reference](docs/datalex-layout.md)** — what each
+  `kind:` file looks like and how the loader discovers them.
+- **[CLI cheat sheet](docs/cli.md)** — every `datalex datalex …` subcommand on
+  one page.
+- **[Architecture](docs/architecture.md)** — core engine modules and
+  end-to-end data flow.
+- Pre-DataLex specs have moved to [docs/archive/](docs/archive/).
+
+## Community
+
+- Discord: [![Join Discord](https://img.shields.io/badge/Discord-Join%20DuckCode%20AI-5865F2?logo=discord&logoColor=white)](https://discord.gg/Dnm6bUvk)
+- Issues: [![GitHub Issues](https://img.shields.io/badge/Issues-Report%20or%20Request-0ea5e9)](https://github.com/duckcode-ai/DataLex/issues)
+- Contributing: `CONTRIBUTING.md`
+- License: [![MIT](https://img.shields.io/badge/License-MIT-22c55e?style=flat-square)](LICENSE)

datalex_cli-0.1.1/README.md

@@ -0,0 +1,176 @@
+<div align="center">
+  <a href="https://duckcode.ai/" target="_blank" rel="noopener noreferrer">
+    <img src="Assets/DataLex.png" alt="DataLex by DuckCode AI Labs" width="220" />
+  </a>
+
+# DataLex
+
+**Git-native data modeling for dbt users.**
+
+Point us at your dbt project and warehouse — we produce versioned, reviewable YAML
+with contracts, lineage, ERDs, and clean round-trip back to dbt.
+
+<p align="center">
+  <a href="https://github.com/duckcode-ai/DataLex/blob/main/LICENSE">
+    <img src="https://img.shields.io/github/license/duckcode-ai/DataLex?style=for-the-badge&color=22c55e" alt="MIT License" />
+  </a>
+  <a href="https://discord.gg/Dnm6bUvk">
+    <img src="https://img.shields.io/badge/Discord-Join%20Community-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord Community" />
+  </a>
+  <a href="https://github.com/duckcode-ai/DataLex/stargazers">
+    <img src="https://img.shields.io/github/stars/duckcode-ai/DataLex?style=for-the-badge&color=f59e0b" alt="GitHub Stars" />
+  </a>
+</p>
+</div>
+
+<p align="center">
+  <img src="Assets/Overview.png" alt="DataLex Visual Studio — file tree, YAML editor, and React Flow ERD on the same entity" width="100%" />
+</p>
+
+## 60-second demo
+
+```bash
+git clone https://github.com/duckcode-ai/DataLex.git
+cd DataLex
+pip install -e '.[duckdb]'
+
+# 1. Build a local DuckDB warehouse (no external credentials)
+python examples/jaffle_shop_demo/setup.py
+
+# 2. Sync the dbt project into DataLex YAML
+./datalex datalex dbt sync examples/jaffle_shop_demo \
+    --out-root examples/jaffle_shop_demo/datalex-out
+
+# 3. Emit dbt-parseable YAML back, with contracts enforced
+./datalex datalex dbt emit examples/jaffle_shop_demo/datalex-out \
+    --out-dir examples/jaffle_shop_demo/dbt-out
+```
+
+Open `examples/jaffle_shop_demo/datalex-out/sources/jaffle_shop_raw.yaml` —
+every column has its warehouse type, descriptions from the manifest, and a
+`meta.datalex.dbt.unique_id` stamp so re-running the sync never clobbers
+anything you've hand-authored.
+
+## What it does
+
+DataLex treats your data models as code. On top of a stricter YAML
+substrate (the **DataLex** layout — one file per entity, `kind:`-dispatched,
+streaming-safe for 10K+ entities), it gives you:
+
+- **`datalex datalex dbt sync <project>`** — reads `target/manifest.json` + your
+  `profiles.yml`, introspects live column types, and merges them into
+  DataLex YAML. Idempotent: user-authored `description:`, `tags:`,
+  `sensitivity:`, and `tests:` survive re-sync.
+- **`datalex datalex dbt emit`** — writes `sources.yml` and `schema.yml` with
+  `contract.enforced: true` and `data_type:` on every column. `dbt parse`
+  succeeds out of the box.
+- **`datalex datalex emit ddl --dialect ...`** — Postgres, Snowflake, BigQuery,
+  Databricks, MySQL, SQL Server, Redshift. Same source, all dialects.
+- **`datalex datalex diff`** — semantic diff with explicit rename tracking
+  (`previous_name:`), breaking-change gate for CI.
+- **Cross-repo package imports** — pin `acme/warehouse-core@1.4.0` in
+  `imports:`, lockfile + content hash drift detection, Git-or-path
+  resolution, on-disk parse cache for large projects.
+- **Visual studio** — React Flow UI for editing entities, relationships,
+  and metadata; same YAML files as the CLI.
+
+## Supported warehouses
+
+| Warehouse | `dbt sync` introspection | Forward DDL | Reverse engineering |
+|---|:---:|:---:|:---:|
+| DuckDB | ✓ | — | — |
+| PostgreSQL | ✓ | ✓ | ✓ |
+| Snowflake | (fallback) | ✓ | ✓ |
+| BigQuery | (fallback) | ✓ | ✓ |
+| Databricks | (fallback) | ✓ | ✓ |
+| MySQL | (fallback) | ✓ | ✓ |
+| SQL Server / Azure SQL | (fallback) | ✓ | ✓ |
+| Redshift | (fallback) | ✓ | ✓ |
+
+"Fallback" = uses the existing full-schema connector (slower than the
+per-table path but already works today; a narrow introspection path ships
+per-dialect over time).
+
+## Install
+
+```bash
+git clone https://github.com/duckcode-ai/DataLex.git
+cd DataLex
+
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .              # puts `datalex` on PATH
+pip install -e '.[duckdb]'    # add warehouse drivers you need
+
+# optional — only needed for the Visual Studio
+npm --prefix packages/api-server install
+npm --prefix packages/web-app install
+```
+
+Available extras: `duckdb`, `postgres`, `mysql`, `snowflake`,
+`bigquery`, `databricks`, `sqlserver`, `redshift`, or `all`.
+
+Prereqs: Python 3.9+, Git. Node.js 18+ if you want the UI.
+
+## Project layout
+
+```text
+DataLex/
+  packages/
+    core_engine/           # Python: loader, dialects, dbt integration, packages
+      src/datalex_core/
+        _schemas/datalex/  # JSON Schema per `kind:` — bundled with the package
+    cli/                   # `datalex` entry point
+    api-server/            # Node.js API (UI backend)
+    web-app/               # React Flow studio
+  examples/
+    jaffle_shop_demo/      # zero-setup dbt-sync demo (DuckDB)
+  model-examples/          # sample projects and scenario walkthroughs
+  docs/                    # architecture, specs, runbooks
+  tests/                   # unittest suite (core engine + datalex)
+```
+
+## Visual Studio (optional)
+
+If you want the UI on top of your DataLex project, run the two dev servers:
+
+```bash
+# Terminal 1
+npm --prefix packages/api-server run dev
+# Terminal 2
+npm --prefix packages/web-app run dev
+```
+
+Then open `http://localhost:5173`. The UI reads and writes the same YAML
+files the CLI does — no database, no hosted service.
+
+## CI / GitOps
+
+DataLex is designed to live in your repo next to your dbt project.
+A typical CI step:
+
+```bash
+./datalex datalex validate datalex/
+./datalex datalex diff datalex-main/ datalex/ --exit-on-breaking
+./datalex datalex dbt emit datalex/ --out-dir dbt/
+dbt parse
+```
+
+## Documentation
+
+- **[Tutorial: dbt sync in 5 minutes](docs/tutorial-dbt-sync.md)** — the
+  full jaffle_shop walkthrough with explanations.
+- **[DataLex layout reference](docs/datalex-layout.md)** — what each
+  `kind:` file looks like and how the loader discovers them.
+- **[CLI cheat sheet](docs/cli.md)** — every `datalex datalex …` subcommand on
+  one page.
+- **[Architecture](docs/architecture.md)** — core engine modules and
+  end-to-end data flow.
+- Pre-DataLex specs have moved to [docs/archive/](docs/archive/).
+
+## Community
+
+- Discord: [![Join Discord](https://img.shields.io/badge/Discord-Join%20DuckCode%20AI-5865F2?logo=discord&logoColor=white)](https://discord.gg/Dnm6bUvk)
+- Issues: [![GitHub Issues](https://img.shields.io/badge/Issues-Report%20or%20Request-0ea5e9)](https://github.com/duckcode-ai/DataLex/issues)
+- Contributing: `CONTRIBUTING.md`
+- License: [![MIT](https://img.shields.io/badge/License-MIT-22c55e?style=flat-square)](LICENSE)

datalex_cli-0.1.1/datalex_cli.egg-info/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: datalex-cli
+Version: 0.1.1
+Summary: Git-native data modeling for dbt users
+Author-email: DuckCode AI Labs <hello@duckcode.ai>
+License: MIT
+Project-URL: Homepage, https://duckcode.ai
+Project-URL: Repository, https://github.com/duckcode-ai/DataLex
+Project-URL: Issues, https://github.com/duckcode-ai/DataLex/issues
+Keywords: dbt,data-modeling,yaml,git-native,erd,data-warehouse
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: jsonschema>=4.0
+Provides-Extra: duckdb
+Requires-Dist: duckdb>=0.9; extra == "duckdb"
+Provides-Extra: postgres
+Requires-Dist: psycopg2-binary; extra == "postgres"
+Provides-Extra: mysql
+Requires-Dist: mysql-connector-python; extra == "mysql"
+Provides-Extra: snowflake
+Requires-Dist: snowflake-connector-python; extra == "snowflake"
+Provides-Extra: bigquery
+Requires-Dist: google-cloud-bigquery; extra == "bigquery"
+Provides-Extra: databricks
+Requires-Dist: databricks-sql-connector; extra == "databricks"
+Provides-Extra: sqlserver
+Requires-Dist: pyodbc; extra == "sqlserver"
+Provides-Extra: redshift
+Requires-Dist: redshift-connector; extra == "redshift"
+Provides-Extra: all
+Requires-Dist: duckdb>=0.9; extra == "all"
+Requires-Dist: psycopg2-binary; extra == "all"
+Requires-Dist: mysql-connector-python; extra == "all"
+Requires-Dist: snowflake-connector-python; extra == "all"
+Requires-Dist: google-cloud-bigquery; extra == "all"
+Requires-Dist: databricks-sql-connector; extra == "all"
+Requires-Dist: pyodbc; extra == "all"
+Requires-Dist: redshift-connector; extra == "all"
+Dynamic: license-file
+
+<div align="center">
+  <a href="https://duckcode.ai/" target="_blank" rel="noopener noreferrer">
+    <img src="Assets/DataLex.png" alt="DataLex by DuckCode AI Labs" width="220" />
+  </a>
+
+# DataLex
+
+**Git-native data modeling for dbt users.**
+
+Point us at your dbt project and warehouse — we produce versioned, reviewable YAML
+with contracts, lineage, ERDs, and clean round-trip back to dbt.
+
+<p align="center">
+  <a href="https://github.com/duckcode-ai/DataLex/blob/main/LICENSE">
+    <img src="https://img.shields.io/github/license/duckcode-ai/DataLex?style=for-the-badge&color=22c55e" alt="MIT License" />
+  </a>
+  <a href="https://discord.gg/Dnm6bUvk">
+    <img src="https://img.shields.io/badge/Discord-Join%20Community-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord Community" />
+  </a>
+  <a href="https://github.com/duckcode-ai/DataLex/stargazers">
+    <img src="https://img.shields.io/github/stars/duckcode-ai/DataLex?style=for-the-badge&color=f59e0b" alt="GitHub Stars" />
+  </a>
+</p>
+</div>
+
+<p align="center">
+  <img src="Assets/Overview.png" alt="DataLex Visual Studio — file tree, YAML editor, and React Flow ERD on the same entity" width="100%" />
+</p>
+
+## 60-second demo
+
+```bash
+git clone https://github.com/duckcode-ai/DataLex.git
+cd DataLex
+pip install -e '.[duckdb]'
+
+# 1. Build a local DuckDB warehouse (no external credentials)
+python examples/jaffle_shop_demo/setup.py
+
+# 2. Sync the dbt project into DataLex YAML
+./datalex datalex dbt sync examples/jaffle_shop_demo \
+    --out-root examples/jaffle_shop_demo/datalex-out
+
+# 3. Emit dbt-parseable YAML back, with contracts enforced
+./datalex datalex dbt emit examples/jaffle_shop_demo/datalex-out \
+    --out-dir examples/jaffle_shop_demo/dbt-out
+```
+
+Open `examples/jaffle_shop_demo/datalex-out/sources/jaffle_shop_raw.yaml` —
+every column has its warehouse type, descriptions from the manifest, and a
+`meta.datalex.dbt.unique_id` stamp so re-running the sync never clobbers
+anything you've hand-authored.
+
+## What it does
+
+DataLex treats your data models as code. On top of a stricter YAML
+substrate (the **DataLex** layout — one file per entity, `kind:`-dispatched,
+streaming-safe for 10K+ entities), it gives you:
+
+- **`datalex datalex dbt sync <project>`** — reads `target/manifest.json` + your
+  `profiles.yml`, introspects live column types, and merges them into
+  DataLex YAML. Idempotent: user-authored `description:`, `tags:`,
+  `sensitivity:`, and `tests:` survive re-sync.
+- **`datalex datalex dbt emit`** — writes `sources.yml` and `schema.yml` with
+  `contract.enforced: true` and `data_type:` on every column. `dbt parse`
+  succeeds out of the box.
+- **`datalex datalex emit ddl --dialect ...`** — Postgres, Snowflake, BigQuery,
+  Databricks, MySQL, SQL Server, Redshift. Same source, all dialects.
+- **`datalex datalex diff`** — semantic diff with explicit rename tracking
+  (`previous_name:`), breaking-change gate for CI.
+- **Cross-repo package imports** — pin `acme/warehouse-core@1.4.0` in
+  `imports:`, lockfile + content hash drift detection, Git-or-path
+  resolution, on-disk parse cache for large projects.
+- **Visual studio** — React Flow UI for editing entities, relationships,
+  and metadata; same YAML files as the CLI.
+
+## Supported warehouses
+
+| Warehouse | `dbt sync` introspection | Forward DDL | Reverse engineering |
+|---|:---:|:---:|:---:|
+| DuckDB | ✓ | — | — |
+| PostgreSQL | ✓ | ✓ | ✓ |
+| Snowflake | (fallback) | ✓ | ✓ |
+| BigQuery | (fallback) | ✓ | ✓ |
+| Databricks | (fallback) | ✓ | ✓ |
+| MySQL | (fallback) | ✓ | ✓ |
+| SQL Server / Azure SQL | (fallback) | ✓ | ✓ |
+| Redshift | (fallback) | ✓ | ✓ |
+
+"Fallback" = uses the existing full-schema connector (slower than the
+per-table path but already works today; a narrow introspection path ships
+per-dialect over time).
+
+## Install
+
+```bash
+git clone https://github.com/duckcode-ai/DataLex.git
+cd DataLex
+
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .              # puts `datalex` on PATH
+pip install -e '.[duckdb]'    # add warehouse drivers you need
+
+# optional — only needed for the Visual Studio
+npm --prefix packages/api-server install
+npm --prefix packages/web-app install
+```
+
+Available extras: `duckdb`, `postgres`, `mysql`, `snowflake`,
+`bigquery`, `databricks`, `sqlserver`, `redshift`, or `all`.
+
+Prereqs: Python 3.9+, Git. Node.js 18+ if you want the UI.
+
+## Project layout
+
+```text
+DataLex/
+  packages/
+    core_engine/           # Python: loader, dialects, dbt integration, packages
+      src/datalex_core/
+        _schemas/datalex/  # JSON Schema per `kind:` — bundled with the package
+    cli/                   # `datalex` entry point
+    api-server/            # Node.js API (UI backend)
+    web-app/               # React Flow studio
+  examples/
+    jaffle_shop_demo/      # zero-setup dbt-sync demo (DuckDB)
+  model-examples/          # sample projects and scenario walkthroughs
+  docs/                    # architecture, specs, runbooks
+  tests/                   # unittest suite (core engine + datalex)
+```
+
+## Visual Studio (optional)
+
+If you want the UI on top of your DataLex project, run the two dev servers:
+
+```bash
+# Terminal 1
+npm --prefix packages/api-server run dev
+# Terminal 2
+npm --prefix packages/web-app run dev
+```
+
+Then open `http://localhost:5173`. The UI reads and writes the same YAML
+files the CLI does — no database, no hosted service.
+
+## CI / GitOps
+
+DataLex is designed to live in your repo next to your dbt project.
+A typical CI step:
+
+```bash
+./datalex datalex validate datalex/
+./datalex datalex diff datalex-main/ datalex/ --exit-on-breaking
+./datalex datalex dbt emit datalex/ --out-dir dbt/
+dbt parse
+```
+
+## Documentation
+
+- **[Tutorial: dbt sync in 5 minutes](docs/tutorial-dbt-sync.md)** — the
+  full jaffle_shop walkthrough with explanations.
+- **[DataLex layout reference](docs/datalex-layout.md)** — what each
+  `kind:` file looks like and how the loader discovers them.
+- **[CLI cheat sheet](docs/cli.md)** — every `datalex datalex …` subcommand on
+  one page.
+- **[Architecture](docs/architecture.md)** — core engine modules and
+  end-to-end data flow.
+- Pre-DataLex specs have moved to [docs/archive/](docs/archive/).
+
+## Community
+
+- Discord: [![Join Discord](https://img.shields.io/badge/Discord-Join%20DuckCode%20AI-5865F2?logo=discord&logoColor=white)](https://discord.gg/Dnm6bUvk)
+- Issues: [![GitHub Issues](https://img.shields.io/badge/Issues-Report%20or%20Request-0ea5e9)](https://github.com/duckcode-ai/DataLex/issues)
+- Contributing: `CONTRIBUTING.md`
+- License: [![MIT](https://img.shields.io/badge/License-MIT-22c55e?style=flat-square)](LICENSE)